Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added POST /files and store ownership for uploaded files (V-3742) (#14866)
Damian Legawieccbde8fef8d27
diff --git a/.changeset/cli-api-upload.md b/.changeset/cli-api-upload.mdnew file mode 100644index 0000000000..c03ccb6e6a--- /dev/null+++ b/.changeset/cli-api-upload.md@@ -0,0 +1,5 @@+---+"@spree/cli": minor+---++`spree api upload <file>` uploads a file and prints the `signed_id` to pass to the endpoint that uses it. Add `--private` for documents, imports and digital products.diff --git a/.changeset/files-upload-endpoint.md b/.changeset/files-upload-endpoint.mdnew file mode 100644index 0000000000..568984b6ea--- /dev/null+++ b/.changeset/files-upload-endpoint.md@@ -0,0 +1,10 @@+---+"@spree/admin-sdk": minor+"@spree/seller-sdk": minor+"@spree/dashboard": minor+"@spree/dashboard-core": minor+"@spree/dashboard-ui": minor+"@spree/seller-dashboard": minor+---++`directUploads.create()` is replaced by `files.create()` and `files.upload()`, which uploads a file and resolves to a `signed_id` in one call, either straight to storage or in the request itself. The `signed_id` expires after a day. Every parameter that takes one is now named `signed_id` or `<slot>_signed_id` (`avatar_signed_id`, `logo_signed_id`, `attachment_signed_id`, `document_signed_id`, `file_signed_id`, `po_document_signed_id`, …). In `@spree/dashboard-core`, `useDirectUpload` becomes `useFileUpload({ visibility })`, and `signedIdParam` builds the three-state write for an image or document field.diff --git a/.changeset/store-po-document-signed-id.md b/.changeset/store-po-document-signed-id.mdnew file mode 100644index 0000000000..5350bb6ae0--- /dev/null+++ b/.changeset/store-po-document-signed-id.md@@ -0,0 +1,5 @@+---+"@spree/sdk": minor+---++A cart's purchase order document is now set with `po_document_signed_id` instead of `po_document`.diff --git a/docs/api-reference/admin-api/introduction.mdx b/docs/api-reference/admin-api/introduction.mdxindex ffcad6ba57..d0d18db387 100644--- a/docs/api-reference/admin-api/introduction.mdx+++ b/docs/api-reference/admin-api/introduction.mdx@@ -69,4 +69,12 @@ Before integrating, read:- [Authentication](/api-reference/admin-api/authentication) — secret API keys, scopes, and JWT tokens- [Errors](/api-reference/admin-api/errors) — error format and admin-specific codes- [Querying](/api-reference/admin-api/querying) — filtering, sorting, pagination, and `expand`+- [Uploads](/api-reference/admin-api/uploads) — uploading files and passing their `signed_id`- [Spree CLI](/developer/cli/admin-api) — call the Admin API from your terminal++## Opaque values++Some values are references for you to pass along, not data to read. Store and use them exactly as given, and never build or parse them:++- **Image URLs** (`original_url`, `small_url`, …) can change host or format, for example when a store moves to a CDN.+- **`signed_id`** values from [uploads](/api-reference/admin-api/uploads) can change format, and expire after a day.diff --git a/docs/api-reference/admin-api/uploads.mdx b/docs/api-reference/admin-api/uploads.mdxnew file mode 100644index 0000000000..dc7276e263--- /dev/null+++ b/docs/api-reference/admin-api/uploads.mdx@@ -0,0 +1,130 @@+---+title: "Uploading files to the Admin and Seller APIs"+sidebarTitle: "Uploads"+description: "How to upload images, documents and CSV files to Spree, get a signed_id, and attach the file to products, imports, logos and other records."+---++import { Since } from '/snippets/since.mdx';++<Since version="6.0" />++Endpoints that use a file never take its bytes. You upload the file to the files endpoint first, get back a `signed_id`, and pass that `signed_id` to the endpoint that uses the file:++1. Upload the file with `POST /api/v3/admin/files` (or `POST /api/v3/seller/files` in the [Seller API](/api-reference/seller-api/introduction)).+2. Send the returned `signed_id` to the endpoint that uses it — product [media](/developer/core-concepts/media), an import, a logo, a document.++## Uploading with the SDK++`files.upload()` does the whole upload and resolves to the response:++<Tabs>+ <Tab title="SDK">+```typescript+const { signed_id } = await client.files.upload(file, { visibility: 'private' })++await client.imports.create({ type: 'products', attachment_signed_id: signed_id })+```+ </Tab>+ <Tab title="Spree CLI">+```bash+spree api upload ./products.csv --private+```+ </Tab>+</Tabs>++`file` is any `Blob` or `File` — from a file input in the browser, or `fs.openAsBlob(path)` in Node.++## Two ways to send the bytes++Both return the same response.++**Presigned (default).** Send the file's metadata as JSON, then send the bytes with `upload.method` (always `PUT`) to `upload.url`, carrying exactly `upload.headers`. The bytes go straight to storage, so use this for anything large. `checksum` is the file's MD5 digest, base64-encoded; storage checks the bytes against it.++<Tabs>+ <Tab title="SDK">+```typescript+// files.upload() runs both steps; this is what it does underneath.+const upload = await client.files.create({+ filename: 'products.csv',+ content_type: 'text/csv',+ byte_size: 48213,+ checksum: 'rL0Y20zC+Fzt72VPzMSk2A==',+ visibility: 'private',+})++await fetch(upload.upload.url, { method: 'PUT', headers: upload.upload.headers, body: file })+```+ </Tab>+ <Tab title="cURL">+```bash+curl -X POST 'https://api.mystore.com/api/v3/admin/files' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -H 'Content-Type: application/json' \+ -d '{ "filename": "products.csv", "content_type": "text/csv", "byte_size": 48213,+ "checksum": "rL0Y20zC+Fzt72VPzMSk2A==", "visibility": "private" }'+```+ </Tab>+</Tabs>++**Multipart.** Send the bytes in a `file` part of the request itself. The file is stored before the response, so `upload` is `null`. No checksum is needed, but the size limit is lower. This suits scripts and tools that cannot make a second request.++<Tabs>+ <Tab title="SDK">+```typescript+const { signed_id } = await client.files.upload(file, { method: 'multipart' })+```+ </Tab>+ <Tab title="cURL">+```bash+curl -X POST 'https://api.mystore.com/api/v3/admin/files' \+ -H 'X-Spree-API-Key: sk_xxx' \+ -F '[email protected]'+```+ </Tab>+</Tabs>++## The response++```json+{+ "signed_id": "eyJfcmFpbHMiOnsi…",+ "filename": "products.csv",+ "content_type": "text/csv",+ "byte_size": 48213,+ "visibility": "private",+ "expires_at": "2026-10-11T12:00:00.000Z",+ "upload": { "method": "PUT", "url": "https://…", "headers": { "Content-MD5": "…" } }+}+```++- **`signed_id` is opaque.** Pass it back unchanged and never parse it.+- **It expires** at `expires_at`, one day after the upload. An expired or altered `signed_id` is refused with a `422`; upload the file again.+- **The file belongs to your store.** A file uploaded in one store is meant to be used in that store only.++## Visibility++| `visibility` | Use for | Accepted types |+|---|---|---|+| `public` (default) | Images and videos customers see: product media, logos, category images | Web images, videos, CSV |+| `private` | Documents, imports, digital products, purchase orders | Any type |++Attaching a file never moves it between public and private storage, so choose when you upload. Each endpoint still checks the file it receives, so a digital product can be any type while a logo must be an image.++## Size limits++| Upload | Default | Setting |+|---|---|---|+| Presigned | 5 GB | `Spree::Config.max_upload_size` or `SPREE_MAX_UPLOAD_SIZE` (bytes) |+| Multipart | 10 MB | `Spree::Config.max_multipart_upload_size` or `SPREE_MAX_MULTIPART_UPLOAD_SIZE` (bytes) |++## Parameter names++Every parameter that takes an upload is named `signed_id` or `<name>_signed_id`, after the file it sets: `avatar_signed_id`, `logo_signed_id`, `image_signed_id`, `attachment_signed_id`, `document_signed_id`, `file_signed_id`, `po_document_signed_id`. Send `null` to remove a file, or leave the key out to keep it.++## Files that are never used++A file uploaded through the files endpoint that is never attached to anything is deleted after two days by `Spree::Uploads::PurgeUnattachedJob`. Files that belong to no store, such as files from before the 6.0 upgrade that were never attached, are left alone. Schedule it daily (see the [upgrade guide](/developer/upgrades/5.6-to-6.0#file-uploads)). Change the period with `Spree::Config.unattached_upload_retention_days` or `SPREE_UNATTACHED_UPLOAD_RETENTION_DAYS`.++## Image URLs are opaque too++Image URLs in responses (`original_url`, `small_url`, …) can change host or format, for example when a store moves to a CDN. Store and render them as given; never build or parse them.diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlindex c719dbde64..d144b40a58 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -10311,6 +10311,147 @@ paths:schema:type: stringformat: binary+ "/api/v3/admin/files":+ post:+ summary: Upload a file+ tags:+ - Files+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Accepts a file and returns a `signed_id` to send to the endpoint that+ uses it — `signed_id` on product media, `avatar_signed_id` on a+ customer, `attachment_signed_id` on an import, and so on.++ Two ways to send the bytes, one response:++ - **Presigned** (JSON): send the file's metadata, then `PUT` the bytes+ to `upload.url` with exactly `upload.headers`. Use this for anything+ large — the bytes go straight to storage.+ - **Multipart**: send the bytes in a `file` part. The file is stored+ before the response, so `upload` is null. Limited to 10 MB by default.++ `signed_id` is opaque: pass it back unchanged and never parse it. It+ stops being attachable at `expires_at`, one day after the upload.++ `visibility` picks the storage: `public` (the default) for images and+ videos customers see, `private` for documents, imports and digital+ products. Public uploads accept web images, videos and CSV; private+ uploads accept any type. `checksum` is the file's MD5 digest,+ base64-encoded — the storage service verifies the bytes against it.+++ **Required scope:** `write_products` (for API-key authentication).+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ responses:+ '201':+ description: presigned upload target created+ content:+ application/json:+ example:+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--bb0b6973ee0447f02cdcd29af88cf330e909e39c+ filename: products.csv+ content_type: text/csv+ byte_size: 48213+ visibility: private+ expires_at: '2026-01-16T12:00:00.000Z'+ upload:+ method: PUT+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJxcmZsMnNod3YwYmR4cWF3ZWFocDZvYjhlYzh5IiwiY29udGVudF90eXBlIjoidGV4dC9jc3YiLCJjb250ZW50X2xlbmd0aCI6NDgyMTMsImNoZWNrc3VtIjoiaGdKTXJSNkRFQjJYTloxelVRVVJWZz09Iiwic2VydmljZV9uYW1lIjoidGVzdCJ9LCJleHAiOiIyMDI2LTAxLTE1VDEyOjA1OjAwLjAwMFoiLCJwdXIiOiJibG9iX3Rva2VuIn19--6232b64223176120a39db5ee65051c450ce2c899+ headers:+ Content-Type: text/csv+ schema:+ "$ref": "#/components/schemas/FileUpload"+ '422':+ description: content type not allowed for a public upload+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Content type is not included in the list+ details:+ content_type:+ - value: application/x-sh+ code: inclusion+ message: is not included in the list+ specific: false+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ filename:+ type: string+ example: products.csv+ content_type:+ type: string+ example: text/csv+ byte_size:+ type: integer+ example: 48213+ checksum:+ type: string+ description: Base64-encoded MD5 digest of the file+ example: rL0Y20zC+Fzt72VPzMSk2A==+ visibility:+ type: string+ enum:+ - public+ - private+ default: public+ file:+ type: string+ format: binary+ description: The bytes, for a multipart upload+ required:+ - filename+ - content_type+ multipart/form-data:+ schema:+ type: object+ properties:+ filename:+ type: string+ example: products.csv+ content_type:+ type: string+ example: text/csv+ byte_size:+ type: integer+ example: 48213+ checksum:+ type: string+ description: Base64-encoded MD5 digest of the file+ example: rL0Y20zC+Fzt72VPzMSk2A==+ visibility:+ type: string+ enum:+ - public+ - private+ default: public+ file:+ type: string+ format: binary+ description: The bytes, for a multipart upload+ required:+ - filename+ - content_type"/api/v3/admin/orders/{order_id}/fulfillments":get:summary: List fulfillments@@ -12487,8 +12628,8 @@ paths:- api_key: []bearer_auth: []description: |-- Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`- and pass the returned `signed_id` as `attachment`. On success the import is in the+ Queues a CSV import. Upload the file first via `POST /api/v3/admin/files`+ and pass the returned `signed_id` as `attachment_signed_id`. On success the import is in the`mapping` state and the response carries the mapping payload: `schema_fields`(the canonical columns for the type), `csv_headers`, a `sample_row`, and theauto-assigned `mappings`.@@ -12884,7 +13025,7 @@ paths:type: objectrequired:- type- - attachment+ - attachment_signed_idproperties:type:type: string@@ -12900,9 +13041,9 @@ paths:description: 'For `price_list_prices` imports: the price list therows are merged into. Must belong to the current store.'example: pl_86Rf07xd4z- attachment:+ attachment_signed_id:type: string- description: ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.+ description: The `signed_id` returned by POST /api/v3/admin/files.example: eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signeddelimiter:type: string@@ -22390,7 +22531,7 @@ paths:updated_at: '2026-01-15T12:00:00.000Z'provider_type:provider_name: File- download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJ0Z252N2l0MG55YnkwbHhkczg5Y2hteTd6aXlvIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRoaW5raW5nLWNhdC5qcGdcIjsgZmlsZW5hbWUqPVVURi04Jyd0aGlua2luZy1jYXQuanBnIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--5b8cceb2276ef40ff0ebf9b7ad17b0b385fee97d/thinking-cat.jpg+ download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJ0Z252N2l0MG55YnkwbHhkczg5Y2hteTd6aXlvIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRoaW5raW5nLWNhdC5qcGdcIjsgZmlsZW5hbWUqPVVURi04Jyd0aGlua2luZy1jYXQuanBnIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--b47efdca6924cbe4605e0d19700f1da4ed928526/thinking-cat.jpgeffective_authorized_clicks: 5effective_authorized_days: 7meta:@@ -39765,8 +39906,8 @@ paths:until verified.`country_code` and `state_code` say where the certificate holds — omit both for one valid- everywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage- signed blob id obtained from `POST /api/v3/admin/direct_uploads`.+ everywhere, give only the country for one valid throughout it. `document_signed_id` takes the+ `signed_id` returned by `POST /api/v3/admin/files`.**Required scope:** `write_customers` (for API-key authentication).@@ -39781,21 +39922,12 @@ paths:secretKey: 'sk_xxx',})- // Upload the document first, then pass the signed id.- const { signed_id } = await client.directUploads.create({- blob: {- filename: 'resale.pdf',- byte_size: 18_345,- checksum: 'Base64EncodedMD5==',- content_type: 'application/pdf',- },- })-+ // `signed_id` comes from `client.files.upload(file, { visibility: 'private' })`.const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {certificate_number: 'DE-RESALE-7',reason_code: 'resale',country_code: 'DE',- document: signed_id,+ document_signed_id: signed_id,})- lang: bashlabel: Spree CLI@@ -39870,9 +40002,9 @@ paths:type: stringnullable: trueexample: Finanzamt Berlin- document:+ document_signed_id:type: string- description: ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.+ description: The `signed_id` returned by POST /api/v3/admin/files.example: eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signedrequired:- certificate_number@@ -42635,13 +42767,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d240e11dadf33f20a28429eafe85c73373c48af9/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f906fd4aebefb1b0cc6679e36b767f62c6c9388/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f59f774c3c1dd795fa879eea20a37ce0162e3c1/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f4a4f600e48ddb944ac3840029b3eb570007cf63/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7f9aeba30e7a608af78d60a2c5b7f29c248b0f6e/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--71db2ee0b2513e89488e3f733c50830d6e75e706/thinking-cat.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/thinking-cat.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--442343dfe070937dea6e93cdcd43a359693380b5/thinking-cat.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f44f3ea1d1a5ff569a5f638dcc1145a780497006/thinking-cat.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b56d7c8dd01d809c7daf6d19b80d6ae606467fae/thinking-cat.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1b6c9cbee354d1e94401da9990867da1975ef253/thinking-cat.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7dab3bb82bf4e749a1e26fd97e49e2a7a5922177/thinking-cat.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--01255a15bd06c290c3fb787ae920d7d19723cc10/thinking-cat.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -42649,10 +42781,10 @@ paths:filename: thinking-cat.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--a6c0fa8c4cf89e4d1fc0aa429a080d07fc3392e7/thinking-cat.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--bb0b6973ee0447f02cdcd29af88cf330e909e39cviewable_id: prod_UkLWZg9DAJ- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/thinking-cat.jpg?disposition=attachmentmetadata: {}viewable_type: productmeta:@@ -42686,7 +42818,7 @@ paths:bearer_auth: []description: |-Adds a file to the library without placing it on anything. Upload the- file first through the direct-upload endpoint, then send the signed id+ file first through `POST /api/v3/admin/files`, then send the signed idhere. Put the file on a product by posting to that product's media withthis record's id as `source_media_id`.@@ -42723,13 +42855,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/library-upload.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d240e11dadf33f20a28429eafe85c73373c48af9/library-upload.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f906fd4aebefb1b0cc6679e36b767f62c6c9388/library-upload.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f59f774c3c1dd795fa879eea20a37ce0162e3c1/library-upload.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f4a4f600e48ddb944ac3840029b3eb570007cf63/library-upload.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7f9aeba30e7a608af78d60a2c5b7f29c248b0f6e/library-upload.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--71db2ee0b2513e89488e3f733c50830d6e75e706/library-upload.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/library-upload.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--442343dfe070937dea6e93cdcd43a359693380b5/library-upload.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f44f3ea1d1a5ff569a5f638dcc1145a780497006/library-upload.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b56d7c8dd01d809c7daf6d19b80d6ae606467fae/library-upload.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1b6c9cbee354d1e94401da9990867da1975ef253/library-upload.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7dab3bb82bf4e749a1e26fd97e49e2a7a5922177/library-upload.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--01255a15bd06c290c3fb787ae920d7d19723cc10/library-upload.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -42737,10 +42869,10 @@ paths:filename: library-upload.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/library-upload.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--a6c0fa8c4cf89e4d1fc0aa429a080d07fc3392e7/library-upload.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--9df67009f2b4fc89684f00759178a9bb404511beviewable_id:- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/library-upload.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/library-upload.jpg?disposition=attachmentmetadata: {}viewable_type:schema:@@ -42753,7 +42885,7 @@ paths:properties:signed_id:type: string- description: Direct-upload signed id for the file.+ description: The `signed_id` returned by POST /api/v3/admin/files.alt:type: stringexample: Folded on a table@@ -42959,13 +43091,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d240e11dadf33f20a28429eafe85c73373c48af9/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f906fd4aebefb1b0cc6679e36b767f62c6c9388/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f59f774c3c1dd795fa879eea20a37ce0162e3c1/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f4a4f600e48ddb944ac3840029b3eb570007cf63/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7f9aeba30e7a608af78d60a2c5b7f29c248b0f6e/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--71db2ee0b2513e89488e3f733c50830d6e75e706/thinking-cat.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/thinking-cat.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--442343dfe070937dea6e93cdcd43a359693380b5/thinking-cat.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f44f3ea1d1a5ff569a5f638dcc1145a780497006/thinking-cat.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b56d7c8dd01d809c7daf6d19b80d6ae606467fae/thinking-cat.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1b6c9cbee354d1e94401da9990867da1975ef253/thinking-cat.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7dab3bb82bf4e749a1e26fd97e49e2a7a5922177/thinking-cat.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--01255a15bd06c290c3fb787ae920d7d19723cc10/thinking-cat.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -42973,10 +43105,10 @@ paths:filename: thinking-cat.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--a6c0fa8c4cf89e4d1fc0aa429a080d07fc3392e7/thinking-cat.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--bb0b6973ee0447f02cdcd29af88cf330e909e39cviewable_id: prod_UkLWZg9DAJ- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/thinking-cat.jpg?disposition=attachmentmetadata: {}viewable_type: productmeta:@@ -43047,13 +43179,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d240e11dadf33f20a28429eafe85c73373c48af9/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f906fd4aebefb1b0cc6679e36b767f62c6c9388/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f59f774c3c1dd795fa879eea20a37ce0162e3c1/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f4a4f600e48ddb944ac3840029b3eb570007cf63/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7f9aeba30e7a608af78d60a2c5b7f29c248b0f6e/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--71db2ee0b2513e89488e3f733c50830d6e75e706/thinking-cat.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/thinking-cat.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--442343dfe070937dea6e93cdcd43a359693380b5/thinking-cat.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f44f3ea1d1a5ff569a5f638dcc1145a780497006/thinking-cat.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b56d7c8dd01d809c7daf6d19b80d6ae606467fae/thinking-cat.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1b6c9cbee354d1e94401da9990867da1975ef253/thinking-cat.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7dab3bb82bf4e749a1e26fd97e49e2a7a5922177/thinking-cat.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--01255a15bd06c290c3fb787ae920d7d19723cc10/thinking-cat.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -43061,10 +43193,10 @@ paths:filename: thinking-cat.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--a6c0fa8c4cf89e4d1fc0aa429a080d07fc3392e7/thinking-cat.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--bb0b6973ee0447f02cdcd29af88cf330e909e39cviewable_id: prod_gbHJdmfrXB- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--75c79f2e42d5b1d5a50e62b48c3d6ec05583ea85/thinking-cat.jpg?disposition=attachmentmetadata: {}viewable_type: productschema:@@ -43209,13 +43341,13 @@ paths:video_embed_url:video_url:poster_url:- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/thinking-cat.jpg- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d240e11dadf33f20a28429eafe85c73373c48af9/thinking-cat.jpg- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f906fd4aebefb1b0cc6679e36b767f62c6c9388/thinking-cat.jpg- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f59f774c3c1dd795fa879eea20a37ce0162e3c1/thinking-cat.jpg- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f4a4f600e48ddb944ac3840029b3eb570007cf63/thinking-cat.jpg- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7f9aeba30e7a608af78d60a2c5b7f29c248b0f6e/thinking-cat.jpg- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--71db2ee0b2513e89488e3f733c50830d6e75e706/thinking-cat.jpg+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/thinking-cat.jpg+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--442343dfe070937dea6e93cdcd43a359693380b5/thinking-cat.jpg+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--f44f3ea1d1a5ff569a5f638dcc1145a780497006/thinking-cat.jpg+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--b56d7c8dd01d809c7daf6d19b80d6ae606467fae/thinking-cat.jpg+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1b6c9cbee354d1e94401da9990867da1975ef253/thinking-cat.jpg+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--7dab3bb82bf4e749a1e26fd97e49e2a7a5922177/thinking-cat.jpg+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--01255a15bd06c290c3fb787ae920d7d19723cc10/thinking-cat.jpgexternal_references: {}created_at: '2026-01-15T12:00:00.000Z'updated_at: '2026-01-15T12:00:00.000Z'@@ -43223,10 +43355,10 @@ paths:filename: thinking-cat.jpgcontent_type: image/jpegbyte_size: 18090- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--a6c0fa8c4cf89e4d1fc0aa429a080d07fc3392e7/thinking-cat.jpg+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--9df67009f2b4fc89684f00759178a9bb404511beviewable_id: variant_gbHJdmfrXB- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/thinking-cat.jpg?disposition=attachment+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--b8a5821c31708931dc058b1d7c96177aaef86b0c/thinking-cat.jpg?disposition=attachmentmetadata: {}viewable_type: variantmeta:@@ -48022,16 +48154,16 @@ paths:type: stringformat: date-timenullable: true- logo:+ logo_signed_id:type: stringnullable: true- description: ActiveStorage signed id of a direct-uploaded file.- Send `null` to remove the attachment, or omit the key to leave- it alone. Same for `square_logo` and `cover_photo`.- square_logo:+ description: The `signed_id` returned by POST /api/v3/admin/files.+ Send `null` to remove the image, or omit the key to leave it alone.+ Same for `square_logo_signed_id` and `cover_photo_signed_id`.+ square_logo_signed_id:type: stringnullable: true- cover_photo:+ cover_photo_signed_id:type: stringnullable: truebilling_address:@@ -51707,6 +51839,9 @@ tags:previews, publishing and history'- name: Exportsdescription: Async CSV exports of admin resources+- name: Files+ description: Uploading the files that product media, imports, logos and documents+ use- name: Fulfillmentsdescription: Order fulfillments — shipments, fulfill, cancel, resume, split- name: Gift Cards@@ -55102,6 +55237,51 @@ components:- created_at- updated_atx-typelizer: true+ FileUpload:+ type: object+ properties:+ signed_id:+ type: string+ filename:+ type: string+ content_type:+ type: string+ byte_size:+ type: number+ visibility:+ type: string+ enum:+ - public+ - private+ expires_at:+ type: string+ upload:+ allOf:+ - "$ref": "#/components/schemas/FileUploadTarget"+ nullable: true+ required:+ - signed_id+ - filename+ - content_type+ - byte_size+ - visibility+ - expires_at+ - upload+ x-typelizer: true+ FileUploadTarget:+ type: object+ properties:+ method:+ type: string+ url:+ type: string+ headers:+ type: object+ required:+ - method+ - url+ - headers+ x-typelizer: trueFreightSummaryLine:type: objectproperties:diff --git a/docs/api-reference/seller-api/introduction.mdx b/docs/api-reference/seller-api/introduction.mdxindex a0ccd5f6ae..d9658e50c5 100644--- a/docs/api-reference/seller-api/introduction.mdx+++ b/docs/api-reference/seller-api/introduction.mdx@@ -81,8 +81,8 @@ const { data: products } = await client.products.list({ limit: 25 })<Card title="Stock locations" icon="warehouse">Manage where they keep stock, and so where returns are sent.</Card>- <Card title="Uploads" icon="upload">- Presign direct uploads for the documents onboarding asks for.+ <Card title="Files" icon="upload" href="/api-reference/admin-api/uploads">+ Upload the logos, documents and CSV files a profile, submission or import uses.</Card></CardGroup>diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yamlindex 52a2ed33fd..460f7f317f 100644--- a/docs/api-reference/seller.yaml+++ b/docs/api-reference/seller.yaml@@ -727,7 +727,7 @@ paths:`X-Spree-Seller-Id`, because the account is the same whichever sellerthey are acting for.- `avatar` takes an ActiveStorage direct-upload signed id to set the+ `avatar_signed_id` takes the `signed_id` from `POST /files` to set thephoto, or `null` to remove it; omit it to leave the current one alone.`email` is identity-bound and cannot be changed here.parameters: []@@ -765,7 +765,7 @@ paths:message: Avatar has an invalid content type (authorized contenttypes are PNG, JPG, GIF, WEBP)details:- avatar:+ avatar_signed_id:- has an invalid content type (authorized content types are PNG,JPG, GIF, WEBP)schema:@@ -796,10 +796,11 @@ paths:type: stringexample: dedescription: Panel display language, as a code the panel ships.- avatar:+ avatar_signed_id:type: stringnullable: true- description: Direct-upload signed id, or `null` to remove the photo.+ description: The `signed_id` returned by POST /files, or `null`+ to remove the photo."/api/v3/seller/countries":get:summary: List countries@@ -13421,8 +13422,8 @@ paths:needs to correct something submits again rather than editing, and thelatest one counts.- `file` is **not** a multipart upload — it is the `signed_id` returned by- `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage+ `file_signed_id` is the `signed_id` returned by+ `POST /api/v3/seller/files`, so the bytes are already in storageby the time this runs.An attestation is accepted on the spot; a requirement the operator@@ -13474,10 +13475,10 @@ paths:type: stringdescription: A reference number or external identifier, for requirementsthat ask for one- file:+ file_signed_id:type: string- description: A direct-upload `signed_id`, for requirements that- ask for a document+ description: The `signed_id` returned by POST /files, for requirements+ that ask for a document"/api/v3/seller/requirement_submissions/{id}/download":parameters:- name: id@@ -14663,14 +14664,15 @@ paths:registration_number:type: stringnullable: true- logo:+ logo_signed_id:type: stringnullable: true- description: ActiveStorage signed id; `null` removes the attachment- square_logo:+ description: The `signed_id` returned by POST /files; `null` removes+ the image+ square_logo_signed_id:type: stringnullable: true- cover_photo:+ cover_photo_signed_id:type: stringnullable: trueaccept_terms:@@ -15390,27 +15392,28 @@ paths:message: Admin user not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/direct_uploads":+ "/api/v3/seller/files":post:- summary: Create a direct upload+ summary: Upload a filetags:- - Uploads+ - Filessecurity:- bearer_auth: []description: |- Presigns an upload target for a file the seller is about to send.-- Three steps: post the file's metadata here, `PUT` the bytes to the- returned `direct_upload.url` with the headers it names, then send the- returned `signed_id` wherever the file belongs — as a requirement- submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the- profile.+ Accepts a file and returns a `signed_id` to send wherever the file+ belongs — as a requirement submission's `file_signed_id`, or as+ `logo_signed_id`, `square_logo_signed_id` or `cover_photo_signed_id` on+ the profile. The file is attached to nothing at this point; the+ endpoint that takes the `signed_id` is the one that checks ownership.- The blob is attached to nothing at this point. The endpoint that consumes- the `signed_id` is the one that checks ownership.+ Send the file's metadata as JSON, then `PUT` the bytes to `upload.url`+ with exactly `upload.headers`; or send small files (10 MB by default)+ as a multipart `file` part, in which case `upload` is null.- `checksum` is the file's MD5 digest, base64-encoded — the storage service- verifies the upload against it.+ `signed_id` is opaque and expires at `expires_at`, one day after the+ upload. `visibility` is `public` (the default, web images, videos and+ CSV only) or `private` (any type). `checksum` is the file's MD5+ digest, base64-encoded.parameters:- name: X-Spree-Seller-Idin: header@@ -15423,42 +15426,81 @@ paths:content:application/json:example:- direct_upload:- url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--1f5050701bdb56c56ae8346d9fef78a0405b680c+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwiZXhwIjoiMjAyNi0wMS0xNlQxMjowMDowMC4wMDBaIiwicHVyIjoiYmxvYl9pZCJ9fQ==--bb0b6973ee0447f02cdcd29af88cf330e909e39c+ filename: registration.pdf+ content_type: application/pdf+ byte_size: 51234+ visibility: private+ expires_at: '2026-01-16T12:00:00.000Z'+ upload:+ method: PUT+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiI4NDFrenlvbTQ5cnRhcDk0cmZxbGV6dnM1cGJsIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--8107f48df9ba51d19f7688d473fda995d4063f66headers:Content-Type: application/pdf- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3eschema:- "$ref": "#/components/schemas/DirectUploadResponse"+ "$ref": "#/components/schemas/FileUpload"requestBody:content:application/json:schema:type: objectproperties:- blob:- type: object- properties:- filename:- type: string- example: registration.pdf- byte_size:- type: integer- example: 51234- checksum:- type: string- description: Base64-encoded MD5 digest of the file- example: rL0Y20zC+Fzt72VPzMSk2A==- content_type:- type: string- example: application/pdf- required:- - filename- - byte_size- - checksum- - content_type+ filename:+ type: string+ example: registration.pdf+ content_type:+ type: string+ example: application/pdf+ byte_size:+ type: integer+ example: 51234+ checksum:+ type: string+ description: Base64-encoded MD5 digest of the file+ example: rL0Y20zC+Fzt72VPzMSk2A==+ visibility:+ type: string+ enum:+ - public+ - private+ default: public+ file:+ type: string+ format: binary+ description: The bytes, for a multipart upload+ required:+ - filename+ - content_type+ multipart/form-data:+ schema:+ type: object+ properties:+ filename:+ type: string+ example: registration.pdf+ content_type:+ type: string+ example: application/pdf+ byte_size:+ type: integer+ example: 51234+ checksum:+ type: string+ description: Base64-encoded MD5 digest of the file+ example: rL0Y20zC+Fzt72VPzMSk2A==+ visibility:+ type: string+ enum:+ - public+ - private+ default: public+ file:+ type: string+ format: binary+ description: The bytes, for a multipart uploadrequired:- - blob+ - filename+ - content_type"/api/v3/seller/balances":get:summary: List balances@@ -20322,8 +20364,8 @@ tags:description: Where the seller keeps stock, and so where their returns are sent- name: Teamdescription: Who runs this seller, and the invitations nobody has accepted yet-- name: Uploads- description: Presigned direct uploads for the documents onboarding asks for+- name: Files+ description: Uploading the files a profile, a submission or an import usescomponents:securitySchemes:bearer_auth:@@ -20761,31 +20803,6 @@ components:- iso- iso3- name- DirectUploadResponse:- type: object- description: A presigned upload target. PUT the file to `direct_upload.url`- with the given headers, then send `signed_id` as the submission's `file`.- properties:- signed_id:- type: string- description: Send this as a submission's `file`- example: eyJfcmFpbHMiOnsibWVzc2FnZSI6...- direct_upload:- type: object- properties:- url:- type: string- example: https://storage.example.com/uploads/abc123- headers:- type: object- additionalProperties:- type: string- required:- - url- - headers- required:- - signed_id- - direct_uploadAuthProvidersResponse:type: objectdescription: Sign-in methods this marketplace offers sellers, for the login@@ -21607,6 +21624,51 @@ components:- byte_size- download_urlx-typelizer: true+ FileUpload:+ type: object+ properties:+ signed_id:+ type: string+ filename:+ type: string+ content_type:+ type: string+ byte_size:+ type: number+ visibility:+ type: string+ enum:+ - public+ - private+ expires_at:+ type: string+ upload:+ allOf:+ - "$ref": "#/components/schemas/FileUploadTarget"+ nullable: true+ required:+ - signed_id+ - filename+ - content_type+ - byte_size+ - visibility+ - expires_at+ - upload+ x-typelizer: true+ FileUploadTarget:+ type: object+ properties:+ method:+ type: string+ url:+ type: string+ headers:+ type: object+ required:+ - method+ - url+ - headers+ x-typelizer: trueFulfillmentItem:type: objectproperties:diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 65ea252a69..398e0351b6 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -15049,6 +15049,51 @@ components:- amount- display_amountx-typelizer: true+ FileUpload:+ type: object+ properties:+ signed_id:+ type: string+ filename:+ type: string+ content_type:+ type: string+ byte_size:+ type: number+ visibility:+ type: string+ enum:+ - public+ - private+ expires_at:+ type: string+ upload:+ allOf:+ - "$ref": "#/components/schemas/FileUploadTarget"+ nullable: true+ required:+ - signed_id+ - filename+ - content_type+ - byte_size+ - visibility+ - expires_at+ - upload+ x-typelizer: true+ FileUploadTarget:+ type: object+ properties:+ method:+ type: string+ url:+ type: string+ headers:+ type: object+ required:+ - method+ - url+ - headers+ x-typelizer: trueFreightSummary:type: objectproperties:diff --git a/docs/developer/core-concepts/media.mdx b/docs/developer/core-concepts/media.mdxindex 184d951a7e..4babcfc924 100644--- a/docs/developer/core-concepts/media.mdx+++ b/docs/developer/core-concepts/media.mdx@@ -147,8 +147,9 @@ import { createAdminClient } from '@spree/admin-sdk'const client = createAdminClient({ baseUrl, secretKey })-// `signed_id` comes from a direct upload; see the Active Storage docs for-// generating one client-side.+// `signed_id` comes from uploading the file first; see Uploads.+const { signed_id: signedBlobId } = await client.files.upload(file)+const media = await client.products.media.create('prod_86Rf07xd4z', {signed_id: signedBlobId,alt: 'Front view',@@ -171,7 +172,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/medi#### Creating media from a remote URL-When the image already lives at a public URL, pass `url` instead of a `signed_id` — Spree fetches the remote file and stores it as product media, so you skip the direct-upload step entirely.+When the image already lives at a public URL, pass `url` instead of a `signed_id` — Spree fetches the remote file and stores it as product media, so you skip the [upload](/api-reference/admin-api/uploads) step entirely.<CodeGroup>diff --git a/docs/developer/core-concepts/products.mdx b/docs/developer/core-concepts/products.mdxindex 760479975d..63d5b646ac 100644--- a/docs/developer/core-concepts/products.mdx+++ b/docs/developer/core-concepts/products.mdx@@ -846,14 +846,10 @@ You attach assets to a variant from the product's **Digital files** card in the<CodeGroup>```typescript Admin SDK-// 1. Ask for a private-storage upload slot, then PUT the file to the returned URL.-const { direct_upload, signed_id } = await adminClient.directUploads.create({- private: true, // digital files are only ever served through a signed link- blob: { filename: 'guide.pdf', byte_size: file.size, checksum, content_type: 'application/pdf' },-})-await fetch(direct_upload.url, { method: 'PUT', headers: direct_upload.headers, body: file })+// 1. Upload the file to private storage — digital files are only ever served through a signed link.+const { signed_id } = await adminClient.files.upload(file, { visibility: 'private' })-// 2. Attach the uploaded blob to the product's default variant.+// 2. Attach it to the product's default variant.await adminClient.products.digitalAssets.create('prod_86Rf07xd4z', {signed_id,authorized_clicks: 5, // optional — omit to inherit the store default@@ -871,7 +867,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/digi</CodeGroup><Warning>-Digital files must be uploaded to **private storage**. The Admin API refuses a blob that landed on the public service — attaching never moves a file between services, so a public upload would stay publicly readable while looking attached. Request the direct upload with `private: true`.+Digital files must be uploaded to **private storage**. The Admin API refuses a blob that landed on the public service — attaching never moves a file between services, so a public upload would stay publicly readable while looking attached. Upload it with `visibility: 'private'` (see [Uploads](/api-reference/admin-api/uploads)).</Warning>Replacing an asset's file keeps every download link that was already issued working: links resolve through the asset, not the underlying blob, so a merchant can swap a corrected file mid‑sale without breaking anyone's access.diff --git a/docs/developer/dashboard/public-api.mdx b/docs/developer/dashboard/public-api.mdxindex e28c96c6a4..961226b613 100644--- a/docs/developer/dashboard/public-api.mdx+++ b/docs/developer/dashboard/public-api.mdx@@ -90,7 +90,7 @@ import {useGlobalSearch, // global search query stateuseCountries,useCustomFields,- useDirectUpload, // ActiveStorage direct uploads+ useFileUpload, // uploads a file through POST /files, resolves to its signed_iduseExport, // CSV export job lifecycleuseResourceKey, // store-scoped query key — use it for every custom queryuseResourceMutation, // useMutation wrapper with 422 handling@@ -105,6 +105,7 @@ import {import {filtersToRansack, // converts table filter state → Ransack paramsmapSpreeErrorsToForm, // 422 response → form.setError+ signedIdParam, // image/document field → `<name>_signed_id` (set, `null` to remove, or omitted)// formattersformatPrice, // Price object → display stringformatStoreDateTime, // ISO string → wall-clock in the store's timezonediff --git a/docs/developer/deployment/assets.mdx b/docs/developer/deployment/assets.mdxindex 201f28b2a8..4796f02692 100644--- a/docs/developer/deployment/assets.mdx+++ b/docs/developer/deployment/assets.mdx@@ -19,7 +19,7 @@ Set the following environment variables:### CORS Configuration-The Admin Dashboard uses direct uploads. Configure CORS on your S3 bucket to allow this:+The Admin Dashboard uploads files straight to storage. Configure CORS on your S3 bucket to allow this:1. Go to your S3 bucket in AWS Console2. Click on "Permissions" tab@@ -56,7 +56,7 @@ Set the following environment variables:### CORS Configuration-Configure CORS on your R2 bucket for direct uploads:+Configure CORS on your R2 bucket so files can be uploaded straight to it:1. Go to your R2 bucket in Cloudflare Console2. Click on "Settings" tabdiff --git a/docs/developer/how-to/build-a-b2b-store.mdx b/docs/developer/how-to/build-a-b2b-store.mdxindex dcab1601e5..f9ea15643d 100644--- a/docs/developer/how-to/build-a-b2b-store.mdx+++ b/docs/developer/how-to/build-a-b2b-store.mdx@@ -626,18 +626,16 @@ curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \-d '{ "po_number": "PO-2026-0418" }'# Attaching the document: ask for an upload URL, upload the file there,-# then send the returned signed_id as po_document on a cart update+# then send the returned signed_id as po_document_signed_id on a cart updatecurl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/po_document' \-H 'X-Spree-API-Key: pk_xxx' \-H "Authorization: Bearer $CUSTOMER_JWT" \-H 'Content-Type: application/json' \-d '{- "blob": {- "filename": "PO-2026-0418.pdf",- "byte_size": 48213,- "checksum": "BASE64_MD5",- "content_type": "application/pdf"- }+ "filename": "PO-2026-0418.pdf",+ "byte_size": 48213,+ "checksum": "BASE64_MD5",+ "content_type": "application/pdf"}'```@@ -820,7 +818,7 @@ const certificate = await adminClient.companies.taxExemptionCertificates.create(country_code: 'US',state_code: 'CA',expires_at: '2027-12-31',- document: signedId, // from adminClient.directUploads.create()+ document_signed_id: signedId, // from adminClient.files.upload(file, { visibility: 'private' })})await adminClient.companies.taxExemptionCertificates.verify('comp_xxx', certificate.id)diff --git a/docs/developer/how-to/build-a-marketplace.mdx b/docs/developer/how-to/build-a-marketplace.mdxindex 247136fe01..6645e00eb8 100644--- a/docs/developer/how-to/build-a-marketplace.mdx+++ b/docs/developer/how-to/build-a-marketplace.mdx@@ -789,7 +789,7 @@ The chosen seller travels as `X-Spree-Seller-Id`. The store is derived from the| `orders` | List and detail, plus `cancel`, `address`, nested `fulfillments`, `deliveries`, `labels`, `returns`, `exchanges`, `claims`, `notes` || `balances`, `transfers`, `payouts` | Read-only — written by fulfilment and the sweep, never by the seller || `deliveryMethods`, `packageTypes`, `stockLocations` | How and from where they ship |-| `imports`, `exports`, `directUploads` | Bulk listing by CSV, and CSV of what they sold |+| `imports`, `exports`, `files` | Bulk listing by CSV, and CSV of what they sold || `productTypes`, `deliveryProfiles`, `deliveryZones`, `returnReasons`, `claimReasons`, `trackingCarriers`, `countries` | Read-only marketplace vocabulary a seller picks from |Two asymmetries are worth noticing, because both are deliberate:diff --git a/docs/developer/how-to/sell-digital-products.mdx b/docs/developer/how-to/sell-digital-products.mdxindex bf4a16df3f..814e28fb0b 100644--- a/docs/developer/how-to/sell-digital-products.mdx+++ b/docs/developer/how-to/sell-digital-products.mdx@@ -48,12 +48,8 @@ A product's delivery profile is auto-assigned when it is created — from its prUpload the file to **private storage** and attach it to the variant as a digital asset. Private storage matters: a digital file is only ever served through a short-lived signed link, so the Admin API refuses a blob that landed on the public bucket.```typescript Admin SDK-// Request a private upload slot, PUT the file, then attach the blob.-const { direct_upload, signed_id } = await adminClient.directUploads.create({- private: true,- blob: { filename: 'guide.pdf', byte_size: file.size, checksum, content_type: 'application/pdf' },-})-await fetch(direct_upload.url, { method: 'PUT', headers: direct_upload.headers, body: file })+// Upload the file to private storage, then attach it.+const { signed_id } = await adminClient.files.upload(file, { visibility: 'private' })await adminClient.products.digitalAssets.create('prod_86Rf07xd4z', { signed_id })```diff --git a/docs/developer/sdk/admin/resources.mdx b/docs/developer/sdk/admin/resources.mdxindex ac14bd5b1e..5321ebc97a 100644--- a/docs/developer/sdk/admin/resources.mdx+++ b/docs/developer/sdk/admin/resources.mdx@@ -91,7 +91,7 @@ await client.customers.addresses.create('cus_xxx', {| `client.countries` | List and read countries (for address dropdowns). || `client.customFieldDefinitions` | CRUD on [custom field](/developer/core-concepts/metafields) definitions. || `client.exports` | Create and track CSV exports (products, orders, customers, …). |-| `client.directUploads` | Pre-signed Active Storage uploads (used by media flows). |+| `client.files` | File uploads — `files.upload()` returns the `signed_id` other endpoints take. See [Uploads](/api-reference/admin-api/uploads). |## Platform & accessdiff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdxindex 6bac0a07f7..93cf410c2b 100644--- a/docs/developer/upgrades/5.6-to-6.0.mdx+++ b/docs/developer/upgrades/5.6-to-6.0.mdx@@ -205,6 +205,14 @@ bundle exec rake spree:upgrade:migrate_country_state_codesCountries and states are no longer database records in 6.0. Addresses, delivery zone members, market countries, stock locations and stores now name them by ISO code (`country_code`, `state_code`), and this task fills those columns from the old `country_id` / `state_id` references. The old `country_iso` / `state_abbr` names still work on addresses for one release.+### Record which store owns every uploaded file++```bash+bundle exec rake spree:uploads:assign_stores+```++Every uploaded file now records the store that owns it (`active_storage_blobs.store_id`). New uploads get it when they are made; this task gives existing files the store of the record they are attached to. A file attached in more than one store is listed and left alone for you to resolve. Safe to re-run at any time.+## Enable Active Record encryptionSpree encrypts payment gateway and integration secrets, webhook endpoint signing secrets, payment gateway customer IDs and the OAuth tokens on user identities with [Active Record encryption](https://guides.rubyonrails.org/active_record_encryption.html) — but only when encryption keys are configured. Without keys these values are stored in plain text. New 6.0 projects get keys at setup; upgraded applications need to add them.@@ -501,6 +509,39 @@ one. An order whose every parcel was recalled now reads`fulfillment_status: unfulfilled` rather than `canceled`; only a canceledorder reads `canceled`.+## File uploads++`POST /direct_uploads` is removed from the Admin and Seller APIs. Upload through `POST /files` instead ([Uploads](/api-reference/admin-api/uploads)): the request is flat (`filename`, `content_type`, `byte_size`, `checksum`, `visibility`), the bytes go to `upload.url`, and small files can be sent in the request itself. In the SDKs, `directUploads.create()` becomes `files.upload(file, { visibility })`; `private: true` becomes `visibility: 'private'`.++The `signed_id` an upload returns now **expires after a day** (`expires_at`). Store the file's record, not the `signed_id`.++Every parameter that takes a `signed_id` is renamed to `<name>_signed_id`:++| Endpoint | Before | After |+|---|---|---|+| Admin `/me`, Seller `/me`, Admin customers | `avatar` | `avatar_signed_id` |+| Admin store settings | `mailer_logo` (and the new `logo`) | `mailer_logo_signed_id`, `logo_signed_id` |+| Admin sellers, Seller profile | `logo`, `square_logo`, `cover_photo` | `logo_signed_id`, `square_logo_signed_id`, `cover_photo_signed_id` |+| Admin categories, collections | `image`, `square_image` | `image_signed_id`, `square_image_signed_id` |+| Admin option values | `image` | `image_signed_id` |+| Admin tax exemption certificates | `document` | `document_signed_id` |+| Admin and Seller imports | `attachment` | `attachment_signed_id` |+| Admin and Seller shipping labels, Seller requirement submissions | `file` | `file_signed_id` |+| Admin orders, Store API carts | `po_document` | `po_document_signed_id` |++The Store API's `POST /carts/:id/po_document` keeps its route but takes the same flat request and returns the same response as `POST /files`.++Uploads that are never attached are now deleted after two days. Only files uploaded to a store are deleted; files from before the upgrade that were never attached are left as they are. Schedule the job daily in `server/config/recurring.yml`:++```yaml server/config/recurring.yml+production:+ purge_unattached_uploads:+ class: Spree::Uploads::PurgeUnattachedJob+ schedule: every day at 4am+```++Attaching a file uploaded in another store is logged in 6.0 and refused from 6.1. If your logs show `Spree 6.1 refuses this attachment`, fix the code that creates that file before upgrading to 6.1.+## Payment source IDs use the `psrc_` prefix`Spree::PaymentSource` shared the `ps_` prefix with `Spree::PaymentSession`,@@ -1065,6 +1106,7 @@ const orders = isOrderGroup(result) ? result.orders : [result]| Rich text comes in two shapes | Render `description_html` for markup; `description` is plain text | [Rich-text fields](#rich-text-fields-read-as-plain-text-plus-html) || Payment source IDs | Stored `source_id` values change prefix from `ps_` to `psrc_` | [Payment source IDs](#payment-source-ids-use-the-psrc_-prefix) || Completed carts are read-only | Read post-checkout data from the order, not the cart | [The Cart/Order split](#the-cartorder-split) |+| Purchase order document | Send `po_document_signed_id` on the cart; `POST /carts/:id/po_document` takes a flat request | [File uploads](#file-uploads) |## For extension authorsdiff --git a/docs/docs.json b/docs/docs.jsonindex f0127beeda..66f4c20a8d 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -1068,6 +1068,7 @@"api-reference/admin-api/errors","api-reference/admin-api/querying","api-reference/admin-api/monetary-amounts",+ "api-reference/admin-api/uploads","api-reference/admin-api/endpoints"]},@@ -1823,6 +1824,7 @@"api-reference/admin-api/errors","api-reference/admin-api/querying","api-reference/admin-api/monetary-amounts",+ "api-reference/admin-api/uploads","api-reference/admin-api/endpoints"]},@@ -2619,6 +2621,7 @@"api-reference/admin-api/errors","api-reference/admin-api/querying","api-reference/admin-api/monetary-amounts",+ "api-reference/admin-api/uploads","api-reference/admin-api/endpoints"]},diff --git a/docs/plans/6.0-uploads-and-file-ownership.md b/docs/plans/6.0-uploads-and-file-ownership.mdnew file mode 100644index 0000000000..2f8f2469dc--- /dev/null+++ b/docs/plans/6.0-uploads-and-file-ownership.md@@ -0,0 +1,139 @@+# Uploads and File Ownership++**Status:** In Progress — 6.0 scope being built on `feat/uploads-api` (upload contract, parameter rename, store ownership, orphan purge)+**Target:** Spree 6.0 (upload contract, multipart uploads, store ownership) · Spree 6.1 (enforcement, uploader)+**Depends on:** `6.0-media-library.md` (media rows, blob reuse), `6.0-mcp-server.md` (MCP `upload_file` and export tools reach files through the Admin API), `6.0-digital-assets.md` (private uploads)+**Author:** Damian + Claude+**Last updated:** 2026-10-10+**Tracking:** Linear V-3742 · GitHub spree/spree#14865++## Summary++Files reach Spree through `POST /api/v3/admin/direct_uploads`, a presigning helper whose request and response follow Active Storage's own shape: nested parameters, a `private` flag, and a signed blob ID that never expires as the only reference. Two problems follow from that.++- **Blobs have no owner.** Nothing records which store uploaded a file, so a `signed_id` from one store can be attached in another, and storage cannot be measured or cleaned up per store.+- **The contract describes the storage library, not the API.** It breaks the flat-params rule for v3, a leaked reference stays attachable forever, and a caller that cannot run a presigned upload, such as the MCP server or the CLI, has no way to send a file at all.++6.0 replaces the endpoint with `POST /api/v3/admin/files`: a flat request, an expiring opaque reference, and a second way to upload where the bytes travel in the request itself. It also records which store owns every blob. The Admin and Seller APIs are not yet stable, so the old endpoint is removed in the same release, without an alias. 6.1 only tightens: attaching a file from another store is refused, and uploads record who made them. No model changes, so 6.x stays stable for everything built on attachments.++## Key Decisions (do not deviate without discussion)++### 6.0++- **`POST /api/v3/admin/files` replaces `/direct_uploads`, with no alias.** The Admin and Seller APIs are not yet stable, so the old endpoint and its request shape are removed in the same release, not deprecated. "Direct" stops being true once the endpoint also accepts the bytes themselves. `/files` names what the caller sends, in the API's own words rather than the storage library's; only `create` exists in 6.0, so it promises no listing or fetching yet (decided 2026-10-10 over `/uploads`). The Seller API gets the same endpoint.+- **Flat request.** `filename`, `content_type`, `byte_size`, `checksum` (base64 MD5) and `visibility` (`public` or `private`) sit at the top level, following the flat-params rule for v3. The `{ blob: { … } }` wrapper and the `private: true` flag are gone.+- **Two ways to upload, one response.**+ - **Presigned:** JSON metadata returns a target the client PUTs the bytes to. The dashboard and seller panel use this, so large files go straight to storage.+ - **Multipart:** a `file` part in the request, and the server stores the bytes itself, returning the same response with `upload: null`. The MCP server and the CLI use this. A caller that cannot make a second request (a model calling a tool) needs it, and on disk storage it avoids a presigned target that points back at the same application.+- **`signed_id` keeps its name and is documented as opaque.** Every write endpoint already accepts it. Clients pass it back unchanged and must not parse it, so the way references are issued can change without breaking anyone.+- **Signed IDs expire.** Uploads mint `signed_id(expires_in: 1.day)`, returned with `expires_at`. Responses that offer an existing file for reuse (the media library) mint a fresh one on each read. A leaked reference is no longer attachable forever.+- **Blobs belong to a store.** A nullable `store_id` column on `active_storage_blobs`; Active Storage ignores columns it does not define. Set when every blob is created, and backfilled for existing rows by the 6.0 upgrade.+- **6.0 checks and logs; 6.1 refuses.** Attaching a blob whose store differs from its owner's, or that has no store, is logged in 6.0 and refused from 6.1. One release of logs finds every path that creates blobs without a store before anything depends on the check.+- **Image URLs are documented as opaque.** Clients store and render them as given and never build or parse them, so the format and host can change (a CDN, a different storage service) without breaking anyone.+- **Every upload reference parameter is named `signed_id` or `<slot>_signed_id`** (2026-10-10). Renamed in the same change as the endpoint, while the breaking window is open: `avatar` → `avatar_signed_id`, `logo` → `logo_signed_id`, `image` → `image_signed_id`, `document` → `document_signed_id`, `attachment` → `attachment_signed_id`, `file` → `file_signed_id`, `po_document` → `po_document_signed_id`, and so on for every slot. Clients no longer translate between names; the old names are removed, not aliased, in the Admin and Seller APIs, and the Store API change is in the upgrade guide.+- **Public uploads are allowlisted, private uploads are open** (2026-10-10). Public: web image types, `Spree::Config.video_content_types` and `text/csv`. Private: any type, because digital products are ebooks, archives and audio, and the attachment's own validation is the real check. Limits are installation settings: `Spree::Config.max_upload_size` (5 GB) for presigned uploads and `max_multipart_upload_size` (10 MB, matching MCP `upload_file`) for multipart.+- **Never-attached uploads are purged by a daily core job** (2026-10-10). Rails purges nothing on its own and neither did Spree. `Spree::Uploads::PurgeUnattachedJob` removes blobs that belong to a store and have no attachment, older than `Spree::Config.unattached_upload_retention_days` (default 2, longer than the 1-day reference expiry, so nothing a client can still attach is lost). An installation setting rather than a store one: storage is installation infrastructure.+- **The Store API purchase-order presigner adopts the same contract and stays nested** (2026-10-10). `POST /api/v3/store/carts/:cart_id/po_document` keeps its cart-scoped route, because a publishable key is public and must not mint uploads freely, but takes the flat request, returns the same response shape with an expiring `signed_id`, and records the store. It is the one exception to "uploads go through `/files` only".+- **MCP is not on `main` yet** (2026-10-10). The MCP server branch (`6.0-mcp-server.md`) adopts the multipart request when it rebases; this change ships the endpoint it will call.++### 6.1++- **The store check refuses.** After a release of 6.0 logs, attaching a blob from another store, or one with no store, is refused.+- **Uploads record who made them** (2026-10-10). `uploaded_by_type` / `uploaded_by_id` on `active_storage_blobs`, short type names per `6.0-action-actors.md`, set by the same creation hook that sets `store_id`. One migration and one hook line answer "who uploaded this file" for audits and seller disputes.++## Design Details++### The upload contract++**Presigned:**+```http+POST /api/v3/admin/files+Content-Type: application/json++{ "filename": "products.csv", "content_type": "text/csv", "byte_size": 48213,+ "checksum": "<base64 MD5>", "visibility": "private" }+```++```json+201+{ "signed_id": "…opaque…",+ "filename": "products.csv", "content_type": "text/csv", "byte_size": 48213,+ "visibility": "private", "expires_at": "2026-10-11T12:00:00Z",+ "upload": { "method": "PUT", "url": "https://…", "headers": { "Content-MD5": "…" } } }+```++The client PUTs the bytes to `upload.url` with `upload.headers`, treating both as opaque, then passes `signed_id` to the endpoint that uses the file.++**Multipart:**+```http+POST /api/v3/admin/files+Content-Type: multipart/form-data++filename, content_type, visibility, file=<bytes>+```++The server takes `byte_size` and `checksum` from the bytes it received and returns the same response with `upload: null`. The file is already stored.++**Both ways:**+- The endpoint enforces the content-type allowlist for public uploads and the size limit for both. Multipart has a lower limit, because the bytes pass through the application; larger files use the presigned upload.+- `visibility` selects the public or private storage service.+- `store_id` is set on the blob (see below).+- The Seller API's `POST /api/v3/seller/files` is identical, behind the seller's own scope.++**Callers that move in the same change.** The admin and seller SDKs replace `directUploads.create()` with `files.create()`, plus a helper that runs create and PUT and returns the `signed_id` in one call. These move together:+- **Dashboard and seller panel:** product and variant media and posters, digital assets, imports, shipping labels, the store logo and mailer logo, avatars, tax exemption certificates, and seller requirement submissions.+- **MCP:** `upload_file` dispatches the multipart request through the Admin API, replacing its direct blob creation.+- **CLI:** `spree api` gains an upload command built on the multipart request.++### Store ownership++- **Column:** `active_storage_blobs.store_id`, nullable, indexed.+- **Set on creation:**+ - `POST /files` passes `store_id: current_store.id` in both ways of uploading.+ - Blobs Spree creates internally (imports, exports, shipping labels, data requests, seeds) get the store from one `ActiveSupport.on_load(:active_storage_blob)` hook reading `Spree::Current.store`.+- **Checked on attachment:** one check when an `ActiveStorage::Attachment` is created. The blob's store must equal the owning record's store: `record.store_id`, or the owner's store for records without one (media through its viewable, variants through their product). It lives on the attachment model, so controllers, workflows, extensions and console use are all covered.+ - In 6.0 a mismatch, or a blob with no store, is logged with the attachment slot and owner. From 6.1 it is refused.+ - Records with no store (global admin avatars) are exempt.+- **Backfill:** `spree:uploads:assign_stores` runs as part of the 6.0 upgrade manifest (after `db:migrate`), as an `ActiveJob::Continuable` task with one set-based `UPDATE … FROM active_storage_attachments JOIN <owner table>` per attachment slot, in ID ranges, safe to rerun. A blob attached in two stores is reported, not resolved. Unattached blobs are left without a store, and the daily purge leaves them alone: it only deletes files that belong to a store, since a host app may keep blobs of its own outside attachments (2026-10-10, from review).++What ownership enables beyond the security check:+- storage used per store;+- cleanup of a store's orphaned uploads;+- deleting a store's files when the store is deleted.++## Migration Path++**6.0**+1. Migration (`[8.1]`): `store_id`, indexed, on `active_storage_blobs`.+2. `POST /files` for the Admin and Seller APIs: the flat request, `visibility`, presigned and multipart uploads, the response shape, expiring `signed_id`, and `store_id` on the blob. `/direct_uploads` and its controllers, concern and routes are deleted.+3. The store hook on internal blob creation, and the store check on attachment creation, logging only.+4. Admin and seller SDK `files.create()` plus the helper; `directUploads` removed. The dashboard and seller panel move every upload flow over. MCP `upload_file` dispatches the multipart request. `spree api` gains the upload command. Regenerate types, Zod schemas and OpenAPI.+5. `spree:uploads:assign_stores` in the 6.0 upgrade manifest, with a report of blobs attached in two stores.+6. Every upload reference parameter renamed to `signed_id` / `<slot>_signed_id`, and the daily purge of never-attached uploads.+7. Docs: an uploads page (both ways of uploading, the opaque `signed_id`, expiry, visibility, size limits), image URLs and `signed_id` called out as opaque in the API introduction, and a changelog entry for the endpoint replacement.++**6.1**+1. The store check refuses mismatches and blobs with no store.+2. Uploader columns (`uploaded_by_type`, `uploaded_by_id`).++## Constraints on Current Work++- **Uploads go through `POST /files` only.** Do not add another way to create a blob from the API.+- **Never put a blob ID, storage key or Rails blob URL in an API response.** Public images go through `image_url_for` / `cdn_image_url`. Upload references are `signed_id` values, minted with an expiry.+- **Every blob Spree creates belongs to a store.** Pass `store_id`, or create it inside a request or job where `Spree::Current.store` is set. A 6.0 log line about a blob with no store is a bug to fix before 6.1 starts refusing.+- **No new `has_many_attached`.** A record with several images uses media rows; a private document is a single `has_one_attached` slot.+- **An image a merchant picks or reuses is a media row,** not a new attachment on the owner. Logos, covers and swatches added from now on go through the media library.+- **Upload references are parameters named `signed_id` or `<slot>_signed_id`.** Do not add new names (`document`, `file`, `attachment`) for the same thing.+- **Do not build URLs with `rails_blob_*` or `rails_representation_*` helpers** outside `cdn_image`. Keeping one place that builds image URLs is what lets their host and format change without touching serializers.++## Open Questions++None.++## References++- `docs/plans/6.0-media-library.md`: media rows, blob reuse and deletion safety+- `docs/plans/6.0-mcp-server.md`: MCP `upload_file` and export tools reach files only through the Admin API+- `docs/plans/6.0-action-actors.md`: actor model for `uploaded_by`+- `spree/api/app/controllers/spree/api/v3/admin/direct_uploads_controller.rb`, `spree/api/app/controllers/concerns/spree/api/v3/direct_uploads.rb`: the endpoint 6.0 replaces+- `spree/core/config/routes.rb` (`cdn_image`): the one place public image URLs are builtdiff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex 93c2425211..ee1141018d 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,13 @@+## 2026-10-10: One upload endpoint, store-owned blobs, and `<slot>_signed_id` everywhere++**Context:** Files reached Spree through `/direct_uploads`, which copied Active Storage's nested request and minted references that never expired, and nothing recorded which store a blob belonged to. Endpoints that took those references named them seven different ways.++**Decision:** `POST /api/v3/admin/files` and `POST /api/v3/seller/files` replace `/direct_uploads` with no alias: a flat request, `visibility` (`public`/`private`), presigned or multipart bytes, and one response carrying an opaque `signed_id` that expires after a day. Blobs gain a nullable `store_id`, set on every creation and backfilled by the 6.0 upgrade; attaching a blob from another store is logged in 6.0 and refused in 6.1. Every parameter that takes an upload reference is `signed_id` or `<slot>_signed_id` (`avatar_signed_id`, `logo_signed_id`, `po_document_signed_id`, …). Public uploads are allowlisted (web images, videos, CSV); private uploads accept any type. A daily job purges blobs never attached, after `Spree::Config.unattached_upload_retention_days`. The Store API purchase-order presigner keeps its cart-nested route but adopts the same contract. In 6.1 blobs also record who uploaded them.++**Consequences:** A new endpoint that takes a file uses `<slot>_signed_id`, never `file`, `document` or `attachment`. A blob Spree creates must belong to a store: pass `store_id`, or create it where `Spree::Current.store` is set. API responses never contain a blob id, storage key or Rails blob URL; a response offering an existing file for reuse mints a fresh expiring `signed_id`. Supersedes `6.0-digital-assets.md`'s "never multipart through the API request": multipart is allowed for small files through `/files`.++**Plan:** `6.0-uploads-and-file-ownership.md`.+## 2026-10-09: Typed filters keep sellers association-free, take arrays for `_in`, and ship no 5.x warning**Context:** List filters are being generated into OpenAPI and the SDKs from the Ransack allowlists, and PR C will reject unknown filters. Three choices fix what the published contract says before that happens.diff --git a/packages/admin-sdk/examples/order-labels/upload.ts b/packages/admin-sdk/examples/order-labels/upload.tsindex 1cce90e266..2d5f399e5e 100644--- a/packages/admin-sdk/examples/order-labels/upload.ts+++ b/packages/admin-sdk/examples/order-labels/upload.ts@@ -9,7 +9,7 @@ const client = createAdminClient({// Postage bought elsewhere: upload the file first, then record it with the// tracking number printed on it.const label = await client.orders.fulfillments.labels.create('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {- file: 'signed_blob_id',+ file_signed_id: 'signed_id_from_files_upload',tracking_number: '1Z879E930346834440',cost: '6.50',currency: 'USD',diff --git a/packages/admin-sdk/examples/tax-exemption-certificates/create.ts b/packages/admin-sdk/examples/tax-exemption-certificates/create.tsindex 91d572e2e2..d811b68dad 100644--- a/packages/admin-sdk/examples/tax-exemption-certificates/create.ts+++ b/packages/admin-sdk/examples/tax-exemption-certificates/create.ts@@ -5,22 +5,17 @@ const client = createAdminClient({secretKey: 'sk_xxx',})-// region:example-// Upload the document first, then pass the signed id.-const { signed_id } = await client.directUploads.create({- blob: {- filename: 'resale.pdf',- byte_size: 18_345,- checksum: 'Base64EncodedMD5==',- content_type: 'application/pdf',- },-})+declare const certificatePdf: Blob // the certificate PDF, e.g. from a file input or `fs.openAsBlob()`+const { signed_id } = await client.files.upload(certificatePdf, { visibility: 'private' })++// region:example+// `signed_id` comes from `client.files.upload(file, { visibility: 'private' })`.const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {certificate_number: 'DE-RESALE-7',reason_code: 'resale',country_code: 'DE',- document: signed_id,+ document_signed_id: signed_id,})// endregion:examplediff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.tsindex 44fcb16d40..ceaac69f5c 100644--- a/packages/admin-sdk/src/admin-client.ts+++ b/packages/admin-sdk/src/admin-client.ts@@ -1,5 +1,6 @@import type {EmailPasswordLogin,+ FileUploadCreateParams,ListParams,LoginCredentials,PaginatedResponse,@@ -8,8 +9,9 @@ import type {ProviderLogin,RequestFn,RequestOptions,+ UploadFileOptions,} from '@spree/sdk-core'-import { getParams, transformListParams } from '@spree/sdk-core'+import { getParams, transformListParams, uploadFile } from '@spree/sdk-core'import type {AddressFilters,AddressSort,@@ -437,7 +439,6 @@ import type {DigitalAssetCreateParams,DigitalAssetProvider,DigitalAssetUpdateParams,- DirectUploadCreateParams,EmailTemplateDraftParams,EmailTemplateLanguageParams,EmailTemplatePreviewParams,@@ -612,6 +613,7 @@ import type {Exchange,Export,Fee,+ FileUpload,Fulfillment,FulfillmentProviderOption,GiftCard,@@ -1783,7 +1785,7 @@ export class AdminClient {/*** The carrier documents bought or uploaded for a parcel. Creating one* with no body buys it through the parcel's carrier account; creating it- * with a `file` (a signed blob id from `directUploads.create()`) records+ * with a `file_signed_id` (from `files.upload()`) records* postage the merchant bought elsewhere. To print one, fetch* `download_url` with the `Authorization` header and drive the browser* download from a Blob — the bytes are streamed through the API rather@@ -4112,8 +4114,8 @@ export class AdminClient {* sale, since a verified certificate stops counting once its expiry date* passes.*- * Upload the document via `directUploads.create()` first and pass the- * returned `signed_id` as `document`. To read it back, fetch+ * Upload the document via `files.upload()` first and pass the+ * returned `signed_id` as `document_signed_id`. To read it back, fetch* `document_url` with the `Authorization` header and drive the browser* download from a Blob — the bytes are streamed through the API rather* than served from storage, so a top-level navigation carrying no JWT@@ -4387,8 +4389,8 @@ export class AdminClient {/*** Queues asynchronous CSV imports and drives the mapping flow. Upload the- * file via `directUploads.create()` first, then `create()` the import with- * the returned `signed_id` — the response is in the `mapping` state and+ * file via `files.upload()` first, then `create()` the import with+ * the returned `signed_id` as `attachment_signed_id` — the response is in the `mapping` state and* carries `schema_fields`, `csv_headers`, a `sample_row` and the* auto-assigned `mappings`. Adjust mappings if needed and call* `completeMapping(id)` to start processing, then poll `get(id)` while@@ -5734,17 +5736,38 @@ export class AdminClient {}// ============================================- // Direct Uploads (Active Storage)+ // Files// ============================================- readonly directUploads = {+ /**+ * Uploading the files other endpoints use — product media, imports, logos,+ * documents. Each upload returns a `signed_id`: pass it unchanged to the+ * endpoint that uses the file (`signed_id`, `avatar_signed_id`,+ * `attachment_signed_id`, …) within a day, after which it expires.+ */+ readonly files = {+ /**+ * Creates an upload. JSON metadata returns `upload`, the storage target to+ * send the bytes to; a `FormData` body with a `file` part stores the bytes+ * directly and returns `upload: null`. `upload()` does both steps for you.+ */create: (- params: DirectUploadCreateParams,+ params: FileUploadCreateParams | FormData,options?: RequestOptions,- ): Promise<{- direct_upload: { url: string; headers: Record<string, string> }- signed_id: string- }> => this.request('POST', '/direct_uploads', { ...options, body: params }),+ ): Promise<FileUpload> =>+ this.request<FileUpload>('POST', '/files', { ...options, body: params }),++ /**+ * Uploads a file and resolves to the response; its `signed_id` is what the+ * endpoint that uses the file takes. Pass `visibility: 'private'` for+ * documents, imports and digital products.+ */+ upload: (+ file: Blob,+ options: UploadFileOptions = {},+ requestOptions?: RequestOptions,+ ): Promise<FileUpload> =>+ uploadFile((body) => this.files.create(body, requestOptions), file, options),}// ============================================diff --git a/packages/admin-sdk/src/index.ts b/packages/admin-sdk/src/index.tsindex fd4f64cb3e..91de6d5deb 100644--- a/packages/admin-sdk/src/index.ts+++ b/packages/admin-sdk/src/index.ts@@ -1,6 +1,12 @@// Main client-export type { RequestOptions, RetryConfig, ValidationErrorDetail } from '@spree/sdk-core'+export type {+ FileUploadCreateParams,+ RequestOptions,+ RetryConfig,+ UploadFileOptions,+ ValidationErrorDetail,+} from '@spree/sdk-core'// Request infrastructure (re-export from sdk-core)export {compareMoney,diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex 2cf2cd47b2..2e0baf6e78 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -113,8 +113,10 @@ export interface StoreUpdateParams {email_heading_color?: string | null/** Customer email font: `inter`, `system`, `helvetica`, `georgia`, `roboto`, `lato` or `merriweather`. */email_font?: string | null- /** Active Storage signed_id from a direct upload — the logo embedded in transactional emails. */- mailer_logo?: string | null+ /** A `signed_id` from `files.upload()` for the store logo, or `null` to remove it. */+ logo_signed_id?: string | null+ /** A `signed_id` from `files.upload()` for the logo embedded in transactional emails, or `null` to remove it. */+ mailer_logo_signed_id?: string | null/** Where prices come from: a registered provider key, or `internal`. */pricing_provider?: string/** Where stock levels come from: a registered provider key, or `internal`. */@@ -146,8 +148,8 @@ export interface OptionValueParams {position?: number/** Hex color (e.g. `#FF0000`). Only meaningful when the parent option type's `kind` is `color_swatch`. */color_code?: string | null- /** Active Storage signed_id from a direct upload. */- image?: string | null+ /** A `signed_id` from `files.upload()`, or `null` to remove the image. */+ image_signed_id?: string | null}export interface OptionTypeCreateParams {@@ -323,15 +325,15 @@ interface ShippingLabelDetails {* refuses it.*/export interface ShippingLabelUploadParams extends ShippingLabelDetails {- /** Signed blob id from `directUploads.create()`. Its presence records an uploaded label instead of buying one. */- file: string+ /** A `signed_id` from `files.upload()`. Its presence records an uploaded label instead of buying one. */+ file_signed_id: string/** The number printed on an uploaded label. */tracking_number: string}/** Buying through the carrier. The carrier supplies the file and the number. */export interface ShippingLabelPurchaseParams extends ShippingLabelDetails {- file?: never+ file_signed_id?: nevertracking_number?: never}@@ -541,10 +543,10 @@ export interface OrderCreateParams {*/po_number?: string/**- * ActiveStorage signed blob id of the buyer's purchase order, from- * `POST /api/v3/admin/direct_uploads` with `private: true`.+ * The `signed_id` of the buyer's purchase order, from `files.upload()` with+ * `visibility: 'private'`.*/- po_document?: string+ po_document_signed_id?: string/** Rich text HTML. Reads come back as this plus `internal_note_html`. */internal_note?: stringmetadata?: Record<string, unknown>@@ -574,10 +576,10 @@ export interface OrderUpdateParams {*/po_number?: string/**- * See {@link OrderCreateParams.po_document}. Null removes the document the- * order currently carries.+ * See {@link OrderCreateParams.po_document_signed_id}. Null removes the+ * document the order currently carries.*/- po_document?: string | null+ po_document_signed_id?: string | null/*** Company ID. See {@link OrderCreateParams.company_id}. Null makes the draft* a plain customer order again.@@ -740,21 +742,6 @@ export interface CustomerStoreCreditUpdateParams {memo?: string}-export interface DirectUploadCreateParams {- blob: {- filename: string- byte_size: number- checksum: string- content_type: string- }- /**- * Upload to private storage rather than the public bucket. Needed for files- * only ever served through a signed link (digital assets) — attaching a blob- * never moves it between services, so this is decided at upload time.- */- private?: boolean-}-export type MediaType = 'image' | 'video' | 'external_video'export interface MediaCreateParams {@@ -849,7 +836,7 @@ export interface DigitalAssetProvider {}export interface DigitalAssetCreateParams {- /** Signed blob id from a `private: true` direct upload. Required for a file+ /** A `signed_id` from `files.upload()` with `visibility: 'private'`. Required for a file* asset (the default source); omitted for a provider-backed asset. */signed_id?: string/** Provider shorthand from the `providers` endpoint. Omit for an uploaded file (the default source). */@@ -1024,10 +1011,10 @@ export interface CategoryCreateParams {meta_title?: stringmeta_description?: stringmeta_keywords?: string- /** ActiveStorage signed_id of a directly-uploaded landscape image. */- image?: string- /** ActiveStorage signed_id of a directly-uploaded square image. */- square_image?: string+ /** A `signed_id` from `files.upload()` for the landscape image. */+ image_signed_id?: string | null+ /** A `signed_id` from `files.upload()` for the square image. */+ square_image_signed_id?: string | null}export interface CategoryUpdateParams {@@ -1041,10 +1028,10 @@ export interface CategoryUpdateParams {meta_title?: stringmeta_description?: stringmeta_keywords?: string- /** ActiveStorage signed_id of a directly-uploaded landscape image, or null to remove it. */- image?: string | null- /** ActiveStorage signed_id of a directly-uploaded square image, or null to remove it. */- square_image?: string | null+ /** A `signed_id` from `files.upload()` for the landscape image, or null to remove it. */+ image_signed_id?: string | null+ /** A `signed_id` from `files.upload()` for the square image, or null to remove it. */+ square_image_signed_id?: string | null}export interface CategoryRepositionParams {@@ -1106,10 +1093,10 @@ export interface CollectionCreateParams {meta_title?: stringmeta_description?: stringmeta_keywords?: string- /** ActiveStorage signed_id of a directly-uploaded landscape image. */- image?: string- /** ActiveStorage signed_id of a directly-uploaded square image. */- square_image?: string+ /** A `signed_id` from `files.upload()` for the landscape image. */+ image_signed_id?: string | null+ /** A `signed_id` from `files.upload()` for the square image. */+ square_image_signed_id?: string | null/** Default product sort for the storefront listing. Defaults to `manual`. */sort_order?: CollectionSortOrder/** When true, membership is materialized from `rules` instead of curated by hand. */@@ -1135,10 +1122,10 @@ export interface CollectionUpdateParams {meta_title?: stringmeta_description?: stringmeta_keywords?: string- /** ActiveStorage signed_id of a directly-uploaded landscape image, or null to remove it. */- image?: string | null- /** ActiveStorage signed_id of a directly-uploaded square image, or null to remove it. */- square_image?: string | null+ /** A `signed_id` from `files.upload()` for the landscape image, or null to remove it. */+ image_signed_id?: string | null+ /** A `signed_id` from `files.upload()` for the square image, or null to remove it. */+ square_image_signed_id?: string | nullsort_order?: CollectionSortOrderautomatic?: booleanrules_match_policy?: 'all' | 'any'@@ -1435,10 +1422,10 @@ export interface MeUpdateParams {first_name?: stringlast_name?: string/**- * ActiveStorage direct-upload signed id to set the avatar, or `null` to+ * A `signed_id` from `files.upload()` to set the avatar, or `null` to* remove it. Omit to leave the current photo unchanged.*/- avatar?: string | null+ avatar_signed_id?: string | null}export interface StockLocationCreateParams {@@ -1915,12 +1902,12 @@ export interface SellerCreateParams {/** Sanitized HTML — the seller's public description. */about?: string | null/**- * Branding attachments. Pass an ActiveStorage signed id to set one, `null`- * to remove it, or omit the key to leave it untouched.+ * Branding images. Pass a `signed_id` from `files.upload()` to set one,+ * `null` to remove it, or omit the key to leave it untouched.*/- logo?: string | null- square_logo?: string | null- cover_photo?: string | null+ logo_signed_id?: string | null+ square_logo_signed_id?: string | null+ cover_photo_signed_id?: string | nulltax_remittance?: 'seller' | 'platform'payouts_schedule_interval?: 'daily' | 'weekly' | 'biweekly' | 'monthly' | 'manual' | nullminimum_payout_amount?: string | null@@ -2504,11 +2491,8 @@ export type ImportType =export interface ImportCreateParams {/** Which dataset to import. Server validates against `Spree::Import.available_types`. */type: ImportType- /**- * ActiveStorage signed blob id of the uploaded CSV, obtained from- * `client.directUploads.create()` (or the `useDirectUpload` hook).- */- attachment: string+ /** The `signed_id` of the uploaded CSV, from `files.upload()` with `visibility: 'private'`. */+ attachment_signed_id: string/** CSV column separator. Defaults to a comma on the server. */delimiter?: ',' | ';' | '|' | '\t'/**@@ -3066,8 +3050,8 @@ export interface TaxExemptionCertificateParams {issued_at?: string | nullexpires_at?: string | nullissuing_authority?: string | null- /** ActiveStorage signed blob id from `directUploads.create()`. */- document?: string+ /** A `signed_id` from `files.upload()` with `visibility: 'private'`. */+ document_signed_id?: stringmetadata?: Record<string, unknown>}diff --git a/packages/admin-sdk/src/types/generated/FileUpload.ts b/packages/admin-sdk/src/types/generated/FileUpload.tsnew file mode 100644index 0000000000..81ba092905--- /dev/null+++ b/packages/admin-sdk/src/types/generated/FileUpload.ts@@ -0,0 +1,16 @@+// Typelizer digest 7a884ae6d631bee1659086d1f953f34f+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.+import type {FileUploadTarget} from '@/types'++interface FileUpload {+ signed_id: string;+ filename: string;+ content_type: string;+ byte_size: number;+ visibility: 'public' | 'private';+ expires_at: string;+ upload: FileUploadTarget | null;+}++export default FileUpload;diff --git a/packages/admin-sdk/src/types/generated/FileUploadTarget.ts b/packages/admin-sdk/src/types/generated/FileUploadTarget.tsnew file mode 100644index 0000000000..3555bc4eb0--- /dev/null+++ b/packages/admin-sdk/src/types/generated/FileUploadTarget.ts@@ -0,0 +1,11 @@+// Typelizer digest a9603f6f347f9719ba7630c7eeead99e+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface FileUploadTarget {+ method: string;+ url: string;+ headers: Record<string, string>;+}++export default FileUploadTarget;diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.tsindex dce8e3bd5d..7f37e88f39 100644--- a/packages/admin-sdk/src/types/generated/index.ts+++ b/packages/admin-sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest 6c2d08aef7add7a892425e8a6adf1fa1+// Typelizer digest 3c75528941f0091cb81c67924a9d9232//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { ActorKind, ClaimStatus, DataRequestStatus, ExchangeStatus, FeeKind, FulfillmentItemStatus, FulfillmentStatus, GiftCardStatus, ImportRowStatus, ImportStatus, InvitationStatus, PaymentStatus, PriceListStatus, ProductStatus, ProductSubmissionStatus, ReturnStatus, SellerPayoutStatus, SellerRequirementSubmissionStatus, SellerStatus, SellerTransferStatus, ShippingLabelStatus, StockLocationKind, TaxExemptionCertificateStatus } from './Enums'@@ -61,6 +61,8 @@ export type { default as ExchangeLineItem } from './ExchangeLineItem'export type { default as Exchange } from './Exchange'export type { default as Export } from './Export'export type { default as Fee } from './Fee'+export type { default as FileUpload } from './FileUpload'+export type { default as FileUploadTarget } from './FileUploadTarget'export type { default as FreightSummaryLine } from './FreightSummaryLine'export type { default as FreightSummary } from './FreightSummary'export type { default as FulfillmentItem } from './FulfillmentItem'diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.tsindex 3925c0dc5b..004d033c96 100644--- a/packages/admin-sdk/src/types/index.ts+++ b/packages/admin-sdk/src/types/index.ts@@ -108,6 +108,8 @@ export type { default as EmailReturn } from './generated/emails/EmailReturn'export type { default as EmailStockLocation } from './generated/emails/EmailStockLocation'export type { default as EmailStore } from './generated/emails/EmailStore'export type { default as Fee } from './generated/Fee'+export type { default as FileUpload } from './generated/FileUpload'+export type { default as FileUploadTarget } from './generated/FileUploadTarget'export type { default as FreightSummary } from './generated/FreightSummary'export type { default as FreightSummaryLine } from './generated/FreightSummaryLine'export type { default as Fulfillment } from './generated/Fulfillment'diff --git a/packages/admin-sdk/src/zod/generated/FileUpload.ts b/packages/admin-sdk/src/zod/generated/FileUpload.tsnew file mode 100644index 0000000000..8cdf6ec602--- /dev/null+++ b/packages/admin-sdk/src/zod/generated/FileUpload.ts@@ -0,0 +1,15 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';+import { FileUploadTargetSchema } from './FileUploadTarget';++export const FileUploadSchema = z.object({+ signed_id: z.string(),+ filename: z.string(),+ content_type: z.string(),+ byte_size: z.number(),+ visibility: z.string(),+ expires_at: z.string(),+ upload: FileUploadTargetSchema.nullable(),+});++export type FileUpload = z.infer<typeof FileUploadSchema>;diff --git a/packages/admin-sdk/src/zod/generated/FileUploadTarget.ts b/packages/admin-sdk/src/zod/generated/FileUploadTarget.tsnew file mode 100644index 0000000000..ab0d27aa76--- /dev/null+++ b/packages/admin-sdk/src/zod/generated/FileUploadTarget.ts@@ -0,0 +1,10 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';++export const FileUploadTargetSchema = z.object({+ method: z.string(),+ url: z.string(),+ headers: z.record(z.string(), z.string()),+});++export type FileUploadTarget = z.infer<typeof FileUploadTargetSchema>;diff --git a/packages/admin-sdk/src/zod/generated/index.ts b/packages/admin-sdk/src/zod/generated/index.tsindex 5b807bbf0f..ee038b15e9 100644--- a/packages/admin-sdk/src/zod/generated/index.ts+++ b/packages/admin-sdk/src/zod/generated/index.ts@@ -58,6 +58,8 @@ export { ExchangeSchema, type Exchange } from './Exchange';export { ExchangeLineItemSchema, type ExchangeLineItem } from './ExchangeLineItem';export { ExportSchema, type Export } from './Export';export { FeeSchema, type Fee } from './Fee';+export { FileUploadSchema, type FileUpload } from './FileUpload';+export { FileUploadTargetSchema, type FileUploadTarget } from './FileUploadTarget';export { FreightSummarySchema, type FreightSummary } from './FreightSummary';export { FreightSummaryLineSchema, type FreightSummaryLine } from './FreightSummaryLine';export { FulfillmentSchema, type Fulfillment } from './Fulfillment';diff --git a/packages/admin-sdk/tests/store-settings.test.ts b/packages/admin-sdk/tests/store-settings.test.tsindex ad5c5afb53..de6b007aa4 100644--- a/packages/admin-sdk/tests/store-settings.test.ts+++ b/packages/admin-sdk/tests/store-settings.test.ts@@ -115,44 +115,97 @@ describe('dashboard', () => {})})-describe('directUploads', () => {+describe('files', () => {+ const fileUpload = {+ signed_id: 'signed_xyz789',+ filename: 'logo.png',+ content_type: 'image/png',+ byte_size: 4,+ visibility: 'public',+ expires_at: '2026-10-11T12:00:00Z',+ }+describe('create', () => {- it('POSTs /direct_uploads and returns the signed upload', async () => {+ it('POSTs flat metadata to /files', async () => {let body: Record<string, unknown> | null = nullserver.use(- http.post(`${API_PREFIX}/direct_uploads`, async ({ request }) => {+ http.post(`${API_PREFIX}/files`, async ({ request }) => {body = (await request.json()) as Record<string, unknown>+ return HttpResponse.json({ ...fileUpload, upload: null }, { status: 201 })+ }),+ )++ const params = {+ filename: 'logo.png',+ byte_size: 4,+ checksum: 'abc==',+ content_type: 'image/png',+ }+ const res = await createTestClient().files.create(params)++ expect(body).toEqual(params)+ expect(res.signed_id).toBe('signed_xyz789')+ })+ })++ describe('upload', () => {+ it('reserves the file, sends its bytes to the storage target and returns the response', async () => {+ let created: Record<string, unknown> | null = null+ let stored: string | null = null+ server.use(+ http.post(`${API_PREFIX}/files`, async ({ request }) => {+ created = (await request.json()) as Record<string, unknown>return HttpResponse.json({- direct_upload: {+ ...fileUpload,+ visibility: 'private',+ upload: {+ method: 'PUT',url: 'https://uploads.example.com/abc',- headers: { 'Content-Type': 'image/png' },+ headers: { 'Content-MD5': 'x' },},- signed_id: 'signed_xyz789',},{ status: 201 },)}),+ http.put('https://uploads.example.com/abc', async ({ request }) => {+ stored = await request.text()+ return new HttpResponse(null, { status: 200 })+ }),)- const res = await createTestClient().directUploads.create({- blob: {- filename: 'logo.png',- byte_size: 1024,- checksum: 'abc==',- content_type: 'image/png',- },- })+ const file = new File(['logo'], 'logo.png', { type: 'image/png' })+ const res = await createTestClient().files.upload(file, { visibility: 'private' })- expect(body).toEqual({- blob: {- filename: 'logo.png',- byte_size: 1024,- checksum: 'abc==',- content_type: 'image/png',- },+ expect(created).toMatchObject({+ filename: 'logo.png',+ content_type: 'image/png',+ byte_size: 4,+ checksum: 'ltby5+H3BateWchKbcAJsg==',+ visibility: 'private',})+ expect(stored).toBe('logo')expect(res.signed_id).toBe('signed_xyz789')})++ it('sends a multipart upload in the request itself', async () => {+ let file: FormDataEntryValue | null = null+ server.use(+ http.post(`${API_PREFIX}/files`, async ({ request }) => {+ file = (await request.formData()).get('file')+ return HttpResponse.json({ ...fileUpload, upload: null }, { status: 201 })+ }),+ )++ const res = await createTestClient().files.upload(+ new File(['logo'], 'logo.png', { type: 'image/png' }),+ {+ method: 'multipart',+ },+ )++ expect(file).toBeInstanceOf(File)+ expect(res.upload).toBeNull()+ })})})diff --git a/packages/cli/src/commands/api.ts b/packages/cli/src/commands/api.tsindex 7f725987d8..e2f67385b6 100644--- a/packages/cli/src/commands/api.ts+++ b/packages/cli/src/commands/api.ts@@ -1,3 +1,5 @@+import { openAsBlob } from 'node:fs'+import { basename } from 'node:path'import { createAdminClient } from '@spree/admin-sdk'import { type Command, Option } from 'commander'import { printTable } from 'console-table-printer'@@ -89,6 +91,7 @@ export function registerApiCommand(program: Command): void {' spree api get /products -q status_eq=active --limit 10',' spree api post /products -d \'{"name":"Classic Tee","prices":[{"currency":"USD","amount":"29.99"}]}\'',' spree api get /orders/ord_x8k2J9aQ --expand items,payments',+ ' spree api upload ./products.csv --private # prints a signed_id to pass to another endpoint','','Discover the surface (offline, no server needed):',' spree api endpoints --search <term> # find endpoints + required scopes',@@ -150,6 +153,38 @@ export function registerApiCommand(program: Command): void {})}+ // --- File upload -----------------------------------------------------------++ withSharedFlags(+ api+ .command('upload <file>')+ .description(+ 'Upload a file (10 MB by default) and print its signed_id, e.g. `spree api upload ./logo.png`',+ )+ .option('--private', 'store on private storage (documents, imports, digital products)')+ .option('--content-type <type>', 'content type, when it cannot be read from the file'),+ ).action(+ async (file: string, flags: SharedFlags & { private?: boolean; contentType?: string }) => {+ let baseUrl: string | undefined+ try {+ // Open the file before resolving credentials, so a wrong path fails+ // fast without minting a project key.+ const blob = await openAsBlob(file)+ const { client, credentials } = await clientFor(flags)+ baseUrl = credentials.baseUrl+ const result = await client.files.upload(blob, {+ method: 'multipart',+ filename: basename(file),+ contentType: flags.contentType,+ visibility: flags.private ? 'private' : 'public',+ })+ printResult(result, flags.format)+ } catch (error) {+ handleApiError(error, { baseUrl })+ }+ },+ )+// --- Schema introspection (bundled OpenAPI snapshot) ----------------------apidiff --git a/packages/cli/src/commands/completion.ts b/packages/cli/src/commands/completion.tsindex a1f9b067a2..567c67b96d 100644--- a/packages/cli/src/commands/completion.ts+++ b/packages/cli/src/commands/completion.ts@@ -36,7 +36,7 @@ const RANSACK_PREDICATES = ['blank',]-const API_VERBS = ['get', 'post', 'patch', 'delete', 'endpoints', 'schema', 'status']+const API_VERBS = ['get', 'post', 'patch', 'delete', 'upload', 'endpoints', 'schema', 'status']// Keep in sync with `Spree::ApiKey.known_scopes` — the permission catalog keys// plus aliases (spree/core/lib/spree/core/permission_configuration.rb).diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.jsonindex 27258c0523..388845a371 100644--- a/packages/cli/src/generated/admin-spec.json+++ b/packages/cli/src/generated/admin-spec.json@@ -1 +1 @@-{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It is honoured only on the\ndashboard's origin and for an account that is staff of the store —\notherwise it is silently ignored and the link opens the dashboard's\nreset page. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Honoured only on the dashboard origin, for an account that is staff of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."},"sample_data":{"type":"boolean","description":"Load the demo catalog, customers and orders in the background once the admin account exists."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of origin (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[origin_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `origin`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"AllowedOrigin","sortable":["created_at","id","origin","updated_at"]},"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ApiKey","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name and pretty name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `children_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `depth` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `pretty_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[parent_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Category","sortable":["automatic","children_count","created_at","depth","id","name","parent_id","permalink","position","pretty_name","products_count","updated_at"]},"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/custom_fields":{"get":{"summary":"List category custom fields","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the category's custom field values.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Channel","sortable":["active","code","created_at","default","id","name","store_id","updated_at"]},"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy shorthand (built-in: `rules`). `null` inherits the store setting."},"storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy shorthand (built-in: `rules`). `null` inherits the store setting."},"storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[active_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `channel_id`, `created_at`, `id`, `position`, `store_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OrderRoutingRule","sortable":["active","channel_id","created_at","id","position","store_id","type","updated_at"]},"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of namespace, key, and label (partial, case-insensitive)."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[key_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `field_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `key` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `namespace` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `resource_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `searchable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `sortable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `field_type`, `id`, `key`, `label`, `namespace`, `resource_type`, `searchable`, `sortable`, `storefront_visible`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomFieldDefinition","sortable":["created_at","field_type","id","key","label","namespace","resource_type","searchable","sortable","storefront_visible","updated_at"]},"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type token (`short_text`, `long_text`, `rich_text`, `number`, …). An extension type that has no token is named by its registered class instead."},"resource_type":{"type":"string","description":"Shorthand of the owning resource, e.g. `product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomerGroup","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/custom_fields":{"get":{"summary":"List customer custom fields","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's custom field values.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/customers/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/api/v3/admin/consent_records":{"get":{"summary":"List consent records","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the consents customers gave or withdrew, newest first, as evidence of what each one agreed to and when.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `accepted` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purpose` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `recorded_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `source` | One of `checkout`, `registration`, `account`, `admin`, `newsletter`, `anonymization`, `unknown`, `import`, `storefront` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `accepted`, `created_at`, `email`, `id`, `purpose`, `recorded_at`, `source`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ConsentRecord","sortable":["accepted","created_at","email","id","purpose","recorded_at","source","updated_at"]},"responses":{"200":{"description":"consent records found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsentRecord"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/data_requests":{"get":{"summary":"List data requests","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the requests customers made to export or erase their personal data, newest first.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[access]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `access`."},{"name":"q[erasure]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `erasure`."},{"name":"q[in_progress]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_progress`."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `access`, `erasure` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `requested_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `completed_at`, `created_at`, `email`, `id`, `kind`, `number`, `requested_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DataRequest","sortable":["completed_at","created_at","email","id","kind","number","requested_at","status","updated_at"]},"responses":{"200":{"description":"data requests found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DataRequest"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[address1_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `address1` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `address2` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `company` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `postal_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Address","sortable":["address1","address2","city","company","country_code","created_at","first_name","id","last_name","phone","postal_code","state_code","updated_at"]},"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CreditCard","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of memo (partial, case-insensitive)."},{"name":"q[from_gift_card]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `from_gift_card`."},{"name":"q[outstanding]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `outstanding`."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `memo` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[created_by_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `created_by_` | `created_at`, `email`, `first_name`, `id`, `last_name`, `updated_at` |\n| `created_by_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `created_by_id`, `currency`, `customer_id`, `id`, `memo`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StoreCredit","sortable":["amount","created_at","created_by_id","currency","customer_id","id","memo","updated_at"]},"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers/{customer_id}/tax_identifiers":{"get":{"summary":"List customer tax registrations","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's own tax registrations, one per kind.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxIdentifier","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"registrations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxIdentifier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches email, first name, last name or full name (partial, case-insensitive)."},{"name":"q[anonymized]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `anonymized`."},{"name":"q[with_min_total_spent]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `with_min_total_spent` to the given value."},{"name":"q[with_standing_for_company][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_standing_for_company` to the given value."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `accepts_email_marketing` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[addresses_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Customer","sortable":["accepts_email_marketing","created_at","email","first_name","id","last_name","phone","updated_at"]},"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/email_templates":{"get":{"summary":"List email templates","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every email template merchants may edit: the emails customers\nreceive, the email layout and the shared partials. Each shows what\ncustomers receive now (the store's published version, else Spree's\ndefault) and any draft in progress. Staff emails are not editable.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default) for the version every language uses","schema":{"type":"string"}}],"responses":{"200":{"description":"email templates found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The template key with dots, e.g. `spree.order_mailer.confirm_email`","schema":{"type":"string"}}],"get":{"summary":"Get an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the template for one language: what customers receive now,\nSpree's default, and the draft with its `lock_version`. When Spree's\ndefault changed since the store's version started from it,\n`default_changed` is true and `base_body` holds the default it\nstarted from, to compare with `default_body`.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (`draft.updated_by`)","schema":{"type":"string"}}],"responses":{"200":{"description":"email template found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"404":{"description":"not an editable template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Revert an email template to Spree's default","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Goes back to Spree's default for one language and discards the draft.\nThe store's published versions are kept, so one can still be restored.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"email template reverted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/draft":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"put":{"summary":"Save an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Saves the draft, in any state; customers keep receiving the published\nversion until it is published. Send the `lock_version` the draft was\nloaded with: a save made from an older copy is refused with 409,\nnaming who saved last. The first save starts from what is published,\nelse Spree's default.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"draft saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"409":{"description":"saved by someone else since it was loaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"lock_version":{"type":"integer"},"rebase":{"type":"boolean","description":"Marks the draft as based on Spree's current default, after reviewing what changed in it"}}}}}}},"delete":{"summary":"Discard an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"draft discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/publication":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Publish an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Makes the draft what customers receive. The draft is first rendered\nwith sample data; one that does not render (for the layout or a\npartial: in any email using it) is refused with 422, listing each\nproblem with its email and line.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"draft published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"422":{"description":"the draft does not render","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer","description":"The draft's `lock_version` as reviewed; a draft saved since is refused with 409"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/preview":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Preview an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renders the template with sample data built from the store's latest\nmatching record, or the one `record_id` names, and returns the email\nwith the variables it was rendered with. An unsaved `subject` and\n`body` take the place of the current version. The layout and partials\nrender inside an email, `email_key` or the first one. `branding`\npreviews colors and a font before they are saved to the store.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"email template rendered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplatePreview"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string","description":"The record to build sample data from"},"email_key":{"type":"string","description":"For the layout or a partial, the email to show it in"},"branding":{"type":"object","description":"Unsaved colors and font to preview, named like the store's `email_*` settings","properties":{"accent_color":{"type":"string"},"background_color":{"type":"string"},"card_color":{"type":"string"},"text_color":{"type":"string"},"heading_color":{"type":"string"},"font":{"type":"string","enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]}}}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/test_email":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Send a test email","tags":["Email Templates"],"security":[{"bearer_auth":[]}],"description":"Sends the template, rendered as the preview renders it, to the\nsigned-in admin, and never to another address: the sample data comes\nfrom a real customer's records. Takes the same body as the preview.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"test email queued","content":{"application/json":{"schema":{"type":"object","properties":{"sent_to":{"type":"string"}},"required":["sent_to"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string"},"email_key":{"type":"string"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/sample_records":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List records to preview an email template with","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The store's five latest records the template can be previewed with,\nnewest first, to pass as `record_id` to the preview. For the layout\nand partials, those of the email `email_key` names. Empty for an\nemail that needs no record.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"email_key","in":"query","required":false,"description":"For the layout or a partial, the email to show it in","schema":{"type":"string"}}],"responses":{"200":{"description":"records found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List email template revisions","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every version of the template published in one language, newest\nfirst. Reverting to Spree's default keeps them.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (`published_by`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"EmailTemplateRevision","sortable":["created_at","id"]},"responses":{"200":{"description":"revisions found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions/{revision_id}/restoration":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Restore an email template revision","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Copies the revision into the draft, to be published like any change.\nSend the draft's `lock_version` when one is open, as when saving it.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"revision copied into the draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer"}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `format` | One of `csv` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `format`, `id`, `number`, `seller_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Export","sortable":["created_at","format","id","number","seller_id","type","updated_at"]},"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers","price_list_prices","purchase_orders"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Fulfillment","sortable":["created_at","id","number","updated_at"]},"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Exchange and claim replacements are moved only out of a named `source_fulfillment_id`, which is how a canceled replacement is sent again. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"source_fulfillment_id":{"type":"string","description":"The only fulfillment of this order to move units from, its exchange and claim replacements included. Omit to take the customer's bought units from every unshipped fulfillment"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[prefix_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `prefix` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `prefix`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"GiftCardBatch","sortable":["created_at","id","prefix","updated_at"]},"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of code (partial, case-insensitive)."},{"name":"q[active]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `active`."},{"name":"q[expired]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `expired`."},{"name":"q[partially_redeemed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `partially_redeemed`."},{"name":"q[redeemed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `redeemed`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `expires_at` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `gift_card_batch_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `state` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[batch_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `batch_` | `created_at`, `id`, `prefix`, `updated_at` |\n| `customers_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customers_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customers_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customers_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customers_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customers_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customers_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customers_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `users_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `users_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `users_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `users_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `users_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `users_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `users_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `users_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `created_by_id`, `currency`, `customer_id`, `expires_at`, `gift_card_batch_id`, `id`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"GiftCard","sortable":["code","created_at","created_by_id","currency","customer_id","expires_at","gift_card_batch_id","id","state","status","updated_at"]},"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `customer_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"customer_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `mapping`, `completed_mapping`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `seller_id`, `status`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Import","sortable":["created_at","id","number","seller_id","status","type","updated_at"]},"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations","price_list_prices","purchase_orders"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `row_number` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `row_number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ImportRow","sortable":["created_at","id","row_number","status","updated_at"]},"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `default_locale` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `currency`, `default_locale`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Market","sortable":["created_at","currency","default_locale","id","name","position","updated_at"]},"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types/{option_type_id}/custom_fields":{"get":{"summary":"List option type custom fields","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the option type's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"option_type_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name and label (partial, case-insensitive)."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `dropdown`, `color_swatch`, `buttons` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OptionType","sortable":["created_at","id","kind","label","name","position","updated_at"]},"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/claims":{"get":{"summary":"List claims","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every damage or missing-item claim in the store, across all orders.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Claim","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"claims listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/claims":{"get":{"summary":"List order claims","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The damage or missing-item claims opened on one order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Claim","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"claims listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/custom_fields":{"get":{"summary":"List order custom fields","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the order's custom field values.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/digital_links":{"get":{"summary":"List digital links","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the download links issued for digital products bought in this store, newest first.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DigitalLink","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"digital links found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/exchanges":{"get":{"summary":"List exchanges","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every exchange in the store, across all orders.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Exchange","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"exchanges listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/exchanges":{"get":{"summary":"List order exchanges","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The exchanges opened on one order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Exchange","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"exchanges listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[country_code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `included` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `provider_id` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `taxability_reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `country_code`, `created_at`, `id`, `included`, `provider_id`, `state_code`, `taxability_reason`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxLine","sortable":["country_code","created_at","id","included","provider_id","state_code","taxability_reason","updated_at"]},"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Discount","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"get":{"summary":"List fees","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the order's fees, such as surcharges, handling and gift wrap, on the whole order or on one item or delivery.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Fee","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"fees found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Fee"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"string"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/order_groups":{"get":{"summary":"List order groups","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns checkouts split into one order per seller, grouping the orders placed together.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[customer_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `currency`, `email`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OrderGroup","sortable":["created_at","currency","email","id","number","updated_at"]},"responses":{"200":{"description":"order groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[additional_tax_total_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `additional_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `discount_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `included_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `non_taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `pre_tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"LineItem","sortable":["additional_tax_total","adjustment_total","cost_price","created_at","discount_total","id","included_tax_total","non_taxable_adjustment_total","order_id","pre_tax_amount","price","quantity","tax_category_id","taxable_adjustment_total","updated_at","variant_id"]},"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches order number or purchase order number (partial), the billing first or last name, or the exact email."},{"name":"q[complete]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `complete`."},{"name":"q[incomplete]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `incomplete`."},{"name":"q[partially_refunded]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `partially_refunded`."},{"name":"q[refunded]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `refunded`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `considered_risky` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `coupon_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `delivery_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `fulfillment_status` | One of `backorder`, `canceled`, `partial`, `unfulfilled`, `fulfilled`, `delivered`, `pending`, `ready`, `shipped` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `item_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `order_group_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `payment_status` | One of `none`, `authorized`, `partially_paid`, `paid`, `partially_refunded`, `refunded`, `overcharged`, `voided`, `balance_due`, `credit_owed`, `failed`, `void` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `po_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `draft`, `placed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `total_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[bill_address_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `line_items_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `line_items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_group_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `promotions_coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Order","sortable":["channel_id","completed_at","considered_risky","coupon_code","created_at","currency","customer_id","delivery_total","email","fulfillment_status","id","item_total","number","order_group_id","payment_state","payment_status","po_number","seller_id","shipment_state","status","total","total_quantity","updated_at"]},"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\nOn a marketplace, an order holding several sellers' goods becomes one\norder per seller, and the response is the order group they belong to\nwith those orders nested inside it.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/returns":{"get":{"summary":"List returns","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every return in the store, across all orders.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Return","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"returns listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/returns":{"get":{"summary":"List order returns","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The returns opened on one order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Return","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"returns listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/returns/{return_id}/labels":{"get":{"summary":"List return labels","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The shipping labels issued for sending one return back to the store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"return_id","in":"path","required":true,"description":"Return prefixed ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `carrier`, `created_at`, `id`, `source`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ShippingLabel","sortable":["carrier","created_at","id","source","status","tracking_number","updated_at"]},"responses":{"200":{"description":"labels listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PaymentMethod","sortable":["active","created_at","id","name","position","storefront_visible","type","updated_at"]},"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every registered payment provider with the JSON Schema of its `preferences`. `installed` marks a provider the store already has, which a \"Provider\" picker leaves out.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[avs_response_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `avs_response` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cvv_response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `cvv_response_message` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `payment_method_` | `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `avs_response`, `created_at`, `cvv_response_code`, `cvv_response_message`, `id`, `response_code`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Payment","sortable":["amount","avs_response","created_at","cvv_response_code","cvv_response_message","id","response_code","state","status","updated_at"]},"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `catalog_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `ends_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `match_policy` | One of `all`, `any` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `draft`, `active`, `inactive`, `scheduled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PriceList","sortable":["catalog_id","created_at","ends_at","id","match_policy","name","position","starts_at","status","updated_at"]},"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches the variant's SKU, option value or product name, as variant search does."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `compare_at_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `min_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `price_list_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[price_list_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |\n| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Price","sortable":["amount","compare_at_amount","created_at","currency","id","min_quantity","price_list_id","updated_at","variant_id"]},"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/digital_assets":{"parameters":[{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"get":{"summary":"List product digital assets","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the downloadable files attached to the product's variants, oldest first.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DigitalAsset","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"digital assets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\nAlso filters and sorts on the store's searchable custom fields, as `q[cf_<namespace>_<key>_<predicate>]` and `sort=cf_<namespace>_<key>`.\n\n**Sort by:** `available_on`, `best_selling`, `created_at`, `description`, `discontinue_on`, `id`, `manual`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","best_selling","created_at","description","discontinue_on","id","manual","name","price","seller_id","slug","status","updated_at"],"custom_fields":true},"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `owner_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `owner_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `owner_id`, `owner_type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Policy","sortable":["created_at","id","name","owner_id","owner_type","updated_at"]},"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ClaimReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OrderCancellationReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"RefundReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ReturnReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `promotion_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `state` | One of `unused`, `used` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[promotion_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `promotion_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CouponCode","sortable":["code","created_at","id","promotion_id","state","updated_at"]},"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PromotionAction","sortable":["created_at","id","position","updated_at"]},"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PromotionRule","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name and code (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `coupon_code`, `automatic` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `path` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `promotion_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[coupon_codes_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Promotion","sortable":["code","created_at","expires_at","id","kind","name","path","promotion_category_id","starts_at","updated_at"]},"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Refund","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_locale":{"type":"string"},"timezone":{"type":"string"},"weight_unit":{"type":"string"},"unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Shorthand of the tagged resource: `product`, `order` or `customer`","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_categories":{"get":{"summary":"List tax categories","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the tax categories products and delivery methods can be assigned to, which tax rates then apply to.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `is_default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `tax_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxCategory","sortable":["created_at","id","is_default","name","tax_code","updated_at"]},"responses":{"200":{"description":"tax categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxCategory"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `included_in_price` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `amount`, `country_code`, `created_at`, `id`, `included_in_price`, `name`, `state_code`, `tax_category_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxRate","sortable":["amount","country_code","created_at","id","included_in_price","name","rate","state_code","tax_category_id","updated_at"]},"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `rate` as a\ndecimal string (`\"0.19\"`) or `rate_percent` as a percentage string (`\"19\"`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"rate":{"type":"string","description":"Rate as a decimal string, e.g. \"0.19\""},"rate_percent":{"type":"string","description":"Rate as a percentage string, e.g. \"19\""},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"rate":{"type":"string"},"rate_percent":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[spree_roles_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `email`, `first_name`, `id`, `last_name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"AdminUser","sortable":["created_at","email","first_name","id","last_name","updated_at"]},"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores. Removing a role needs the same rights as granting it, and the store always keeps at least one admin.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Invitation","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{invitation_id}/acceptance_link":{"get":{"summary":"Get an invitation acceptance link","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the link the invitee opens to accept a pending invitation. The link carries the invitation token, so it needs write access to staff and the right to grant the invitation's role; invitation listings never include it.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"acceptance link found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationAcceptanceLink"}}}}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Role","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `pickup_enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `returns_enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockLocation","sortable":["active","country_code","created_at","default","id","kind","name","pickup_enabled","returns_enabled","seller_id","state_code","updated_at"]},"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/store_credits":{"get":{"summary":"List store credits","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every store credit in the current store, across all customers.\nRead-only: issuing, editing and deleting a credit stays nested under\nthe customer that holds it.\n\n`meta.totals` carries the outstanding balance as one row per currency,\nsummed over the same filter this request used — so filtering by a\ncustomer answers that customer's balance and no filter answers the\nstore's liability.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of memo (partial, case-insensitive)."},{"name":"q[from_gift_card]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `from_gift_card`."},{"name":"q[outstanding]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `outstanding`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `memo` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[created_by_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `created_by_` | `created_at`, `email`, `first_name`, `id`, `last_name`, `updated_at` |\n| `created_by_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `created_by_id`, `currency`, `customer_id`, `id`, `memo`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StoreCredit","sortable":["amount","created_at","created_by_id","currency","customer_id","id","memo","updated_at"]},"responses":{"200":{"description":"store credits found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a store credit","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCredit"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{store_credit_id}/events":{"parameters":[{"name":"store_credit_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List a store credit's ledger","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every movement of the credit's balance, newest first: allocated when\nissued, authorized when a checkout starts against it, captured when\nthat order is paid, and voided or credited back if it is cancelled.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StoreCreditEvent","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"events found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/variants/{variant_id}/custom_fields":{"get":{"summary":"List variant custom fields","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the variant's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"variant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches SKU, option value or product name (partial, case-insensitive; at least three characters)."},{"name":"q[available_at_stock_location]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `available_at_stock_location` to the given value."},{"name":"q[product_name_or_sku_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `product_name_or_sku_cont` to the given value."},{"name":"q[search_by_product_name_or_sku]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_product_name_or_sku` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[cost_currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carton_package_type_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `carton_weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cartons_per_pallet` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cost_currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `country_of_origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `deleted_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `depth` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `height` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `hs_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `minimum_order_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `order_multiple` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `product_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purchase_unit` | One of `unit`, `carton` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `sku` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `track_inventory` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `units_per_carton` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `width` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[option_values_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `prices_price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |\n| `product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `product_categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `product_channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `product_collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `product_labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `product_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Variant","sortable":["carton_package_type_id","carton_weight","cartons_per_pallet","cost_currency","cost_price","country_of_origin","created_at","deleted_at","depth","discontinue_on","height","hs_code","id","minimum_order_quantity","order_multiple","position","product_id","purchase_unit","sku","track_inventory","units_per_carton","updated_at","weight","width"]},"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/variants":{"get":{"summary":"List variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every variant in the store across all products, for pickers and stock views that are not tied to one product.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches SKU, option value or product name (partial, case-insensitive; at least three characters)."},{"name":"q[available_at_stock_location]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `available_at_stock_location` to the given value."},{"name":"q[product_name_or_sku_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `product_name_or_sku_cont` to the given value."},{"name":"q[search_by_product_name_or_sku]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_product_name_or_sku` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[cost_currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carton_package_type_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `carton_weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cartons_per_pallet` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cost_currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `country_of_origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `deleted_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `depth` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `height` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `hs_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `minimum_order_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `order_multiple` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `product_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purchase_unit` | One of `unit`, `carton` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `sku` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `track_inventory` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `units_per_carton` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `width` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[option_values_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `prices_price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |\n| `product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `product_categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `product_channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `product_collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `product_labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `product_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Variant","sortable":["carton_package_type_id","carton_weight","cartons_per_pallet","cost_currency","cost_price","country_of_origin","created_at","deleted_at","depth","discontinue_on","height","hs_code","id","minimum_order_quantity","order_multiple","position","product_id","purchase_unit","sku","track_inventory","units_per_carton","updated_at","weight","width"]},"responses":{"200":{"description":"variants found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of event name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[event_name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `delivered_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `event_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `execution_time` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `response_code` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `success` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `delivered_at`, `event_name`, `execution_time`, `id`, `response_code`, `success`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"WebhookDelivery","sortable":["created_at","delivered_at","event_name","execution_time","id","response_code","success","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of url (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `url` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`, `url`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"WebhookEndpoint","sortable":["active","created_at","id","name","updated_at","url"]},"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/webhook_events":{"get":{"summary":"List webhook events","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every event a webhook endpoint can subscribe to, including those installed extensions declare. Credential events reach only endpoints that name them, and subscribing to one needs the permission listed; deprecated events name their replacement.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"events returned","content":{"application/json":{}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Catalog","sortable":["active","created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CatalogOrderMinimum","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `sort_order` | One of `manual`, `best_selling`, `price asc`, `price desc`, `available_on desc`, `available_on asc`, `name asc`, `name desc` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Collection","sortable":["automatic","created_at","id","name","permalink","position","products_count","sort_order","updated_at"]},"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `rate` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[commission_rate_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `commission_rate_` | `code`, `created_at`, `enabled`, `id`, `include_shipping`, `kind`, `name`, `position`, `tax_inclusive`, `updated_at`, `value` |\n| `commission_rate_commission_rules_` | `created_at`, `id`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `currency`, `id`, `kind`, `order_id`, `rate`, `tax_amount`, `total`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CommissionLine","sortable":["amount","created_at","currency","id","kind","order_id","rate","tax_amount","total","updated_at"]},"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `include_shipping` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `tax_inclusive` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `value` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[commission_rules_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `commission_rules_` | `created_at`, `id`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `enabled`, `id`, `include_shipping`, `kind`, `name`, `position`, `tax_inclusive`, `updated_at`, `value`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CommissionRate","sortable":["code","created_at","enabled","id","include_shipping","kind","name","position","tax_inclusive","updated_at","value"]},"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its type's `schema`."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"schema":{"type":"object","description":"JSON Schema of the type's `preferences`"},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/addresses":{"get":{"summary":"List company addresses","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's addresses: its sites, billing address and delivery points.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[address1_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `address1` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `address2` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `company` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `postal_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Address","sortable":["address1","address2","city","company","country_code","created_at","first_name","id","last_name","phone","postal_code","state_code","updated_at"]},"responses":{"200":{"description":"addresses found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/companies/{company_id}/invitations":{"get":{"summary":"List company invitations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the invitations into this business that are still waiting to be accepted.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `email`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CompanyInvitation","sortable":["created_at","email","id","updated_at"]},"responses":{"200":{"description":"invitations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyInvitation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CompanyMembership","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[certificate_number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `certificate_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reason_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `pending`, `verified`, `expired`, `revoked` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `certificate_number`, `created_at`, `expires_at`, `id`, `reason_code`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxExemptionCertificate","sortable":["certificate_number","created_at","expires_at","id","reason_code","status","updated_at"]},"responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxIdentifier","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `company`, `division` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `po_number_required` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[children_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `children_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |\n| `children_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |\n| `children_memberships_` | `created_at`, `id`, `updated_at` |\n| `external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |\n| `memberships_` | `created_at`, `id`, `updated_at` |\n| `parent_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |\n| `parent_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |\n| `parent_memberships_` | `created_at`, `id`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Company","sortable":["created_at","id","kind","name","parent_id","po_number_required","updated_at"]},"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit — send the value back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/collections/{collection_id}/custom_fields":{"get":{"summary":"List collection custom fields","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the collection's custom field values.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/sellers/{seller_id}/custom_fields":{"get":{"summary":"List seller custom fields","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the seller's custom field values.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"seller_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryProfile","sortable":["created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List origin groups","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the profile's origin groups: the sets of warehouses that each quote their own delivery rates.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryOriginGroup","sortable":["created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"origin groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryOriginGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_to_sellers` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_to_sellers`, `created_at`, `id`, `name`, `seller_id`, `storefront_visible`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryMethod","sortable":["available_to_sellers","created_at","id","name","seller_id","storefront_visible","updated_at"]},"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator":{"type":"object","description":"How the method is priced: a type from `/delivery_methods/calculators` and its preferences, per that type's `schema`.","properties":{"type":{"type":"string"},"preferences":{"type":"object"}}},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"get":{"summary":"List delivery zones","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the areas delivery methods ship to, each made of countries, states or postal code ranges.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `delivery_profile_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `delivery_profile_id`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryZone","sortable":["created_at","delivery_profile_id","id","name","updated_at"]},"responses":{"200":{"description":"delivery zones found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZone"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/{delivery_method_id}/rules":{"get":{"summary":"List delivery method rules","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the conditions a delivery method must meet to be offered at checkout, such as an order total or weight range.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"delivery_method_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryMethodRule","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"rules found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Integration","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[attached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `attached`."},{"name":"q[filename_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `filename_cont` to the given value."},{"name":"q[unattached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `unattached`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[alt_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Media","sortable":["alt","created_at","id","media_type","position","updated_at"]},"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"List product media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the files placed on a product, in their display order.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[attached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `attached`."},{"name":"q[filename_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `filename_cont` to the given value."},{"name":"q[unattached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `unattached`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[alt_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Media","sortable":["alt","created_at","id","media_type","position","updated_at"]},"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/products/{product_id}/variants/{variant_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}},{"name":"variant_id","in":"path","description":"Variant ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"List variant media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the files placed on one of a product's variants, in their display order.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[attached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `attached`."},{"name":"q[filename_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `filename_cont` to the given value."},{"name":"q[unattached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `unattached`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[alt_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Media","sortable":["alt","created_at","id","media_type","position","updated_at"]},"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `pre_transit`, `in_transit`, `out_for_delivery`, `available_for_pickup`, `delivered`, `return_to_sender`, `failure`, `unknown` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `carrier`, `created_at`, `id`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Delivery","sortable":["carrier","created_at","id","status","tracking_number","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `carrier`, `created_at`, `id`, `source`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ShippingLabel","sortable":["carrier","created_at","id","source","status","tracking_number","updated_at"]},"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `box`, `envelope`, `carton`, `pallet`, `container` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `default`, `id`, `kind`, `name`, `seller_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PackageType","sortable":["created_at","default","id","kind","name","seller_id","updated_at"]},"responses":{"200":{"description":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[option_types_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ProductType","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/purchase_orders":{"get":{"summary":"List purchase orders","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock bought from suppliers. A purchase order carries what a purchase\nhas and a stock transfer does not: a supplier, a unit cost per line and\nan expected arrival date.\n\nOrdered units never count toward availability. Nothing here changes\n`count_on_hand` until `receive` runs, because a merchant who has\nordered stock does not have it.\n\nStatuses are `draft`, `ordered`, `partially_received`, `received`, `over_received` and\n`canceled`. Each move between them is its own endpoint, not a `PATCH`\nthat writes `status`.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[supplier_id_eq]` or `q[expected_at_lteq]`. Expand `items`,\n`supplier` and `destination_location`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number and reference (partial, case-insensitive)."},{"name":"q[closed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `closed`."},{"name":"q[open]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `open`."},{"name":"q[overdue]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `overdue`."},{"name":"q[past_cancel_by]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `past_cancel_by`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `cancel_by` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `closed_short_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `destination_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `expected_at` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `ordered_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `ordered`, `partially_received`, `received`, `over_received`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `supplier_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[destination_location_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `destination_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `destination_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `items_` | `created_at`, `id`, `quantity_ordered`, `quantity_received`, `quantity_rejected`, `unit_cost`, `updated_at`, `variant_id` |\n| `items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `supplier_` | `city`, `contact_name`, `country_code`, `created_at`, `email`, `id`, `name`, `phone`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `cancel_by`, `closed_short_at`, `created_at`, `currency`, `destination_location_id`, `expected_at`, `id`, `number`, `ordered_at`, `received_at`, `reference`, `status`, `supplier_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PurchaseOrder","sortable":["cancel_by","closed_short_at","created_at","currency","destination_location_id","expected_at","id","number","ordered_at","received_at","reference","status","supplier_id","updated_at"]},"responses":{"200":{"description":"purchase orders found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts an order. Nothing is on order and nothing touches availability\nuntil the order is marked as ordered and then received.\n\n`currency` defaults to the store's; set it for a foreign-currency\norder. `expected_at` is a calendar date (`yyyy-mm-dd`) — the day the\nsupplier promised means the same day in every timezone.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"purchase order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"supplier belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_id":{"type":"string"},"destination_location_id":{"type":"string"},"currency":{"type":"string","nullable":true},"expected_at":{"type":"string","format":"date","nullable":true},"reference":{"type":"string","nullable":true,"description":"The supplier's own order number"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_ordered":{"type":"integer"},"unit_cost":{"type":"string"}},"required":["variant_id","quantity_ordered"]}},"metadata":{"type":"object","nullable":true}},"required":["supplier_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/purchase_orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"Get a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"purchase order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_ordered":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Place the order with the supplier","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is\nstamped. Availability is still untouched — ordered stock is not stock\nthe merchant has.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{purchase_order_id}/stock_receipts":{"parameters":[{"name":"purchase_order_id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries booked against an order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the dock counted in, newest first — with its packing-slip reference and what it accepted and refused.\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `receivable_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `receivable_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `received_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_by_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `number`, `receivable_id`, `receivable_type`, `received_at`, `received_by_id`, `received_by_type`, `reference`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockReceipt","sortable":["created_at","id","number","receivable_id","receivable_type","received_at","received_by_id","received_by_type","reference","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Book in a delivery","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment purchased goods first count toward availability. Records\none delivery as a stock receipt: what this delivery brought, per line,\nnot a running total — a second delivery adds to the first.\n\n`quantity_accepted` reaches the shelf; `quantity_rejected` is refused\nand recorded with a `rejection_reason` (`damaged`, `wrong_item`,\n`expired` or `other`), never stocked. Omit `items` to book in\neverything still outstanding, intact.\n\nEach `received` stock movement carries the line's `unit_cost` and\nnames the receipt, so a delivery can be reconciled against the ledger.\n\nThe order stays `partially_received` while any line is still owed,\nsettles in `received` once every line has what it expected, and in\n`over_received` once any line has more.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery booked in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"order has not been placed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true,"description":"The supplier's delivery note or packing slip"},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Take an order back to draft","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reopens a placed order for editing. Only while no delivery has been booked against it; `ordered_at` is cleared.\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Close an order short","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received order whose balance the supplier will not\ndeliver. Nothing moves: what arrived stays on the shelf, the\noutstanding count stays on each line, and the order settles in\n`received` with `closed_short_at` and the `reason` recorded.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/purchase_orders/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Closes what is still outstanding. Nothing is unwound: a purchase order\nnever moved stock until units were received, and units already received\nstay on the shelf because the merchant has them.\n\nA `reason` is appended to the order's notes.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/reporting/saved_reports":{"get":{"summary":"List saved reports","tags":["Reports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's saved reports, each a named query staff can run again.\n\n**Required scope:** `read_reports` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seeded` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `seeded`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SavedReport","sortable":["created_at","id","name","seeded","updated_at"]},"responses":{"200":{"description":"saved reports found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedReport"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerRequirement","sortable":["created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its type's `schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"schema":{"type":"object","description":"JSON Schema of the type's `preferences`"}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `contact_email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `pending`, `invited`, `canceled`, `onboarding`, `ready_for_review`, `approved`, `rejected`, `suspended` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Seller","sortable":["contact_email","created_at","id","name","status","updated_at"]},"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{seller_id}/balances":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's balances","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Where one seller stands with the marketplace, one row per currency:\nwhat they have earned (completed transfers, refund reversals\nincluded), what has been paid to them, what is still owed, and\nearnings the payout provider has not yet confirmed.\n\nComputed from the ledger rather than stored, so the rows carry no id.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"balances listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerBalance"}}},"required":["data"]}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/payouts":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Settle a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sweeps everything this seller is owed into a payout — one per currency,\nsince nothing is ever converted between them.\n\nThis is what the `manual` payout interval means: the scheduled sweep\nruns on each seller's own interval and skips anyone set to `manual`,\nleaving the operator to decide when. It also settles any other seller\nearly.\n\nIt records the settlement rather than sending money: the built-in\nprovider waits to be told the bank transfer went out, which is\n`PATCH /api/v3/admin/seller_payouts/{id}/complete`.\n\nAnswers `422` when there is nothing to settle — no payout account,\nnothing unsettled, or a balance below the seller's minimum.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller settled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}}},"required":["data"]}}}},"422":{"description":"nothing to settle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/requirement_submissions":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's requirement submissions","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this seller submitted against the marketplace requirements, with the review decision on each.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page (max 100)","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reviewed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `pending`, `accepted`, `rejected`, `waived` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[requirement_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `requirement_` | `created_at`, `id`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `reviewed_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerRequirementSubmission","sortable":["created_at","id","reviewed_at","status","updated_at"]},"responses":{"200":{"description":"submissions listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirementSubmission"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_transfers":{"get":{"summary":"List seller transfers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The fund ledger: what each seller earned from an order, and any\nreversals. Read-only, since fulfilment and refunds write it.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of reference (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page (max 100)","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `earning`, `refund_reversal` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `payout_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `provider` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed`, `unresolved` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[payout_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `payout_` | `amount`, `created_at`, `currency`, `id`, `period_end`, `period_start`, `provider`, `reference`, `seller_id`, `status`, `updated_at` |\n| `payout_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `refund_` | `created_at`, `id`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `currency`, `id`, `kind`, `order_id`, `payout_id`, `provider`, `reference`, `seller_id`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerTransfer","sortable":["amount","created_at","currency","id","kind","order_id","payout_id","provider","reference","seller_id","status","updated_at"]},"responses":{"200":{"description":"transfers listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_payouts":{"get":{"summary":"List seller payouts","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Settlements to sellers, each batching the transfers that had\naccumulated since the last. `pending` and `processing` payouts are\nstill owed; `completed` ones reached the seller.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of reference (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page (max 100)","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `period_end` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `period_start` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `provider` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed`, `unresolved` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `currency`, `id`, `period_end`, `period_start`, `provider`, `reference`, `seller_id`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerPayout","sortable":["amount","created_at","currency","id","period_end","period_start","provider","reference","seller_id","status","updated_at"]},"responses":{"200":{"description":"payouts listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_payouts/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller payout prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a payout paid","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the money reached the seller, which is what debits their\nbalance — a balance is earnings less *completed* settlements.\n\nThis is the step the built-in provider waits for: it files the\nsettlement when the payout is created and expects an operator to say\nthe bank transfer went out. A connected provider marks its own payouts\npaid when its webhook reports the money landed.\n\nSend the provider's own id for the transfer as `reference` when there\nis one. Completing a payout that is already complete answers `200`\nwithout recording it twice, so a redelivered webhook or a double click\nis safe.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"payout completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPayout"}}}},"404":{"description":"payout not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The provider's own id for the settlement, when one made it"}}}}}}}},"/api/v3/admin/stock_levels":{"get":{"summary":"List stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One row per variant per stock location, carrying every figure the\nInventory page shows: `count_on_hand` (on hand), `allocated_count`\n(committed to placed orders), `reserved_count` (held by checkouts in\nprogress), `available_count` (on hand minus committed) and\n`incoming_count` (on its way on an open purchase order or a transfer\nin transit). The variant and location are named flat on the row\n(`variant_name`, `variant_sku`, `stock_location_name`, `thumbnail_url`)\nso a list needs no expansion.\n\nFilter with `q[stock_location_id_eq]`, `q[variant_id_eq]` or\n`q[variant_sku_or_variant_product_name_cont]`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of variant sku and variant product name (partial, case-insensitive)."},{"name":"q[with_stock_status][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_stock_status` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[allocated_count_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `allocated_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `count_on_hand` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `incoming_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reserved_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `stock_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[stock_location_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `stock_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `stock_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockLevel","sortable":["allocated_count","count_on_hand","created_at","id","incoming_count","reserved_count","stock_location_id","updated_at","variant_id"]},"responses":{"200":{"description":"stock levels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[reason_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `exchange_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `fulfillment_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `received`, `allocated`, `shipped`, `released`, `adjusted` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purchase_order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `return_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `stock_level_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `stock_receipt_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `stock_transfer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `unit_cost` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[stock_level_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `stock_level_` | `allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id` |\n| `stock_level_stock_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `stock_level_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `exchange_id`, `fulfillment_id`, `id`, `kind`, `order_id`, `purchase_order_id`, `quantity`, `reason`, `return_id`, `stock_level_id`, `stock_receipt_id`, `stock_transfer_id`, `unit_cost`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockMovement","sortable":["created_at","exchange_id","fulfillment_id","id","kind","order_id","purchase_order_id","quantity","reason","return_id","stock_item_id","stock_level_id","stock_receipt_id","stock_transfer_id","unit_cost","updated_at"]},"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_reservations":{"get":{"summary":"List stock reservations","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock held for orders that are being checked out, so it cannot be sold twice before they complete or the hold expires.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `line_item_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `stock_level_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[line_item_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `line_item_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `line_item_order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `line_item_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `line_item_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `stock_level_` | `allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id` |\n| `stock_level_stock_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `stock_level_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `expires_at`, `id`, `line_item_id`, `order_id`, `quantity`, `stock_level_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockReservation","sortable":["created_at","expires_at","id","line_item_id","order_id","quantity","stock_item_id","stock_level_id","updated_at"]},"responses":{"200":{"description":"stock reservations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockReservation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_transfers":{"get":{"summary":"List stock transfers","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock moving between two of the merchant's own warehouses.\n\nA transfer is a trip, not an instant. Units leave the source when the\ntransfer is marked in transit and land at the destination when somebody\ncounts them in — in between they are in flight, gone from one shelf and\nnot yet on the other.\n\nStatuses are `draft`, `ready_to_ship`, `in_transit`,\n`partially_received`, `received`, `over_received` and `canceled`. Each move between them\nis its own endpoint, not a `PATCH` that writes `status`.\n\nReceiving from a supplier is a purchase order, not a transfer with a\nmissing source.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[source_location_id_eq]` or `q[number_or_reference_cont]`. Expand\n`items`, `source_location` and `destination_location`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number and reference (partial, case-insensitive)."},{"name":"q[closed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `closed`."},{"name":"q[open]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `open`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `closed_short_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `destination_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `shipped_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `source_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `draft`, `ready_to_ship`, `in_transit`, `partially_received`, `received`, `over_received`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[destination_location_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `destination_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `destination_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `items_` | `created_at`, `id`, `quantity_received`, `quantity_rejected`, `quantity_shipped`, `updated_at`, `variant_id` |\n| `items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `source_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `source_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `closed_short_at`, `created_at`, `destination_location_id`, `id`, `number`, `received_at`, `reference`, `shipped_at`, `source_location_id`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockTransfer","sortable":["closed_short_at","created_at","destination_location_id","id","number","received_at","reference","shipped_at","source_location_id","status","updated_at"]},"responses":{"200":{"description":"stock transfers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Persists a draft — a packing list the merchant can still edit. Nothing\nmoves until the transfer is marked in transit.\n\nA draft may legitimately open empty and gain lines as the merchant\npacks. Both warehouses are required and must belong to the same store.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock transfer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"warehouse belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"reference":{"type":"string","nullable":true,"description":"The merchant's own label for the trip"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_shipped":{"type":"integer"}},"required":["variant_id","quantity_shipped"]}},"metadata":{"type":"object","nullable":true}},"required":["source_location_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/stock_transfers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"stock transfer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts only. Past `draft` the transfer describes a box that physically\nexists, so it is cancelled rather than deleted — a 422 says so.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock transfer deleted"}}}},"/api/v3/admin/stock_transfers/{id}/mark_ready":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a transfer ready to ship","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Freezes the lines so the warehouse and the merchant are looking at the\nsame list. Nothing leaves the shelf yet.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is ready to ship","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_in_transit":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Send a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment stock leaves the source warehouse: `shipped` movements are\nwritten against the source's levels and `shipped_at` is stamped. The\ndestination is deliberately untouched — the units are in flight.\n\nRefused with a 422 when the source does not hold enough. Pass\n`force: true` to record the departure anyway: a merchant forcing it has\ndecided the box left whatever the ledger claims.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is in transit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Ship even if it drives the source below zero"}}}}}}}},"/api/v3/admin/stock_transfers/{stock_transfer_id}/stock_receipts":{"parameters":[{"name":"stock_transfer_id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries counted in against a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the destination counted in, with what it accepted and refused.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `receivable_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `receivable_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `received_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_by_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `number`, `receivable_id`, `receivable_type`, `received_at`, `received_by_id`, `received_by_type`, `reference`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockReceipt","sortable":["created_at","id","number","receivable_id","receivable_type","received_at","received_by_id","received_by_type","reference","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Count a delivery in","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records one delivery the destination warehouse counted in, as a stock\nreceipt. Partial receipt is the normal case: ten left, eight arrived,\ntwo were crushed in transit. Quantities are this delivery's counts —\na second box adds to the first rather than restating it.\n\n`quantity_accepted` lands on the destination's shelf;\n`quantity_rejected` is refused and recorded with a `rejection_reason`\n(`damaged`, `wrong_item`, `expired` or `other`), never stocked. A\nrefused unit still arrived, so it counts toward the trip being over.\nOmit `items` to count in everything still outstanding, intact.\n\nThe transfer stays `partially_received` while units are still on the\nroad, settles in `received` once everything has arrived, and in\n`over_received` once more arrived than was shipped.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery counted in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"transfer has not shipped yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Take a transfer back to draft","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unfreezes a ready-to-ship transfer so its lines can be changed. Nothing has left the source, so nothing is undone.\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Close a transfer short","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received transfer whose missing units are not going\nto turn up. Nothing moves — they already left the source — and the\ntransfer settles in `received` with `closed_short_at` and the\n`reason` recorded, the outstanding count left on each line.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/stock_transfers/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Calls the trip off.\n\nCancelling a draft or a packed transfer costs nothing — no stock has\nmoved. Cancelling one already in transit needs `on_in_transit`, because\nthe units are physically gone from the source: either they come back\n(`restock`, as if the transfer had never shipped) or they are written\noff as lost (`write_off`). There is no default — guessing would either\ninvent stock or destroy it — so an in-flight cancellation without it is\nrefused with a 422.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"422":{"description":"in-transit cancellation needs a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"on_in_transit":{"type":"string","enum":["restock","write_off"],"description":"Required once the units have left the source"},"reason":{"type":"string","nullable":true,"description":"Recorded against the written-off lines"}}}}}}}},"/api/v3/admin/suppliers":{"get":{"summary":"List suppliers","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Who the merchant buys stock from. A supplier is an address-book entry\nwith a purchasing history — not a party that sells on the store, which\nis a seller.\n\nSuppliers belong to one store, and are soft-deleted so the purchase\norders that name them stay readable.\n\nFilter with Ransack predicates such as\n`q[name_or_contact_name_or_email_cont]` or `q[country_code_eq]`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name, contact name, and email (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `contact_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `city`, `contact_name`, `country_code`, `created_at`, `email`, `id`, `name`, `phone`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Supplier","sortable":["city","contact_name","country_code","created_at","email","id","name","phone","updated_at"]},"responses":{"200":{"description":"suppliers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a supplier to this store's address book. The address is inline —\nstreet, city, state and country live on the supplier itself, the same\nshape a stock location uses.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"supplier created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"required":["name"]}}},"required":true}}},"/api/v3/admin/suppliers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Supplier ID","schema":{"type":"string"}}],"get":{"summary":"Get a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"404":{"description":"supplier not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}}}},"required":true}},"delete":{"summary":"Delete a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the supplier, so the purchase orders naming it stay\nreadable. Refused with a 422 while a purchase order still points at it.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"supplier deleted"}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject short names, e.g. [\"product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceSchema":{"type":"object","description":"The JSON Schema (draft 2020-12) of a type's `preferences`: one property per setting, with `format` (`money`, `currency`, `iso-country`, `prefixed-id`, …), `enum`, `default`, `x-spree-secret` for a secret and `x-spree-prefix` for an id list. Unknown keys are refused.","additionalProperties":true},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"Actor":{"type":"object","properties":{"id":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"label":{"type":"string","nullable":true}},"required":["id","type","label"],"x-typelizer":true},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by_label":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email","created_by_type","created_by_label"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"order_minimum":{"type":"string","nullable":true},"order_minimum_shortfall":{"type":"string","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","item_total","adjustment_total","discount_total","tax_total","included_tax_total","additional_tax_total","total","gift_card_total","amount_due","delivery_total","fee_total","store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string","enum":["explicit","automatic","base"]},"break_count":{"type":"number"},"amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"amount":{"type":"string"}},"required":["min_quantity","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","external_references","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"]},"guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_routing_strategy":{"type":"string","nullable":true,"description":"Order routing strategy; null inherits the store setting. Built-in: rules. Extensions may register more."},"stock_location_ids":{"type":"array","items":{"type":"string"}},"default_catalog_id":{"type":"string","nullable":true}},"required":["id","name","code","active","default","storefront_access","guest_checkout","created_at","updated_at","order_routing_strategy","stock_location_ids","default_catalog_id"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","pre_tax_amount","included_tax_total","additional_tax_total","tax_total","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["open","approved","resolved","denied","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id","created_by_type"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["is_equal_to","is_not_equal_to","contains","does_not_contain"]},"type":{"type":"string","description":"Rule type. Built-in: tag, available_on, sale. Extensions may register more."}},"required":["id","value","match_policy","type"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["percentage","fixed"]},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string","enum":["percentage","fixed"]},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more."},"commission_rate_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/CommissionRulePreferences"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"seller_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"sellers":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","product_ids","seller_ids","category_ids"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"]},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"array","items":{"type":"object"}},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string","enum":["checkout","registration","account","admin","newsletter","anonymization","unknown","import","storefront"]},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"array","items":{"type":"object"}}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"resource_type":{"type":"string","description":"Shorthand of the resource the field attaches to, for example product, variant, order, customer or category. Discover the full list from the resource_types endpoint; extensions may register more."}},"required":["id","namespace","key","label","field_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at","resource_type"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DashboardCounter":{"type":"object","properties":{"key":{"type":"string","description":"Registered counter name. The dashboard translates it; built-in: orders_to_fulfill, payments_to_collect, open_returns, open_exchanges, open_claims, low_stock_items, out_of_stock_items."},"value":{"type":"number"},"link":{"type":"object","nullable":true,"description":"The list filter that shows exactly the rows counted, or null when no list can."},"nav":{"type":"string","nullable":true,"description":"Sidebar entry key this count badges, or null."}},"required":["key","value","link","nav"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string","enum":["access","erasure"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more."},"preferences":{"$ref":"#/components/schemas/DeliveryMethodRulePreferences"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","preferences","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"fulfillment_provider":{"type":"string","description":"Fulfillment provider. Built-in: manual, digital, pickup, pickup_point. Provider gems register more (e.g. easy_post)."},"pickup_point_provider":{"type":"string","nullable":true,"description":"Pickup point network. None built in; provider gems register them."},"rate_provider":{"type":"string","nullable":true,"description":"Rate provider; null prices through the calculator. Built-in: internal, freight. Provider gems register more (e.g. easy_post)."},"calculator":{"allOf":[{"$ref":"#/components/schemas/DeliveryMethodCalculator"}],"nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","storefront_visible","tracking_url","available_to_sellers","created_at","updated_at","deleted_at","markup_flat","markup_percent","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","fulfillment_provider","pickup_point_provider","rate_provider","calculator"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Profile kind. Built-in: shipping, digital. Extensions may register more."},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"array","items":{"type":"object"}},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","unpriced","freight_summary","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","pre_transit","in_transit","out_for_delivery","available_for_pickup","delivered","return_to_sender","failure","unknown"]},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_type":{"type":"string","nullable":true,"description":"Digital asset provider; null is an uploaded file. Built-in: file. Extensions may register more."},"provider_name":{"type":"string","description":"Digital asset provider name. Built-in: File. Extensions may register more."},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_settings","created_at","updated_at","provider_type","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"expires_at":{"type":"string","nullable":true},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["promotion","manual"]},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","metadata","created_at","updated_at"],"x-typelizer":true},"EmailTemplateDraft":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"lock_version":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"updated_by_id":{"type":"string","nullable":true},"updated_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"updated_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","lock_version","created_at","updated_at","updated_by_id","updated_by_type"],"x-typelizer":true},"EmailTemplatePreview":{"type":"object","properties":{"id":{"type":"string","nullable":true},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"email_key":{"type":"string"},"variables":{"type":"object"}},"required":["id","subject","html","text","email_key","variables"],"x-typelizer":true},"EmailTemplateRevision":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"created_at":{"type":"string"},"published_by_id":{"type":"string","nullable":true},"published_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"published_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","created_at","published_by_id","published_by_type"],"x-typelizer":true},"EmailTemplateSampleRecord":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"created_at":{"type":"string"}},"required":["id","label","created_at"],"x-typelizer":true},"EmailTemplate":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"language":{"type":"string"},"customized_languages":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["email","layout","partial"]},"customized":{"type":"boolean"},"published_at":{"type":"string","nullable":true},"default_subject":{"type":"string","nullable":true},"default_body":{"type":"string"},"published_language":{"type":"string","nullable":true},"default_changed":{"type":"boolean"},"base_subject":{"type":"string","nullable":true},"base_body":{"type":"string","nullable":true},"draft":{"allOf":[{"$ref":"#/components/schemas/EmailTemplateDraft"}],"nullable":true}},"required":["id","key","subject","body","language","customized_languages","kind","customized","published_at","default_subject","default_body","published_language","default_changed","base_subject","base_body","draft"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_tax_total":{"type":"string"},"new_tax_total":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_tax_total","new_tax_total","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","fulfilled","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"anyOf":[{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"]},{"type":"string"}],"description":"What sort of charge this is. `duty` is a customs duty on a cross-border order and is not taxed; the other kinds are. Extensions may register further kinds."},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","metadata","created_at","updated_at"],"x-typelizer":true},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["on_hand","backordered","shipped","returned"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["unfulfilled","fulfilled","delivered","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"fulfilled_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"array","items":{"type":"object"}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","unpriced","cost","total","discount_total","additional_tax_total","included_tax_total","tax_total","status","fulfillment_type","fulfilled_at","delivered_at","items","deliveries","metadata","created_at","updated_at","adjustment_total","pre_tax_amount","order_id","stock_location_id","documents","labels","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["active","partially_redeemed","redeemed","canceled","expired"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true,"description":"Import type. Built-in: products, product_translations, customers, price_list_prices. Extensions may register more."},"status":{"anyOf":[{"type":"string","enum":["pending","mapping","completed_mapping","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"delimiter":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","delimiter","price_list_id","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Integration type, registered by the provider gem that owns it (for example the EasyPost provider). Core ships none."},"group":{"type":"string","nullable":true},"preferences":{"$ref":"#/components/schemas/IntegrationPreferences"}},"required":["id","name","active","created_at","updated_at","type","group","preferences"],"x-typelizer":true},"InvitationAcceptanceLink":{"type":"object","properties":{"id":{"type":"string"},"acceptance_url":{"type":"string"}},"required":["id","acceptance_url"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"total":{"type":"string"},"adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"price_list_name":{"type":"string","nullable":true},"catalog_id":{"type":"string","nullable":true},"catalog_name":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","total","adjustment_total","additional_tax_total","included_tax_total","discount_total","pre_tax_amount","discounted_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","price_list_id","price_list_name","catalog_id","catalog_name","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"country_isos":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_provider":{"type":"string","nullable":true,"description":"Tax provider; null uses the store default. Built-in: internal. Provider gems register more."}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","country_isos","supported_locales","created_at","updated_at","tax_provider"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string","enum":["image","video","external_video"]},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string","enum":["dropdown","color_swatch","buttons"]},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","confirmation_delivered","store_owner_notification_delivered","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: preferred_location, default_location, minimize_splits. Extensions may register more."},"channel_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/OrderRoutingRulePreferences"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"total":{"type":"string"},"gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"delivery_total":{"type":"string"},"fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string","enum":["draft","placed","canceled"]},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"metadata":{"type":"object"},"cancel_note":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment_total":{"type":"string"},"commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"approver_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"approver":{"$ref":"#/components/schemas/Actor"},"canceler_id":{"type":"string","nullable":true},"canceler_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"canceler":{"$ref":"#/components/schemas/Actor"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","adjustment_total","discount_total","tax_total","included_tax_total","additional_tax_total","total","gift_card_total","amount_due","delivery_total","fee_total","store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","metadata","cancel_note","canceled_at","approved_at","created_at","updated_at","payment_total","commission_amount_total","commission_tax_total","commission_total","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","approver_type","canceler_id","canceler_type","created_by_id","created_by_type","cancel_reason_id","cancel_reason_name","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"volume":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume","seller_id","seller_name"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","description":"Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe."},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"$ref":"#/components/schemas/PaymentMethodPreferences"},"logo_url":{"type":"string","nullable":true},"docs_url":{"type":"string","nullable":true},"third_party":{"type":"boolean"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","logo_url","docs_url","third_party"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["checkout","processing","pending","completed","failed","void","invalid"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}}},"required":["id","payment_method_id","response_code","number","status","amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"PaymentSplit":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"authorized_amount":{"type":"string"},"captured_amount":{"type":"string"},"refunded_amount":{"type":"string"},"claimed_amount":{"type":"string"},"net_captured_amount":{"type":"string"},"refundable_amount":{"type":"string"},"payment_id":{"type":"string"},"payment_number":{"type":"string","nullable":true},"order_id":{"type":"string"},"order_number":{"type":"string","nullable":true}},"required":["id","currency","created_at","updated_at","authorized_amount","captured_amount","refunded_amount","claimed_amount","net_captured_amount","refundable_amount","payment_id","payment_number","order_id","order_number"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","currency","amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["draft","active","inactive","scheduled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"position":{"type":"number"},"match_policy":{"type":"string","enum":["all","any"]},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: channel_rule, customer_group_rule, market_rule, user_rule, volume_rule, zone_rule. Extensions may register more."},"price_list_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/PriceRulePreferences"},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"min_quantity":{"type":"number"},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","currency","amount","compare_at_amount","price_list_id","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"anyOf":[{"type":"string","enum":["draft","active","archived","proposed","rejected"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","withdrawn"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Action type. Built-in: create_adjustment, create_item_adjustments, create_line_items, free_shipping. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: currency, country, channel, market, item_total, product, customer, customer_group, first_order, customer_logged_in, one_use_per_user, category, option_value. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/PromotionRulePreferences"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"PurchaseOrderItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_ordered":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"currency":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"unit_cost":{"type":"string"},"total_cost":{"type":"string"},"purchase_order_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_ordered","quantity_received","quantity_rejected","quantity_over","outstanding","currency","created_at","updated_at","unit_cost","total_cost","purchase_order_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"PurchaseOrder":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"ordered_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expected_at":{"type":"string","nullable":true},"cancel_by":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_ordered_total":{"type":"number"},"editable":{"type":"boolean"},"subtotal":{"type":"string"},"supplier_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"supplier":{"$ref":"#/components/schemas/Supplier"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","currency","reference","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","ordered_at","received_at","closed_short_at","created_at","updated_at","expected_at","cancel_by","closed_short","quantity_ordered_total","editable","subtotal","supplier_id","destination_location_id"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_amount":{"type":"string"},"refunder_id":{"type":"string","nullable":true},"refunder_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"refunder":{"$ref":"#/components/schemas/Actor"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at","tax_amount","refunder_id","refunder_type"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"type":"string"},"refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","included_tax_total","additional_tax_total","tax_total","refund_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","refunded","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"refund_tax_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"documents":{"type":"array","items":{"type":"object"}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["id","number","status","order_id","reason_id","refund_total","refund_tax_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type","refunded_total","refundable_total","documents","labels","deliveries"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SavedReport":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"query":{"type":"object"},"seeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"author_name":{"type":"string","nullable":true}},"required":["id","name","description","query","seeded","created_at","updated_at","user_id","author_name"],"x-typelizer":true},"SellerBalance":{"type":"object","properties":{"currency":{"type":"string"},"settlement_currency":{"type":"string"},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"earned":{"type":"string"},"pending":{"type":"string"},"payable":{"type":"string"},"paid":{"type":"string"},"balance":{"type":"string"}},"required":["currency","settlement_currency","converted","seller_id","earned","pending","payable","paid","balance"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","status","currency","reference","metadata","period_start","period_end","created_at","updated_at","amount","seller_id","seller_name","transfers_count","provider"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"$ref":"#/components/schemas/SellerRequirementPreferences"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string","enum":["complete","incomplete","pending","rejected"]},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted","rejected","waived"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["pending","invited","canceled","onboarding","ready_for_review","approved","rejected","suspended"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["earning","refund_reversal"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"settled_amount":{"type":"string","nullable":true},"settled_currency":{"type":"string","nullable":true},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","kind","status","currency","reference","metadata","created_at","updated_at","amount","settled_amount","settled_currency","converted","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number","provider"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["purchased","uploaded"]},"status":{"anyOf":[{"type":"string","enum":["purchased","refund_requested","refunded"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string","enum":["fulfillment","return"]},"cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"reserved_count":{"type":"number"},"incoming_count":{"type":"number"},"purchasable_count":{"type":"number"},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_name":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","reserved_count","incoming_count","purchasable_count","variant_name","variant_sku","created_at","updated_at","stock_location_name","product_id","options_text","thumbnail_url","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"anyOf":[{"type":"string","enum":["warehouse","store","fulfillment_center"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true,"enum":["received","allocated","shipped","released","adjusted"]},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"stock_location_name":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true},"stock_receipt_id":{"type":"string","nullable":true},"purchase_order_id":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"return_number":{"type":"string","nullable":true},"exchange_number":{"type":"string","nullable":true},"stock_transfer_number":{"type":"string","nullable":true},"purchase_order_number":{"type":"string","nullable":true},"unit_cost":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","stock_location_id","stock_location_name","variant_id","variant_name","variant_sku","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id","stock_receipt_id","purchase_order_id","order_number","return_number","exchange_number","stock_transfer_number","purchase_order_number","unit_cost"],"x-typelizer":true},"StockReceiptItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"number"},"quantity_rejected":{"type":"number"},"rejection_reason":{"type":"string","nullable":true,"enum":["damaged","wrong_item","expired","other"]},"notes":{"type":"string","nullable":true},"line_type":{"type":"string","enum":["purchase_order_item","stock_transfer_item"]},"line_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_accepted","quantity_rejected","rejection_reason","notes","line_type","line_id","variant_id","product_id","variant_name","variant_sku","thumbnail_url"],"x-typelizer":true},"StockReceipt":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"quantity_accepted_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"received_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"receivable_type":{"type":"string","enum":["purchase_order","stock_transfer"]},"receivable_id":{"type":"string"},"received_by_id":{"type":"string","nullable":true},"received_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"received_by":{"$ref":"#/components/schemas/Actor"},"items_count":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockReceiptItem"}}},"required":["id","number","reference","notes","metadata","quantity_accepted_total","quantity_rejected_total","received_at","created_at","updated_at","receivable_type","receivable_id","received_by_id","received_by_type","items_count"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransferItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_shipped":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_transfer_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_shipped","quantity_received","quantity_rejected","quantity_over","outstanding","created_at","updated_at","stock_transfer_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"shipped_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_shipped_total":{"type":"number"},"editable":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","created_at","updated_at","source_location_id","destination_location_id","status","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","shipped_at","received_at","closed_short_at","deleted_at","closed_short","quantity_shipped_total","editable"],"x-typelizer":true},"StoreCreditEvent":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"authorization_code":{"type":"string","nullable":true},"display_action":{"type":"string","nullable":true},"amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"store_credit_id":{"type":"string"},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true}},"required":["id","action","authorization_code","display_action","amount","created_at","updated_at","store_credit_id","originator_type","originator_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount_authorized":{"type":"string"},"outstanding":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"}},"required":["id","amount","amount_used","amount_remaining","currency","memo","metadata","created_at","updated_at","amount_authorized","outstanding","customer_id","created_by_id","originator_type","originator_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_routing_strategy":{"type":"string","description":"Order routing strategy. Built-in: rules. Extensions may register more."},"payout_provider":{"type":"string","nullable":true,"description":"Payout provider; null uses the installation default. Built-in: system. Provider gems register more (e.g. stripe)."},"admin_locale":{"type":"string","nullable":true},"timezone":{"type":"string"},"storefront_url":{"type":"string","nullable":true},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"unit_system":{"type":"string"},"storefront_access":{"type":"string","enum":["public","prices_hidden","login_required"]},"guest_checkout":{"type":"boolean"},"always_include_confirm_step":{"type":"boolean"},"company_field_enabled":{"type":"boolean"},"address_requires_company":{"type":"boolean"},"address_requires_phone":{"type":"boolean"},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"track_inventory_levels":{"type":"boolean"},"stock_reservations_enabled":{"type":"boolean"},"low_stock_threshold":{"type":"number"},"tax_using_ship_address":{"type":"boolean"},"track_price_history":{"type":"boolean"},"show_products_without_price":{"type":"boolean"},"disable_sku_validation":{"type":"boolean"},"pricing_provider":{"type":"string"},"inventory_provider":{"type":"string"},"pricing_provider_failure_policy":{"type":"string","enum":["fallback","strict"]},"inventory_provider_failure_policy":{"type":"string","enum":["fallback","strict"]},"default_payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"]},"auto_approve_sellers":{"type":"boolean"},"auto_approve_seller_products":{"type":"boolean"},"send_seller_transactional_emails":{"type":"boolean"},"document_number_format":{"type":"string","enum":["sequential","random"]},"order_number_prefix":{"type":"string"},"order_number_suffix":{"type":"string"},"order_number_sequence_start":{"type":"number"},"limit_digital_download_count":{"type":"boolean"},"digital_asset_authorized_clicks":{"type":"number"},"limit_digital_download_days":{"type":"boolean"},"digital_asset_authorized_days":{"type":"number"},"send_consumer_transactional_emails":{"type":"boolean"},"email_accent_color":{"type":"string","nullable":true},"email_background_color":{"type":"string","nullable":true},"email_card_color":{"type":"string","nullable":true},"email_text_color":{"type":"string","nullable":true},"email_heading_color":{"type":"string","nullable":true},"email_font":{"type":"string","nullable":true,"enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]},"order_number_sequence_started":{"type":"boolean"},"default_minimum_payout_amount":{"type":"string","nullable":true},"default_commission_tax_rate":{"type":"string","nullable":true},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","created_at","updated_at","order_routing_strategy","payout_provider","admin_locale","timezone","storefront_url","weight_unit","unit_system","storefront_access","guest_checkout","always_include_confirm_step","company_field_enabled","address_requires_company","address_requires_phone","capture_method","track_inventory_levels","stock_reservations_enabled","low_stock_threshold","tax_using_ship_address","track_price_history","show_products_without_price","disable_sku_validation","pricing_provider","inventory_provider","pricing_provider_failure_policy","inventory_provider_failure_policy","default_payouts_schedule_interval","auto_approve_sellers","auto_approve_seller_products","send_seller_transactional_emails","document_number_format","order_number_prefix","order_number_suffix","order_number_sequence_start","limit_digital_download_count","digital_asset_authorized_clicks","limit_digital_download_days","digital_asset_authorized_days","send_consumer_transactional_emails","email_accent_color","email_background_color","email_card_color","email_text_color","email_heading_color","email_font","order_number_sequence_started","default_minimum_payout_amount","default_commission_tax_rate","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"Supplier":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"purchase_orders_count":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"can_be_deleted":{"type":"boolean"}},"required":["id","name","contact_name","email","phone","notes","address1","address2","city","state_name","state_code","country_code","postal_code","purchase_orders_count","metadata","created_at","updated_at","deleted_at","can_be_deleted"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","verified","expired","revoked"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more."},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true,"enum":["pending","verified","unverified","unavailable","unsupported"]},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true,"enum":["override","company","customer"]},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"credit":{"type":"boolean"},"rate":{"type":"string","nullable":true},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"return_line_item_id":{"type":"string","nullable":true},"claim_line_item_id":{"type":"string","nullable":true},"exchange_line_item_id":{"type":"string","nullable":true},"amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"original_tax_line_id":{"type":"string","nullable":true}},"required":["id","label","included","credit","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","return_line_item_id","claim_line_item_id","exchange_line_item_id","amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at","original_tax_line_id"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"rate":{"type":"string","nullable":true},"rate_percent":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","rate","rate_percent","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true,"enum":["unit","carton"]},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","weight_unit","dimensions_unit","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","cost_price","preorderable","tax_category_id","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true},"WebhookEvent":{"type":"object","properties":{"name":{"type":"string"},"group":{"type":"string"},"credential_permission":{"type":"string","nullable":true},"credential":{"type":"boolean"},"deprecated":{"type":"boolean"},"replaced_by":{"type":"string","nullable":true}},"required":["name","group","credential_permission","credential","deprecated","replaced_by"],"x-typelizer":true},"CommissionRuleCategoryRulePreferences":{"type":"object","properties":{"category_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ctg_[A-Za-z0-9]+$","x-spree-prefix":"ctg"},"default":[]}},"additionalProperties":false},"CommissionRuleItemTotalRulePreferences":{"type":"object","properties":{"min_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"max_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"CommissionRuleProductRulePreferences":{"type":"object","properties":{},"additionalProperties":false},"CommissionRuleSellerRulePreferences":{"type":"object","properties":{"seller_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^sel_[A-Za-z0-9]+$","x-spree-prefix":"sel"},"default":[]}},"additionalProperties":false},"CommissionRulePreferences":{"description":"Settings of a commission rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/CommissionRuleCategoryRulePreferences"},{"$ref":"#/components/schemas/CommissionRuleItemTotalRulePreferences"},{"$ref":"#/components/schemas/CommissionRuleProductRulePreferences"},{"$ref":"#/components/schemas/CommissionRuleSellerRulePreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"category_rule":"#/components/schemas/CommissionRuleCategoryRulePreferences","item_total_rule":"#/components/schemas/CommissionRuleItemTotalRulePreferences","product_rule":"#/components/schemas/CommissionRuleProductRulePreferences","seller_rule":"#/components/schemas/CommissionRuleSellerRulePreferences"}},"DeliveryCalculatorDigitalDeliveryPreferences":{"type":"object","properties":{"amounts":{"type":"object","additionalProperties":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"default":{},"x-spree-property-names":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorFlatPercentItemTotalPreferences":{"type":"object","properties":{"flat_percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"}},"additionalProperties":false},"DeliveryCalculatorFlatRatePreferences":{"type":"object","properties":{"amounts":{"type":"object","additionalProperties":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"default":{},"x-spree-property-names":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorFlexiRatePreferences":{"type":"object","properties":{"first_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"additional_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"max_items":{"type":"integer","default":0},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorPerItemPreferences":{"type":"object","properties":{"amounts":{"type":"object","additionalProperties":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"default":{},"x-spree-property-names":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorPriceSackPreferences":{"type":"object","properties":{"minimal_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"normal_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"discount_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorPreferences":{"description":"Settings of a delivery calculator, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/DeliveryCalculatorDigitalDeliveryPreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorFlatPercentItemTotalPreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorFlatRatePreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorFlexiRatePreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorPerItemPreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorPriceSackPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"digital_delivery":"#/components/schemas/DeliveryCalculatorDigitalDeliveryPreferences","flat_percent_item_total":"#/components/schemas/DeliveryCalculatorFlatPercentItemTotalPreferences","flat_rate":"#/components/schemas/DeliveryCalculatorFlatRatePreferences","flexi_rate":"#/components/schemas/DeliveryCalculatorFlexiRatePreferences","per_item":"#/components/schemas/DeliveryCalculatorPerItemPreferences","price_sack":"#/components/schemas/DeliveryCalculatorPriceSackPreferences"}},"DeliveryMethodRuleChannelRulePreferences":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ch_[A-Za-z0-9]+$","x-spree-prefix":"ch"},"default":[]}},"additionalProperties":false},"DeliveryMethodRuleCompanyRulePreferences":{"type":"object","properties":{"company_orders_only":{"type":"boolean","default":true}},"additionalProperties":false},"DeliveryMethodRuleExcludedProductsRulePreferences":{"type":"object","properties":{},"additionalProperties":false},"DeliveryMethodRuleItemTotalRulePreferences":{"type":"object","properties":{"minimum_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"maximum_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"DeliveryMethodRuleVolumeRulePreferences":{"type":"object","properties":{"minimum_volume":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"maximum_volume":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"DeliveryMethodRuleWeightRulePreferences":{"type":"object","properties":{"minimum_weight":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"maximum_weight":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"DeliveryMethodRulePreferences":{"description":"Settings of a delivery method rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/DeliveryMethodRuleChannelRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleCompanyRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleExcludedProductsRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleItemTotalRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleVolumeRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleWeightRulePreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"channel_rule":"#/components/schemas/DeliveryMethodRuleChannelRulePreferences","company_rule":"#/components/schemas/DeliveryMethodRuleCompanyRulePreferences","excluded_products_rule":"#/components/schemas/DeliveryMethodRuleExcludedProductsRulePreferences","item_total_rule":"#/components/schemas/DeliveryMethodRuleItemTotalRulePreferences","volume_rule":"#/components/schemas/DeliveryMethodRuleVolumeRulePreferences","weight_rule":"#/components/schemas/DeliveryMethodRuleWeightRulePreferences"}},"IntegrationPreferences":{"description":"Settings of a integration, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{}},"OrderRoutingRuleDefaultLocationPreferences":{"type":"object","properties":{},"additionalProperties":false},"OrderRoutingRuleMinimizeSplitsPreferences":{"type":"object","properties":{},"additionalProperties":false},"OrderRoutingRulePreferredLocationPreferences":{"type":"object","properties":{},"additionalProperties":false},"OrderRoutingRulePreferences":{"description":"Settings of a order routing rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/OrderRoutingRuleDefaultLocationPreferences"},{"$ref":"#/components/schemas/OrderRoutingRuleMinimizeSplitsPreferences"},{"$ref":"#/components/schemas/OrderRoutingRulePreferredLocationPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"default_location":"#/components/schemas/OrderRoutingRuleDefaultLocationPreferences","minimize_splits":"#/components/schemas/OrderRoutingRuleMinimizeSplitsPreferences","preferred_location":"#/components/schemas/OrderRoutingRulePreferredLocationPreferences"}},"PaymentMethodBogusPreferences":{"type":"object","properties":{"dummy_key":{"type":"string","default":"PUBLICKEY123"},"dummy_secret_key":{"type":"string","x-spree-secret":true,"nullable":true}},"additionalProperties":false},"PaymentMethodCheckPreferences":{"type":"object","properties":{},"additionalProperties":false},"PaymentMethodCustomPaymentSourceMethodPreferences":{"type":"object","properties":{},"additionalProperties":false},"PaymentMethodStoreCreditPreferences":{"type":"object","properties":{},"additionalProperties":false},"PaymentMethodPreferences":{"description":"Settings of a payment method, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PaymentMethodBogusPreferences"},{"$ref":"#/components/schemas/PaymentMethodCheckPreferences"},{"$ref":"#/components/schemas/PaymentMethodCustomPaymentSourceMethodPreferences"},{"$ref":"#/components/schemas/PaymentMethodStoreCreditPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"bogus":"#/components/schemas/PaymentMethodBogusPreferences","check":"#/components/schemas/PaymentMethodCheckPreferences","custom_payment_source_method":"#/components/schemas/PaymentMethodCustomPaymentSourceMethodPreferences","store_credit":"#/components/schemas/PaymentMethodStoreCreditPreferences"}},"PriceRuleChannelRulePreferences":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ch_[A-Za-z0-9]+$","x-spree-prefix":"ch"},"default":[]}},"additionalProperties":false},"PriceRuleCustomerGroupRulePreferences":{"type":"object","properties":{"customer_group_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^cg_[A-Za-z0-9]+$","x-spree-prefix":"cg"},"default":[]}},"additionalProperties":false},"PriceRuleMarketRulePreferences":{"type":"object","properties":{"market_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^mkt_[A-Za-z0-9]+$","x-spree-prefix":"mkt"},"default":[]}},"additionalProperties":false},"PriceRuleUserRulePreferences":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^cust_[A-Za-z0-9]+$","x-spree-prefix":"cust"},"default":[]}},"additionalProperties":false},"PriceRuleVolumeRulePreferences":{"type":"object","properties":{"min_quantity":{"type":"integer","default":1},"max_quantity":{"type":"integer","nullable":true}},"additionalProperties":false},"PriceRulePreferences":{"description":"Settings of a price rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PriceRuleChannelRulePreferences"},{"$ref":"#/components/schemas/PriceRuleCustomerGroupRulePreferences"},{"$ref":"#/components/schemas/PriceRuleMarketRulePreferences"},{"$ref":"#/components/schemas/PriceRuleUserRulePreferences"},{"$ref":"#/components/schemas/PriceRuleVolumeRulePreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"channel_rule":"#/components/schemas/PriceRuleChannelRulePreferences","customer_group_rule":"#/components/schemas/PriceRuleCustomerGroupRulePreferences","market_rule":"#/components/schemas/PriceRuleMarketRulePreferences","user_rule":"#/components/schemas/PriceRuleUserRulePreferences","volume_rule":"#/components/schemas/PriceRuleVolumeRulePreferences"}},"PromotionCalculatorFlatPercentItemTotalPreferences":{"type":"object","properties":{"flat_percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"}},"additionalProperties":false},"PromotionCalculatorFlatRatePreferences":{"type":"object","properties":{"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"},"apply_only_on_full_priced_items":{"type":"boolean","default":false}},"additionalProperties":false},"PromotionCalculatorFlexiRatePreferences":{"type":"object","properties":{"first_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"additional_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"max_items":{"type":"integer","default":0},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"},"apply_only_on_full_priced_items":{"type":"boolean","default":false}},"additionalProperties":false},"PromotionCalculatorPercentOnLineItemPreferences":{"type":"object","properties":{"percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"apply_only_on_full_priced_items":{"type":"boolean","default":false}},"additionalProperties":false},"PromotionCalculatorTieredFlatRatePreferences":{"type":"object","properties":{"tiers":{"type":"array","items":{"type":"object","properties":{"threshold":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"value":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["threshold","value"],"additionalProperties":false},"default":[]},"base_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"PromotionCalculatorTieredPercentPreferences":{"type":"object","properties":{"tiers":{"type":"array","items":{"type":"object","properties":{"threshold":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"value":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["threshold","value"],"additionalProperties":false},"default":[]},"base_percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"}},"additionalProperties":false},"PromotionCalculatorPreferences":{"description":"Settings of a promotion calculator, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PromotionCalculatorFlatPercentItemTotalPreferences"},{"$ref":"#/components/schemas/PromotionCalculatorFlatRatePreferences"},{"$ref":"#/components/schemas/PromotionCalculatorFlexiRatePreferences"},{"$ref":"#/components/schemas/PromotionCalculatorPercentOnLineItemPreferences"},{"$ref":"#/components/schemas/PromotionCalculatorTieredFlatRatePreferences"},{"$ref":"#/components/schemas/PromotionCalculatorTieredPercentPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"flat_percent_item_total":"#/components/schemas/PromotionCalculatorFlatPercentItemTotalPreferences","flat_rate":"#/components/schemas/PromotionCalculatorFlatRatePreferences","flexi_rate":"#/components/schemas/PromotionCalculatorFlexiRatePreferences","percent_on_line_item":"#/components/schemas/PromotionCalculatorPercentOnLineItemPreferences","tiered_flat_rate":"#/components/schemas/PromotionCalculatorTieredFlatRatePreferences","tiered_percent":"#/components/schemas/PromotionCalculatorTieredPercentPreferences"}},"PromotionRuleCategoryPreferences":{"type":"object","properties":{"match_policy":{"type":"string","enum":["any","all"],"default":"any"}},"additionalProperties":false},"PromotionRuleChannelPreferences":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ch_[A-Za-z0-9]+$","x-spree-prefix":"ch"},"default":[]}},"additionalProperties":false},"PromotionRuleCountryPreferences":{"type":"object","properties":{"country_codes":{"type":"array","items":{"type":"string","format":"iso-country","pattern":"^[A-Z]{2}$"},"default":[]},"country_id":{"type":"integer","nullable":true},"country_code":{"type":"string","format":"iso-country","pattern":"^[A-Z]{2}$","nullable":true}},"additionalProperties":false},"PromotionRuleCurrencyPreferences":{"type":"object","properties":{"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$","nullable":true}},"additionalProperties":false},"PromotionRuleCustomerPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleCustomerGroupPreferences":{"type":"object","properties":{"customer_group_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^cg_[A-Za-z0-9]+$","x-spree-prefix":"cg"},"default":[]}},"additionalProperties":false},"PromotionRuleCustomerLoggedInPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleFirstOrderPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleItemTotalPreferences":{"type":"object","properties":{"amount_min":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"100"},"operator_min":{"type":"string","default":">"},"amount_max":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"operator_max":{"type":"string","default":"<"}},"additionalProperties":false},"PromotionRuleMarketPreferences":{"type":"object","properties":{"market_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^mkt_[A-Za-z0-9]+$","x-spree-prefix":"mkt"},"default":[]}},"additionalProperties":false},"PromotionRuleOneUsePerUserPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleOptionValuePreferences":{"type":"object","properties":{"match_policy":{"type":"string","enum":["any"],"default":"any"},"eligible_values":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^optval_[A-Za-z0-9]+$","x-spree-prefix":"optval"},"default":[]}},"additionalProperties":false},"PromotionRuleProductPreferences":{"type":"object","properties":{"match_policy":{"type":"string","enum":["any","all","none"],"default":"any"}},"additionalProperties":false},"PromotionRulePreferences":{"description":"Settings of a promotion rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PromotionRuleCategoryPreferences"},{"$ref":"#/components/schemas/PromotionRuleChannelPreferences"},{"$ref":"#/components/schemas/PromotionRuleCountryPreferences"},{"$ref":"#/components/schemas/PromotionRuleCurrencyPreferences"},{"$ref":"#/components/schemas/PromotionRuleCustomerPreferences"},{"$ref":"#/components/schemas/PromotionRuleCustomerGroupPreferences"},{"$ref":"#/components/schemas/PromotionRuleCustomerLoggedInPreferences"},{"$ref":"#/components/schemas/PromotionRuleFirstOrderPreferences"},{"$ref":"#/components/schemas/PromotionRuleItemTotalPreferences"},{"$ref":"#/components/schemas/PromotionRuleMarketPreferences"},{"$ref":"#/components/schemas/PromotionRuleOneUsePerUserPreferences"},{"$ref":"#/components/schemas/PromotionRuleOptionValuePreferences"},{"$ref":"#/components/schemas/PromotionRuleProductPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"category":"#/components/schemas/PromotionRuleCategoryPreferences","channel":"#/components/schemas/PromotionRuleChannelPreferences","country":"#/components/schemas/PromotionRuleCountryPreferences","currency":"#/components/schemas/PromotionRuleCurrencyPreferences","customer":"#/components/schemas/PromotionRuleCustomerPreferences","customer_group":"#/components/schemas/PromotionRuleCustomerGroupPreferences","customer_logged_in":"#/components/schemas/PromotionRuleCustomerLoggedInPreferences","first_order":"#/components/schemas/PromotionRuleFirstOrderPreferences","item_total":"#/components/schemas/PromotionRuleItemTotalPreferences","market":"#/components/schemas/PromotionRuleMarketPreferences","one_use_per_user":"#/components/schemas/PromotionRuleOneUsePerUserPreferences","option_value":"#/components/schemas/PromotionRuleOptionValuePreferences","product":"#/components/schemas/PromotionRuleProductPreferences"}},"SellerRequirementAcceptTermsPreferences":{"type":"object","properties":{"terms_body":{"type":"string","x-spree-widget":"textarea","nullable":true},"terms_effective_from":{"type":"string","format":"date","nullable":true},"terms_url":{"type":"string","nullable":true}},"additionalProperties":false},"SellerRequirementAttestationPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementBillingAddressPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementCompleteProfilePreferences":{"type":"object","properties":{"require_about":{"type":"boolean","default":true},"require_logo":{"type":"boolean","default":true},"require_cover_photo":{"type":"boolean","default":false},"require_contact_email":{"type":"boolean","default":true}},"additionalProperties":false},"SellerRequirementDeliveryMethodPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementDocumentPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementMinimumProductsPreferences":{"type":"object","properties":{"minimum_count":{"type":"integer","default":1}},"additionalProperties":false},"SellerRequirementOperatorReviewPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPackageTypePreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPayoutAccountPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPolicyPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementRequiredCustomFieldsPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementReturnsAddressPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPreferences":{"description":"Settings of a seller requirement, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/SellerRequirementAcceptTermsPreferences"},{"$ref":"#/components/schemas/SellerRequirementAttestationPreferences"},{"$ref":"#/components/schemas/SellerRequirementBillingAddressPreferences"},{"$ref":"#/components/schemas/SellerRequirementCompleteProfilePreferences"},{"$ref":"#/components/schemas/SellerRequirementDeliveryMethodPreferences"},{"$ref":"#/components/schemas/SellerRequirementDocumentPreferences"},{"$ref":"#/components/schemas/SellerRequirementMinimumProductsPreferences"},{"$ref":"#/components/schemas/SellerRequirementOperatorReviewPreferences"},{"$ref":"#/components/schemas/SellerRequirementPackageTypePreferences"},{"$ref":"#/components/schemas/SellerRequirementPayoutAccountPreferences"},{"$ref":"#/components/schemas/SellerRequirementPolicyPreferences"},{"$ref":"#/components/schemas/SellerRequirementRequiredCustomFieldsPreferences"},{"$ref":"#/components/schemas/SellerRequirementReturnsAddressPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"accept_terms":"#/components/schemas/SellerRequirementAcceptTermsPreferences","attestation":"#/components/schemas/SellerRequirementAttestationPreferences","billing_address":"#/components/schemas/SellerRequirementBillingAddressPreferences","complete_profile":"#/components/schemas/SellerRequirementCompleteProfilePreferences","delivery_method":"#/components/schemas/SellerRequirementDeliveryMethodPreferences","document":"#/components/schemas/SellerRequirementDocumentPreferences","minimum_products":"#/components/schemas/SellerRequirementMinimumProductsPreferences","operator_review":"#/components/schemas/SellerRequirementOperatorReviewPreferences","package_type":"#/components/schemas/SellerRequirementPackageTypePreferences","payout_account":"#/components/schemas/SellerRequirementPayoutAccountPreferences","policy":"#/components/schemas/SellerRequirementPolicyPreferences","required_custom_fields":"#/components/schemas/SellerRequirementRequiredCustomFieldsPreferences","returns_address":"#/components/schemas/SellerRequirementReturnsAddressPreferences"}},"DeliveryMethodCalculator":{"type":"object","description":"How the delivery method prices a shipment","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"preferences":{"$ref":"#/components/schemas/DeliveryCalculatorPreferences"}},"required":["type","preferences"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"preferences":{"$ref":"#/components/schemas/PromotionCalculatorPreferences"}},"required":["type","preferences"]}}}}\ No newline at end of file+{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It is honoured only on the\ndashboard's origin and for an account that is staff of the store —\notherwise it is silently ignored and the link opens the dashboard's\nreset page. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Honoured only on the dashboard origin, for an account that is staff of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."},"sample_data":{"type":"boolean","description":"Load the demo catalog, customers and orders in the background once the admin account exists."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of origin (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[origin_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `origin`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"AllowedOrigin","sortable":["created_at","id","origin","updated_at"]},"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ApiKey","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name and pretty name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `children_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `depth` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `pretty_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[parent_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Category","sortable":["automatic","children_count","created_at","depth","id","name","parent_id","permalink","position","pretty_name","products_count","updated_at"]},"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/custom_fields":{"get":{"summary":"List category custom fields","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the category's custom field values.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Channel","sortable":["active","code","created_at","default","id","name","store_id","updated_at"]},"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy shorthand (built-in: `rules`). `null` inherits the store setting."},"storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy shorthand (built-in: `rules`). `null` inherits the store setting."},"storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[active_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `store_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `channel_id`, `created_at`, `id`, `position`, `store_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OrderRoutingRule","sortable":["active","channel_id","created_at","id","position","store_id","type","updated_at"]},"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of namespace, key, and label (partial, case-insensitive)."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[key_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `field_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `key` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `namespace` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `resource_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `searchable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `sortable` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `field_type`, `id`, `key`, `label`, `namespace`, `resource_type`, `searchable`, `sortable`, `storefront_visible`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomFieldDefinition","sortable":["created_at","field_type","id","key","label","namespace","resource_type","searchable","sortable","storefront_visible","updated_at"]},"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type token (`short_text`, `long_text`, `rich_text`, `number`, …). An extension type that has no token is named by its registered class instead."},"resource_type":{"type":"string","description":"Shorthand of the owning resource, e.g. `product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomerGroup","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/custom_fields":{"get":{"summary":"List customer custom fields","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's custom field values.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/customers/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/api/v3/admin/consent_records":{"get":{"summary":"List consent records","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the consents customers gave or withdrew, newest first, as evidence of what each one agreed to and when.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `accepted` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purpose` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `recorded_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `source` | One of `checkout`, `registration`, `account`, `admin`, `newsletter`, `anonymization`, `unknown`, `import`, `storefront` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `accepted`, `created_at`, `email`, `id`, `purpose`, `recorded_at`, `source`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ConsentRecord","sortable":["accepted","created_at","email","id","purpose","recorded_at","source","updated_at"]},"responses":{"200":{"description":"consent records found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsentRecord"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/data_requests":{"get":{"summary":"List data requests","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the requests customers made to export or erase their personal data, newest first.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[access]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `access`."},{"name":"q[erasure]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `erasure`."},{"name":"q[in_progress]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_progress`."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `access`, `erasure` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `requested_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `completed_at`, `created_at`, `email`, `id`, `kind`, `number`, `requested_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DataRequest","sortable":["completed_at","created_at","email","id","kind","number","requested_at","status","updated_at"]},"responses":{"200":{"description":"data requests found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DataRequest"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[address1_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `address1` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `address2` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `company` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `postal_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Address","sortable":["address1","address2","city","company","country_code","created_at","first_name","id","last_name","phone","postal_code","state_code","updated_at"]},"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CreditCard","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of memo (partial, case-insensitive)."},{"name":"q[from_gift_card]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `from_gift_card`."},{"name":"q[outstanding]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `outstanding`."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `memo` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[created_by_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `created_by_` | `created_at`, `email`, `first_name`, `id`, `last_name`, `updated_at` |\n| `created_by_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `created_by_id`, `currency`, `customer_id`, `id`, `memo`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StoreCredit","sortable":["amount","created_at","created_by_id","currency","customer_id","id","memo","updated_at"]},"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers/{customer_id}/tax_identifiers":{"get":{"summary":"List customer tax registrations","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's own tax registrations, one per kind.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxIdentifier","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"registrations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxIdentifier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches email, first name, last name or full name (partial, case-insensitive)."},{"name":"q[anonymized]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `anonymized`."},{"name":"q[with_min_total_spent]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `with_min_total_spent` to the given value."},{"name":"q[with_standing_for_company][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_standing_for_company` to the given value."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `accepts_email_marketing` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[addresses_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Customer","sortable":["accepts_email_marketing","created_at","email","first_name","id","last_name","phone","updated_at"]},"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/email_templates":{"get":{"summary":"List email templates","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every email template merchants may edit: the emails customers\nreceive, the email layout and the shared partials. Each shows what\ncustomers receive now (the store's published version, else Spree's\ndefault) and any draft in progress. Staff emails are not editable.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default) for the version every language uses","schema":{"type":"string"}}],"responses":{"200":{"description":"email templates found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The template key with dots, e.g. `spree.order_mailer.confirm_email`","schema":{"type":"string"}}],"get":{"summary":"Get an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the template for one language: what customers receive now,\nSpree's default, and the draft with its `lock_version`. When Spree's\ndefault changed since the store's version started from it,\n`default_changed` is true and `base_body` holds the default it\nstarted from, to compare with `default_body`.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (`draft.updated_by`)","schema":{"type":"string"}}],"responses":{"200":{"description":"email template found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"404":{"description":"not an editable template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Revert an email template to Spree's default","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Goes back to Spree's default for one language and discards the draft.\nThe store's published versions are kept, so one can still be restored.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"email template reverted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/draft":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"put":{"summary":"Save an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Saves the draft, in any state; customers keep receiving the published\nversion until it is published. Send the `lock_version` the draft was\nloaded with: a save made from an older copy is refused with 409,\nnaming who saved last. The first save starts from what is published,\nelse Spree's default.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"draft saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"409":{"description":"saved by someone else since it was loaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"lock_version":{"type":"integer"},"rebase":{"type":"boolean","description":"Marks the draft as based on Spree's current default, after reviewing what changed in it"}}}}}}},"delete":{"summary":"Discard an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"lock_version","in":"query","required":false,"description":"The draft's `lock_version` as last seen; a draft saved since is refused with 409","schema":{"type":"integer"}}],"responses":{"200":{"description":"draft discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/publication":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Publish an email template draft","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Makes the draft what customers receive. The draft is first rendered\nwith sample data; one that does not render (for the layout or a\npartial: in any email using it) is refused with 422, listing each\nproblem with its email and line.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"draft published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}},"422":{"description":"the draft does not render","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer","description":"The draft's `lock_version` as reviewed; a draft saved since is refused with 409"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/preview":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Preview an email template","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renders the template with sample data built from the store's latest\nmatching record, or the one `record_id` names, and returns the email\nwith the variables it was rendered with. An unsaved `subject` and\n`body` take the place of the current version. The layout and partials\nrender inside an email, `email_key` or the first one. `branding`\npreviews colors and a font before they are saved to the store.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"email template rendered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplatePreview"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string","description":"The record to build sample data from"},"email_key":{"type":"string","description":"For the layout or a partial, the email to show it in"},"branding":{"type":"object","description":"Unsaved colors and font to preview, named like the store's `email_*` settings","properties":{"accent_color":{"type":"string"},"background_color":{"type":"string"},"card_color":{"type":"string"},"text_color":{"type":"string"},"heading_color":{"type":"string"},"font":{"type":"string","enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]}}}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/test_email":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"post":{"summary":"Send a test email","tags":["Email Templates"],"security":[{"bearer_auth":[]}],"description":"Sends the template, rendered as the preview renders it, to the\nsigned-in admin, and never to another address: the sample data comes\nfrom a real customer's records. Takes the same body as the preview.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"test email queued","content":{"application/json":{"schema":{"type":"object","properties":{"sent_to":{"type":"string"}},"required":["sent_to"]}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"record_id":{"type":"string"},"email_key":{"type":"string"}}}}}}}},"/api/v3/admin/email_templates/{email_template_id}/sample_records":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List records to preview an email template with","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The store's five latest records the template can be previewed with,\nnewest first, to pass as `record_id` to the preview. For the layout\nand partials, those of the email `email_key` names. Empty for an\nemail that needs no record.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"email_key","in":"query","required":false,"description":"For the layout or a partial, the email to show it in","schema":{"type":"string"}}],"responses":{"200":{"description":"records found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}}],"get":{"summary":"List email template revisions","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every version of the template published in one language, newest\nfirst. Reverting to Spree's default keeps them.\n\n\n**Required scope:** `read_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"language","in":"query","required":false,"description":"A language code, or `any` (the default)","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (`published_by`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"EmailTemplateRevision","sortable":["created_at","id"]},"responses":{"200":{"description":"revisions found","content":{"application/json":{}}}}}},"/api/v3/admin/email_templates/{email_template_id}/revisions/{revision_id}/restoration":{"parameters":[{"name":"email_template_id","in":"path","required":true,"description":"The template key with dots","schema":{"type":"string"}},{"name":"revision_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Restore an email template revision","tags":["Email Templates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Copies the revision into the draft, to be published like any change.\nSend the draft's `lock_version` when one is open, as when saving it.\n\n\n**Required scope:** `write_email_templates` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"revision copied into the draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string"},"lock_version":{"type":"integer"}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `format` | One of `csv` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `format`, `id`, `number`, `seller_id`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Export","sortable":["created_at","format","id","number","seller_id","type","updated_at"]},"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers","price_list_prices","purchase_orders"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/files":{"post":{"summary":"Upload a file","tags":["Files"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts a file and returns a `signed_id` to send to the endpoint that\nuses it — `signed_id` on product media, `avatar_signed_id` on a\ncustomer, `attachment_signed_id` on an import, and so on.\n\nTwo ways to send the bytes, one response:\n\n- **Presigned** (JSON): send the file's metadata, then `PUT` the bytes\n to `upload.url` with exactly `upload.headers`. Use this for anything\n large — the bytes go straight to storage.\n- **Multipart**: send the bytes in a `file` part. The file is stored\n before the response, so `upload` is null. Limited to 10 MB by default.\n\n`signed_id` is opaque: pass it back unchanged and never parse it. It\nstops being attachable at `expires_at`, one day after the upload.\n\n`visibility` picks the storage: `public` (the default) for images and\nvideos customers see, `private` for documents, imports and digital\nproducts. Public uploads accept web images, videos and CSV; private\nuploads accept any type. `checksum` is the file's MD5 digest,\nbase64-encoded — the storage service verifies the bytes against it.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"presigned upload target created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUpload"}}}},"422":{"description":"content type not allowed for a public upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"checksum":{"type":"string","description":"Base64-encoded MD5 digest of the file"},"visibility":{"type":"string","enum":["public","private"],"default":"public"},"file":{"type":"string","format":"binary","description":"The bytes, for a multipart upload"}},"required":["filename","content_type"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"checksum":{"type":"string","description":"Base64-encoded MD5 digest of the file"},"visibility":{"type":"string","enum":["public","private"],"default":"public"},"file":{"type":"string","format":"binary","description":"The bytes, for a multipart upload"}},"required":["filename","content_type"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Fulfillment","sortable":["created_at","id","number","updated_at"]},"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Exchange and claim replacements are moved only out of a named `source_fulfillment_id`, which is how a canceled replacement is sent again. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"source_fulfillment_id":{"type":"string","description":"The only fulfillment of this order to move units from, its exchange and claim replacements included. Omit to take the customer's bought units from every unshipped fulfillment"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[prefix_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `prefix` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `prefix`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"GiftCardBatch","sortable":["created_at","id","prefix","updated_at"]},"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of code (partial, case-insensitive)."},{"name":"q[active]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `active`."},{"name":"q[expired]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `expired`."},{"name":"q[partially_redeemed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `partially_redeemed`."},{"name":"q[redeemed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `redeemed`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `expires_at` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `gift_card_batch_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `state` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `active`, `partially_redeemed`, `redeemed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[batch_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `batch_` | `created_at`, `id`, `prefix`, `updated_at` |\n| `customers_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customers_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customers_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customers_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customers_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customers_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customers_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customers_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `orders_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `users_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `users_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `users_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `users_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `users_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `users_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `users_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `users_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `created_by_id`, `currency`, `customer_id`, `expires_at`, `gift_card_batch_id`, `id`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"GiftCard","sortable":["code","created_at","created_by_id","currency","customer_id","expires_at","gift_card_batch_id","id","state","status","updated_at"]},"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `customer_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"customer_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `mapping`, `completed_mapping`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `seller_id`, `status`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Import","sortable":["created_at","id","number","seller_id","status","type","updated_at"]},"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/files`\nand pass the returned `signed_id` as `attachment_signed_id`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment_signed_id"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations","price_list_prices","purchase_orders"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"attachment_signed_id":{"type":"string","description":"The `signed_id` returned by POST /api/v3/admin/files."},"delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `row_number` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `row_number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ImportRow","sortable":["created_at","id","row_number","status","updated_at"]},"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `default_locale` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `currency`, `default_locale`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Market","sortable":["created_at","currency","default_locale","id","name","position","updated_at"]},"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types/{option_type_id}/custom_fields":{"get":{"summary":"List option type custom fields","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the option type's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"option_type_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name and label (partial, case-insensitive)."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `dropdown`, `color_swatch`, `buttons` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `label` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OptionType","sortable":["created_at","id","kind","label","name","position","updated_at"]},"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/claims":{"get":{"summary":"List claims","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every damage or missing-item claim in the store, across all orders.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Claim","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"claims listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/claims":{"get":{"summary":"List order claims","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The damage or missing-item claims opened on one order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Claim","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"claims listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/custom_fields":{"get":{"summary":"List order custom fields","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the order's custom field values.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/digital_links":{"get":{"summary":"List digital links","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the download links issued for digital products bought in this store, newest first.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DigitalLink","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"digital links found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/exchanges":{"get":{"summary":"List exchanges","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every exchange in the store, across all orders.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Exchange","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"exchanges listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/exchanges":{"get":{"summary":"List order exchanges","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The exchanges opened on one order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Exchange","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"exchanges listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[country_code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `included` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `provider_id` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `taxability_reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `country_code`, `created_at`, `id`, `included`, `provider_id`, `state_code`, `taxability_reason`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxLine","sortable":["country_code","created_at","id","included","provider_id","state_code","taxability_reason","updated_at"]},"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Discount","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"string"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"get":{"summary":"List fees","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the order's fees, such as surcharges, handling and gift wrap, on the whole order or on one item or delivery.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Fee","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"fees found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Fee"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"string"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/order_groups":{"get":{"summary":"List order groups","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns checkouts split into one order per seller, grouping the orders placed together.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[customer_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `orders_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `currency`, `email`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OrderGroup","sortable":["created_at","currency","email","id","number","updated_at"]},"responses":{"200":{"description":"order groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[additional_tax_total_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `additional_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `discount_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `included_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `non_taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `pre_tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"LineItem","sortable":["additional_tax_total","adjustment_total","cost_price","created_at","discount_total","id","included_tax_total","non_taxable_adjustment_total","order_id","pre_tax_amount","price","quantity","tax_category_id","taxable_adjustment_total","updated_at","variant_id"]},"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches order number or purchase order number (partial), the billing first or last name, or the exact email."},{"name":"q[complete]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `complete`."},{"name":"q[incomplete]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `incomplete`."},{"name":"q[partially_refunded]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `partially_refunded`."},{"name":"q[refunded]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `refunded`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `considered_risky` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `coupon_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `delivery_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `fulfillment_status` | One of `backorder`, `canceled`, `partial`, `unfulfilled`, `fulfilled`, `delivered`, `pending`, `ready`, `shipped` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `item_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `order_group_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `payment_status` | One of `none`, `authorized`, `partially_paid`, `paid`, `partially_refunded`, `refunded`, `overcharged`, `voided`, `balance_due`, `credit_owed`, `failed`, `void` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `po_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `draft`, `placed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `total_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[bill_address_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `line_items_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `line_items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_group_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `promotions_coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Order","sortable":["channel_id","completed_at","considered_risky","coupon_code","created_at","currency","customer_id","delivery_total","email","fulfillment_status","id","item_total","number","order_group_id","payment_state","payment_status","po_number","seller_id","shipment_state","status","total","total_quantity","updated_at"]},"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"shipping_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\nOn a marketplace, an order holding several sellers' goods becomes one\norder per seller, and the response is the order group they belong to\nwith those orders nested inside it.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/returns":{"get":{"summary":"List returns","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every return in the store, across all orders.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Return","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"returns listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/returns":{"get":{"summary":"List order returns","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The returns opened on one order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Return","sortable":["created_at","id","number","status","updated_at"]},"responses":{"200":{"description":"returns listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/returns/{return_id}/labels":{"get":{"summary":"List return labels","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The shipping labels issued for sending one return back to the store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}},{"name":"return_id","in":"path","required":true,"description":"Return prefixed ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `carrier`, `created_at`, `id`, `source`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ShippingLabel","sortable":["carrier","created_at","id","source","status","tracking_number","updated_at"]},"responses":{"200":{"description":"labels listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PaymentMethod","sortable":["active","created_at","id","name","position","storefront_visible","type","updated_at"]},"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every registered payment provider with the JSON Schema of its `preferences`. `installed` marks a provider the store already has, which a \"Provider\" picker leaves out.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[avs_response_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `avs_response` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cvv_response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `cvv_response_message` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `payment_method_` | `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `avs_response`, `created_at`, `cvv_response_code`, `cvv_response_message`, `id`, `response_code`, `state`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Payment","sortable":["amount","avs_response","created_at","cvv_response_code","cvv_response_message","id","response_code","state","status","updated_at"]},"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `catalog_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `ends_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `match_policy` | One of `all`, `any` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `draft`, `active`, `inactive`, `scheduled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PriceList","sortable":["catalog_id","created_at","ends_at","id","match_policy","name","position","starts_at","status","updated_at"]},"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches the variant's SKU, option value or product name, as variant search does."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `compare_at_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `min_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `price_list_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[price_list_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |\n| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Price","sortable":["amount","compare_at_amount","created_at","currency","id","min_quantity","price_list_id","updated_at","variant_id"]},"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/digital_assets":{"parameters":[{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"get":{"summary":"List product digital assets","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the downloadable files attached to the product's variants, oldest first.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DigitalAsset","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"digital assets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\nAlso filters and sorts on the store's searchable custom fields, as `q[cf_<namespace>_<key>_<predicate>]` and `sort=cf_<namespace>_<key>`.\n\n**Sort by:** `available_on`, `best_selling`, `created_at`, `description`, `discontinue_on`, `id`, `manual`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","best_selling","created_at","description","discontinue_on","id","manual","name","price","seller_id","slug","status","updated_at"],"custom_fields":true},"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_levels:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `owner_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `owner_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `owner_id`, `owner_type`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Policy","sortable":["created_at","id","name","owner_id","owner_type","updated_at"]},"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ClaimReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"claim reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"OrderCancellationReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order cancellation reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"RefundReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"refund reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ReturnReason","sortable":["active","created_at","id","name","updated_at"]},"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"return reason created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"return reason deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[code_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `promotion_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `state` | One of `unused`, `used` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[promotion_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `promotion_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CouponCode","sortable":["code","created_at","id","promotion_id","state","updated_at"]},"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PromotionAction","sortable":["created_at","id","position","updated_at"]},"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PromotionRule","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`).\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name and code (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `coupon_code`, `automatic` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `path` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `promotion_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[coupon_codes_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Promotion","sortable":["code","created_at","expires_at","id","kind","name","path","promotion_category_id","starts_at","updated_at"]},"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Refund","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_locale":{"type":"string"},"timezone":{"type":"string"},"weight_unit":{"type":"string"},"unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Shorthand of the tagged resource: `product`, `order` or `customer`","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/tax_categories":{"get":{"summary":"List tax categories","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the tax categories products and delivery methods can be assigned to, which tax rates then apply to.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `is_default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `tax_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxCategory","sortable":["created_at","id","is_default","name","tax_code","updated_at"]},"responses":{"200":{"description":"tax categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxCategory"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `included_in_price` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `amount`, `country_code`, `created_at`, `id`, `included_in_price`, `name`, `state_code`, `tax_category_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxRate","sortable":["amount","country_code","created_at","id","included_in_price","name","rate","state_code","tax_category_id","updated_at"]},"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `rate` as a\ndecimal string (`\"0.19\"`) or `rate_percent` as a percentage string (`\"19\"`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"rate":{"type":"string","description":"Rate as a decimal string, e.g. \"0.19\""},"rate_percent":{"type":"string","description":"Rate as a percentage string, e.g. \"19\""},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"rate":{"type":"string"},"rate_percent":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[spree_roles_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `email`, `first_name`, `id`, `last_name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"AdminUser","sortable":["created_at","email","first_name","id","last_name","updated_at"]},"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores. Removing a role needs the same rights as granting it, and the store always keeps at least one admin.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Invitation","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{invitation_id}/acceptance_link":{"get":{"summary":"Get an invitation acceptance link","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the link the invitee opens to accept a pending invitation. The link carries the invitation token, so it needs write access to staff and the right to grant the invitation's role; invitation listings never include it.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"invitation_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"acceptance link found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationAcceptanceLink"}}}}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Role","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `pickup_enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `returns_enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockLocation","sortable":["active","country_code","created_at","default","id","kind","name","pickup_enabled","returns_enabled","seller_id","state_code","updated_at"]},"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/store_credits":{"get":{"summary":"List store credits","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every store credit in the current store, across all customers.\nRead-only: issuing, editing and deleting a credit stays nested under\nthe customer that holds it.\n\n`meta.totals` carries the outstanding balance as one row per currency,\nsummed over the same filter this request used — so filtering by a\ncustomer answers that customer's balance and no filter answers the\nstore's liability.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of memo (partial, case-insensitive)."},{"name":"q[from_gift_card]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `from_gift_card`."},{"name":"q[outstanding]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `outstanding`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `memo` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[created_by_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `created_by_` | `created_at`, `email`, `first_name`, `id`, `last_name`, `updated_at` |\n| `created_by_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_orders_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |\n| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `created_by_id`, `currency`, `customer_id`, `id`, `memo`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StoreCredit","sortable":["amount","created_at","created_by_id","currency","customer_id","id","memo","updated_at"]},"responses":{"200":{"description":"store credits found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a store credit","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCredit"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{store_credit_id}/events":{"parameters":[{"name":"store_credit_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List a store credit's ledger","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every movement of the credit's balance, newest first: allocated when\nissued, authorized when a checkout starts against it, captured when\nthat order is paid, and voided or credited back if it is cancelled.\n\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StoreCreditEvent","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"events found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/variants/{variant_id}/custom_fields":{"get":{"summary":"List variant custom fields","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the variant's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"variant_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches SKU, option value or product name (partial, case-insensitive; at least three characters)."},{"name":"q[available_at_stock_location]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `available_at_stock_location` to the given value."},{"name":"q[product_name_or_sku_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `product_name_or_sku_cont` to the given value."},{"name":"q[search_by_product_name_or_sku]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_product_name_or_sku` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[cost_currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carton_package_type_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `carton_weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cartons_per_pallet` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cost_currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `country_of_origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `deleted_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `depth` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `height` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `hs_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `minimum_order_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `order_multiple` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `product_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purchase_unit` | One of `unit`, `carton` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `sku` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `track_inventory` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `units_per_carton` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `width` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[option_values_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `prices_price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |\n| `product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `product_categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `product_channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `product_collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `product_labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `product_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Variant","sortable":["carton_package_type_id","carton_weight","cartons_per_pallet","cost_currency","cost_price","country_of_origin","created_at","deleted_at","depth","discontinue_on","height","hs_code","id","minimum_order_quantity","order_multiple","position","product_id","purchase_unit","sku","track_inventory","units_per_carton","updated_at","weight","width"]},"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_levels, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_levels":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/variants":{"get":{"summary":"List variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every variant in the store across all products, for pickers and stock views that are not tied to one product.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches SKU, option value or product name (partial, case-insensitive; at least three characters)."},{"name":"q[available_at_stock_location]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `available_at_stock_location` to the given value."},{"name":"q[product_name_or_sku_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `product_name_or_sku_cont` to the given value."},{"name":"q[search_by_product_name_or_sku]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_product_name_or_sku` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[cost_currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carton_package_type_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `carton_weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cartons_per_pallet` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `cost_currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `country_of_origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `deleted_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `depth` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `height` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `hs_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `minimum_order_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `order_multiple` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `product_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purchase_unit` | One of `unit`, `carton` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `sku` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `track_inventory` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `units_per_carton` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `width` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[option_values_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `prices_price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |\n| `product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `product_categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `product_channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `product_collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `product_labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `product_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Variant","sortable":["carton_package_type_id","carton_weight","cartons_per_pallet","cost_currency","cost_price","country_of_origin","created_at","deleted_at","depth","discontinue_on","height","hs_code","id","minimum_order_quantity","order_multiple","position","product_id","purchase_unit","sku","track_inventory","units_per_carton","updated_at","weight","width"]},"responses":{"200":{"description":"variants found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of event name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[event_name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `delivered_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `event_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `execution_time` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `response_code` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `success` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `delivered_at`, `event_name`, `execution_time`, `id`, `response_code`, `success`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"WebhookDelivery","sortable":["created_at","delivered_at","event_name","execution_time","id","response_code","success","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of url (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `url` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`, `url`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"WebhookEndpoint","sortable":["active","created_at","id","name","updated_at","url"]},"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/webhook_events":{"get":{"summary":"List webhook events","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every event a webhook endpoint can subscribe to, including those installed extensions declare. Credential events reach only endpoints that name them, and subscribing to one needs the permission listed; deprecated events name their replacement.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"events returned","content":{"application/json":{}}}}}},"/api/v3/admin/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `active`, `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Catalog","sortable":["active","created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CatalogOrderMinimum","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `sort_order` | One of `manual`, `best_selling`, `price asc`, `price desc`, `available_on desc`, `available_on asc`, `name asc`, `name desc` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Collection","sortable":["automatic","created_at","id","name","permalink","position","products_count","sort_order","updated_at"]},"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `rate` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[commission_rate_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `commission_rate_` | `code`, `created_at`, `enabled`, `id`, `include_shipping`, `kind`, `name`, `position`, `tax_inclusive`, `updated_at`, `value` |\n| `commission_rate_commission_rules_` | `created_at`, `id`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `currency`, `id`, `kind`, `order_id`, `rate`, `tax_amount`, `total`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CommissionLine","sortable":["amount","created_at","currency","id","kind","order_id","rate","tax_amount","total","updated_at"]},"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `include_shipping` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `tax_inclusive` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `value` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[commission_rules_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `commission_rules_` | `created_at`, `id`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `code`, `created_at`, `enabled`, `id`, `include_shipping`, `kind`, `name`, `position`, `tax_inclusive`, `updated_at`, `value`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CommissionRate","sortable":["code","created_at","enabled","id","include_shipping","kind","name","position","tax_inclusive","updated_at","value"]},"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its type's `schema`."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"schema":{"type":"object","description":"JSON Schema of the type's `preferences`"},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/addresses":{"get":{"summary":"List company addresses","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's addresses: its sites, billing address and delivery points.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[address1_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `address1` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `address2` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `company` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `postal_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Address","sortable":["address1","address2","city","company","country_code","created_at","first_name","id","last_name","phone","postal_code","state_code","updated_at"]},"responses":{"200":{"description":"addresses found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/companies/{company_id}/invitations":{"get":{"summary":"List company invitations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the invitations into this business that are still waiting to be accepted.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[email_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `email`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CompanyInvitation","sortable":["created_at","email","id","updated_at"]},"responses":{"200":{"description":"invitations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyInvitation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/companies/{company_id}/memberships":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CompanyMembership","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[certificate_number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `certificate_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reason_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `pending`, `verified`, `expired`, `revoked` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `certificate_number`, `created_at`, `expires_at`, `id`, `reason_code`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxExemptionCertificate","sortable":["certificate_number","created_at","expires_at","id","reason_code","status","updated_at"]},"responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document_signed_id` takes the\n`signed_id` returned by `POST /api/v3/admin/files`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document_signed_id":{"type":"string","description":"The `signed_id` returned by POST /api/v3/admin/files."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"TaxIdentifier","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `company`, `division` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `po_number_required` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[children_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `children_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |\n| `children_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |\n| `children_memberships_` | `created_at`, `id`, `updated_at` |\n| `external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |\n| `memberships_` | `created_at`, `id`, `updated_at` |\n| `parent_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |\n| `parent_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |\n| `parent_memberships_` | `created_at`, `id`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Company","sortable":["created_at","id","kind","name","parent_id","po_number_required","updated_at"]},"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit — send the value back verbatim rather than deriving it from the name.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/collections/{collection_id}/custom_fields":{"get":{"summary":"List collection custom fields","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the collection's custom field values.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/sellers/{seller_id}/custom_fields":{"get":{"summary":"List seller custom fields","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the seller's custom field values.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"seller_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"CustomField","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"custom fields found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryProfile","sortable":["created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List origin groups","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the profile's origin groups: the sets of warehouses that each quote their own delivery rates.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryOriginGroup","sortable":["created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"origin groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryOriginGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_to_sellers` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_to_sellers`, `created_at`, `id`, `name`, `seller_id`, `storefront_visible`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryMethod","sortable":["available_to_sellers","created_at","id","name","seller_id","storefront_visible","updated_at"]},"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator":{"type":"object","description":"How the method is priced: a type from `/delivery_methods/calculators` and its preferences, per that type's `schema`.","properties":{"type":{"type":"string"},"preferences":{"type":"object"}}},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"get":{"summary":"List delivery zones","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the areas delivery methods ship to, each made of countries, states or postal code ranges.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `delivery_profile_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `delivery_profile_id`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryZone","sortable":["created_at","delivery_profile_id","id","name","updated_at"]},"responses":{"200":{"description":"delivery zones found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZone"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/{delivery_method_id}/rules":{"get":{"summary":"List delivery method rules","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the conditions a delivery method must meet to be offered at checkout, such as an order total or weight range.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"delivery_method_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"DeliveryMethodRule","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"rules found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Integration","sortable":["created_at","id","updated_at"]},"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[attached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `attached`."},{"name":"q[filename_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `filename_cont` to the given value."},{"name":"q[unattached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `unattached`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[alt_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Media","sortable":["alt","created_at","id","media_type","position","updated_at"]},"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through `POST /api/v3/admin/files`, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"The `signed_id` returned by POST /api/v3/admin/files."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"List product media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the files placed on a product, in their display order.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[attached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `attached`."},{"name":"q[filename_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `filename_cont` to the given value."},{"name":"q[unattached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `unattached`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[alt_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Media","sortable":["alt","created_at","id","media_type","position","updated_at"]},"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/products/{product_id}/variants/{variant_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}},{"name":"variant_id","in":"path","description":"Variant ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"List variant media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the files placed on one of a product's variants, in their display order.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[attached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `attached`."},{"name":"q[filename_cont]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `filename_cont` to the given value."},{"name":"q[unattached]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `unattached`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[alt_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Media","sortable":["alt","created_at","id","media_type","position","updated_at"]},"responses":{"200":{"description":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `pre_transit`, `in_transit`, `out_for_delivery`, `available_for_pickup`, `delivered`, `return_to_sender`, `failure`, `unknown` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `carrier`, `created_at`, `id`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Delivery","sortable":["carrier","created_at","id","status","tracking_number","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[carrier_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `carrier`, `created_at`, `id`, `source`, `status`, `tracking_number`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ShippingLabel","sortable":["carrier","created_at","id","source","status","tracking_number","updated_at"]},"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `box`, `envelope`, `carton`, `pallet`, `container` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `default`, `id`, `kind`, `name`, `seller_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PackageType","sortable":["created_at","default","id","kind","name","seller_id","updated_at"]},"responses":{"200":{"description":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches product name or variant SKU (partial, case-insensitive), and the store's searchable custom fields."},{"name":"q[ascend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `ascend_by_price`."},{"name":"q[descend_by_price]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `descend_by_price`."},{"name":"q[in_categories][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `in_categories` to the given value."},{"name":"q[in_category]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_category` to the given value."},{"name":"q[in_collection]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_collection` to the given value."},{"name":"q[in_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `in_stock`."},{"name":"q[in_taxon]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `in_taxon` to the given value."},{"name":"q[not_discontinued]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `not_discontinued`."},{"name":"q[out_of_stock]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `out_of_stock`."},{"name":"q[price_between][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"description":"Applies `price_between` to the given value."},{"name":"q[price_gte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_gte` to the given value."},{"name":"q[price_lte]","in":"query","required":false,"schema":{"type":"number"},"description":"Applies `price_lte` to the given value."},{"name":"q[search_by_name]","in":"query","required":false,"schema":{"type":"string"},"description":"Applies `search_by_name` to the given value."},{"name":"q[with_option_value_ids][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_option_value_ids` to the given value."},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |\n| `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |\n| `default_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `labels_` | `created_at`, `id`, `name`, `updated_at` |\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |\n| `product_type_` | `created_at`, `id`, `name`, `updated_at` |\n| `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `store_` | `created_at`, `id`, `name`, `updated_at` |\n| `tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `variants_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Product","sortable":["available_on","created_at","description","discontinue_on","id","name","price","seller_id","slug","status","updated_at"]},"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[option_types_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"ProductType","sortable":["created_at","id","name","updated_at"]},"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/purchase_orders":{"get":{"summary":"List purchase orders","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock bought from suppliers. A purchase order carries what a purchase\nhas and a stock transfer does not: a supplier, a unit cost per line and\nan expected arrival date.\n\nOrdered units never count toward availability. Nothing here changes\n`count_on_hand` until `receive` runs, because a merchant who has\nordered stock does not have it.\n\nStatuses are `draft`, `ordered`, `partially_received`, `received`, `over_received` and\n`canceled`. Each move between them is its own endpoint, not a `PATCH`\nthat writes `status`.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[supplier_id_eq]` or `q[expected_at_lteq]`. Expand `items`,\n`supplier` and `destination_location`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number and reference (partial, case-insensitive)."},{"name":"q[closed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `closed`."},{"name":"q[open]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `open`."},{"name":"q[overdue]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `overdue`."},{"name":"q[past_cancel_by]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `past_cancel_by`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `cancel_by` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `closed_short_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `destination_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `expected_at` | Date | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `ordered_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `draft`, `ordered`, `partially_received`, `received`, `over_received`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `supplier_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[destination_location_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `destination_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `destination_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `items_` | `created_at`, `id`, `quantity_ordered`, `quantity_received`, `quantity_rejected`, `unit_cost`, `updated_at`, `variant_id` |\n| `items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `supplier_` | `city`, `contact_name`, `country_code`, `created_at`, `email`, `id`, `name`, `phone`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `cancel_by`, `closed_short_at`, `created_at`, `currency`, `destination_location_id`, `expected_at`, `id`, `number`, `ordered_at`, `received_at`, `reference`, `status`, `supplier_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"PurchaseOrder","sortable":["cancel_by","closed_short_at","created_at","currency","destination_location_id","expected_at","id","number","ordered_at","received_at","reference","status","supplier_id","updated_at"]},"responses":{"200":{"description":"purchase orders found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts an order. Nothing is on order and nothing touches availability\nuntil the order is marked as ordered and then received.\n\n`currency` defaults to the store's; set it for a foreign-currency\norder. `expected_at` is a calendar date (`yyyy-mm-dd`) — the day the\nsupplier promised means the same day in every timezone.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"purchase order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"supplier belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_id":{"type":"string"},"destination_location_id":{"type":"string"},"currency":{"type":"string","nullable":true},"expected_at":{"type":"string","format":"date","nullable":true},"reference":{"type":"string","nullable":true,"description":"The supplier's own order number"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_ordered":{"type":"integer"},"unit_cost":{"type":"string"}},"required":["variant_id","quantity_ordered"]}},"metadata":{"type":"object","nullable":true}},"required":["supplier_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/purchase_orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"Get a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"purchase order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_ordered":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Place the order with the supplier","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is\nstamped. Availability is still untouched — ordered stock is not stock\nthe merchant has.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{purchase_order_id}/stock_receipts":{"parameters":[{"name":"purchase_order_id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries booked against an order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the dock counted in, newest first — with its packing-slip reference and what it accepted and refused.\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `receivable_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `receivable_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `received_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_by_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `number`, `receivable_id`, `receivable_type`, `received_at`, `received_by_id`, `received_by_type`, `reference`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockReceipt","sortable":["created_at","id","number","receivable_id","receivable_type","received_at","received_by_id","received_by_type","reference","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Book in a delivery","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment purchased goods first count toward availability. Records\none delivery as a stock receipt: what this delivery brought, per line,\nnot a running total — a second delivery adds to the first.\n\n`quantity_accepted` reaches the shelf; `quantity_rejected` is refused\nand recorded with a `rejection_reason` (`damaged`, `wrong_item`,\n`expired` or `other`), never stocked. Omit `items` to book in\neverything still outstanding, intact.\n\nEach `received` stock movement carries the line's `unit_cost` and\nnames the receipt, so a delivery can be reconciled against the ledger.\n\nThe order stays `partially_received` while any line is still owed,\nsettles in `received` once every line has what it expected, and in\n`over_received` once any line has more.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery booked in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"order has not been placed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true,"description":"The supplier's delivery note or packing slip"},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Take an order back to draft","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reopens a placed order for editing. Only while no delivery has been booked against it; `ordered_at` is cleared.\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Close an order short","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received order whose balance the supplier will not\ndeliver. Nothing moves: what arrived stays on the shelf, the\noutstanding count stays on each line, and the order settles in\n`received` with `closed_short_at` and the `reason` recorded.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"order closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/purchase_orders/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Closes what is still outstanding. Nothing is unwound: a purchase order\nnever moved stock until units were received, and units already received\nstay on the shelf because the merchant has them.\n\nA `reason` is appended to the order's notes.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/reporting/saved_reports":{"get":{"summary":"List saved reports","tags":["Reports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's saved reports, each a named query staff can run again.\n\n**Required scope:** `read_reports` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seeded` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `seeded`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SavedReport","sortable":["created_at","id","name","seeded","updated_at"]},"responses":{"200":{"description":"saved reports found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SavedReport"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerRequirement","sortable":["created_at","id","name","position","updated_at"]},"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its type's `schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"schema":{"type":"object","description":"JSON Schema of the type's `preferences`"}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `contact_email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `status` | One of `pending`, `invited`, `canceled`, `onboarding`, `ready_for_review`, `approved`, `rejected`, `suspended` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Seller","sortable":["contact_email","created_at","id","name","status","updated_at"]},"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo_signed_id":{"type":"string","nullable":true,"description":"The `signed_id` returned by POST /api/v3/admin/files. Send `null` to remove the image, or omit the key to leave it alone. Same for `square_logo_signed_id` and `cover_photo_signed_id`."},"square_logo_signed_id":{"type":"string","nullable":true},"cover_photo_signed_id":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{seller_id}/balances":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's balances","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Where one seller stands with the marketplace, one row per currency:\nwhat they have earned (completed transfers, refund reversals\nincluded), what has been paid to them, what is still owed, and\nearnings the payout provider has not yet confirmed.\n\nComputed from the ledger rather than stored, so the rows carry no id.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"balances listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerBalance"}}},"required":["data"]}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/payouts":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Settle a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sweeps everything this seller is owed into a payout — one per currency,\nsince nothing is ever converted between them.\n\nThis is what the `manual` payout interval means: the scheduled sweep\nruns on each seller's own interval and skips anyone set to `manual`,\nleaving the operator to decide when. It also settles any other seller\nearly.\n\nIt records the settlement rather than sending money: the built-in\nprovider waits to be told the bank transfer went out, which is\n`PATCH /api/v3/admin/seller_payouts/{id}/complete`.\n\nAnswers `422` when there is nothing to settle — no payout account,\nnothing unsettled, or a balance below the seller's minimum.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller settled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}}},"required":["data"]}}}},"422":{"description":"nothing to settle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/requirement_submissions":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's requirement submissions","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this seller submitted against the marketplace requirements, with the review decision on each.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page (max 100)","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reviewed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `status` | One of `pending`, `accepted`, `rejected`, `waived` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[requirement_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `requirement_` | `created_at`, `id`, `name`, `position`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `id`, `reviewed_at`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerRequirementSubmission","sortable":["created_at","id","reviewed_at","status","updated_at"]},"responses":{"200":{"description":"submissions listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirementSubmission"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_transfers":{"get":{"summary":"List seller transfers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The fund ledger: what each seller earned from an order, and any\nreversals. Read-only, since fulfilment and refunds write it.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of reference (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page (max 100)","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `earning`, `refund_reversal` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `payout_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `provider` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed`, `unresolved` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[payout_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `payout_` | `amount`, `created_at`, `currency`, `id`, `period_end`, `period_start`, `provider`, `reference`, `seller_id`, `status`, `updated_at` |\n| `payout_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `refund_` | `created_at`, `id`, `updated_at` |\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `currency`, `id`, `kind`, `order_id`, `payout_id`, `provider`, `reference`, `seller_id`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerTransfer","sortable":["amount","created_at","currency","id","kind","order_id","payout_id","provider","reference","seller_id","status","updated_at"]},"responses":{"200":{"description":"transfers listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_payouts":{"get":{"summary":"List seller payouts","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Settlements to sellers, each batching the transfers that had\naccumulated since the last. `pending` and `processing` payouts are\nstill owed; `completed` ones reached the seller.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of reference (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page (max 100)","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[currency_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `period_end` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `period_start` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `provider` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `pending`, `processing`, `completed`, `failed`, `unresolved` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `amount`, `created_at`, `currency`, `id`, `period_end`, `period_start`, `provider`, `reference`, `seller_id`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"SellerPayout","sortable":["amount","created_at","currency","id","period_end","period_start","provider","reference","seller_id","status","updated_at"]},"responses":{"200":{"description":"payouts listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/seller_payouts/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller payout prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a payout paid","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the money reached the seller, which is what debits their\nbalance — a balance is earnings less *completed* settlements.\n\nThis is the step the built-in provider waits for: it files the\nsettlement when the payout is created and expects an operator to say\nthe bank transfer went out. A connected provider marks its own payouts\npaid when its webhook reports the money landed.\n\nSend the provider's own id for the transfer as `reference` when there\nis one. Completing a payout that is already complete answers `200`\nwithout recording it twice, so a redelivered webhook or a double click\nis safe.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"payout completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPayout"}}}},"404":{"description":"payout not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The provider's own id for the settlement, when one made it"}}}}}}}},"/api/v3/admin/stock_levels":{"get":{"summary":"List stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One row per variant per stock location, carrying every figure the\nInventory page shows: `count_on_hand` (on hand), `allocated_count`\n(committed to placed orders), `reserved_count` (held by checkouts in\nprogress), `available_count` (on hand minus committed) and\n`incoming_count` (on its way on an open purchase order or a transfer\nin transit). The variant and location are named flat on the row\n(`variant_name`, `variant_sku`, `stock_location_name`, `thumbnail_url`)\nso a list needs no expansion.\n\nFilter with `q[stock_location_id_eq]`, `q[variant_id_eq]` or\n`q[variant_sku_or_variant_product_name_cont]`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of variant sku and variant product name (partial, case-insensitive)."},{"name":"q[with_stock_status][]","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"description":"Applies `with_stock_status` to the given value."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[allocated_count_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `allocated_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `count_on_hand` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `incoming_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reserved_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `stock_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[stock_location_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `stock_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `stock_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |\n| `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |\n| `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |\n| `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockLevel","sortable":["allocated_count","count_on_hand","created_at","id","incoming_count","reserved_count","stock_location_id","updated_at","variant_id"]},"responses":{"200":{"description":"stock levels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[reason_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `exchange_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `fulfillment_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `kind` | One of `received`, `allocated`, `shipped`, `released`, `adjusted` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `purchase_order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `return_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `stock_level_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `stock_receipt_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `stock_transfer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `unit_cost` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[stock_level_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `stock_level_` | `allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id` |\n| `stock_level_stock_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `stock_level_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `exchange_id`, `fulfillment_id`, `id`, `kind`, `order_id`, `purchase_order_id`, `quantity`, `reason`, `return_id`, `stock_level_id`, `stock_receipt_id`, `stock_transfer_id`, `unit_cost`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockMovement","sortable":["created_at","exchange_id","fulfillment_id","id","kind","order_id","purchase_order_id","quantity","reason","return_id","stock_item_id","stock_level_id","stock_receipt_id","stock_transfer_id","unit_cost","updated_at"]},"responses":{"200":{"description":"stock movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_reservations":{"get":{"summary":"List stock reservations","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock held for orders that are being checked out, so it cannot be sold twice before they complete or the hold expires.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[created_at_eq]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `line_item_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `stock_level_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[line_item_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `line_item_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `line_item_order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `line_item_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |\n| `line_item_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `order_` | `channel_id`, `completed_at`, `considered_risky`, `coupon_code`, `created_at`, `currency`, `customer_id`, `delivery_total`, `email`, `fulfillment_status`, `id`, `item_total`, `number`, `order_group_id`, `payment_status`, `po_number`, `seller_id`, `status`, `total`, `total_quantity`, `updated_at` |\n| `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |\n| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |\n| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_line_items_` | `additional_tax_total`, `adjustment_total`, `cost_price`, `created_at`, `discount_total`, `id`, `included_tax_total`, `non_taxable_adjustment_total`, `order_id`, `pre_tax_amount`, `price`, `quantity`, `tax_category_id`, `taxable_adjustment_total`, `updated_at`, `variant_id` |\n| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |\n| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |\n| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |\n| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |\n| `order_store_` | `created_at`, `id`, `name`, `updated_at` |\n| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |\n| `stock_level_` | `allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id` |\n| `stock_level_stock_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `stock_level_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n\n</Accordion>\n\n**Sort by:** `created_at`, `expires_at`, `id`, `line_item_id`, `order_id`, `quantity`, `stock_level_id`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockReservation","sortable":["created_at","expires_at","id","line_item_id","order_id","quantity","stock_item_id","stock_level_id","updated_at"]},"responses":{"200":{"description":"stock reservations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockReservation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_transfers":{"get":{"summary":"List stock transfers","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock moving between two of the merchant's own warehouses.\n\nA transfer is a trip, not an instant. Units leave the source when the\ntransfer is marked in transit and land at the destination when somebody\ncounts them in — in between they are in flight, gone from one shelf and\nnot yet on the other.\n\nStatuses are `draft`, `ready_to_ship`, `in_transit`,\n`partially_received`, `received`, `over_received` and `canceled`. Each move between them\nis its own endpoint, not a `PATCH` that writes `status`.\n\nReceiving from a supplier is a purchase order, not a transfer with a\nmissing source.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[source_location_id_eq]` or `q[number_or_reference_cont]`. Expand\n`items`, `source_location` and `destination_location`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of number and reference (partial, case-insensitive)."},{"name":"q[closed]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `closed`."},{"name":"q[open]","in":"query","required":false,"schema":{"type":"boolean"},"description":"Set to `true` to apply `open`."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `closed_short_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `destination_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `shipped_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `source_location_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `status` | One of `draft`, `ready_to_ship`, `in_transit`, `partially_received`, `received`, `over_received`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n<Accordion title=\"Filters through associations\">\n\nPrefix an associated record's attribute with the association, as in `q[destination_location_id_eq]`. The same predicates apply.\n\n| Prefix | Attributes |\n|---|---|\n| `destination_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `destination_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n| `items_` | `created_at`, `id`, `quantity_received`, `quantity_rejected`, `quantity_shipped`, `updated_at`, `variant_id` |\n| `items_variant_` | `carton_package_type_id`, `carton_weight`, `cartons_per_pallet`, `cost_currency`, `cost_price`, `country_of_origin`, `created_at`, `deleted_at`, `depth`, `discontinue_on`, `height`, `hs_code`, `id`, `minimum_order_quantity`, `order_multiple`, `position`, `product_id`, `purchase_unit`, `sku`, `track_inventory`, `units_per_carton`, `updated_at`, `weight`, `width` |\n| `source_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |\n| `source_location_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |\n\n</Accordion>\n\n**Sort by:** `closed_short_at`, `created_at`, `destination_location_id`, `id`, `number`, `received_at`, `reference`, `shipped_at`, `source_location_id`, `status`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockTransfer","sortable":["closed_short_at","created_at","destination_location_id","id","number","received_at","reference","shipped_at","source_location_id","status","updated_at"]},"responses":{"200":{"description":"stock transfers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Persists a draft — a packing list the merchant can still edit. Nothing\nmoves until the transfer is marked in transit.\n\nA draft may legitimately open empty and gain lines as the merchant\npacks. Both warehouses are required and must belong to the same store.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock transfer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"warehouse belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"reference":{"type":"string","nullable":true,"description":"The merchant's own label for the trip"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_shipped":{"type":"integer"}},"required":["variant_id","quantity_shipped"]}},"metadata":{"type":"object","nullable":true}},"required":["source_location_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/stock_transfers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"stock transfer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts only. Past `draft` the transfer describes a box that physically\nexists, so it is cancelled rather than deleted — a 422 says so.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock transfer deleted"}}}},"/api/v3/admin/stock_transfers/{id}/mark_ready":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a transfer ready to ship","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Freezes the lines so the warehouse and the merchant are looking at the\nsame list. Nothing leaves the shelf yet.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is ready to ship","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_in_transit":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Send a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment stock leaves the source warehouse: `shipped` movements are\nwritten against the source's levels and `shipped_at` is stamped. The\ndestination is deliberately untouched — the units are in flight.\n\nRefused with a 422 when the source does not hold enough. Pass\n`force: true` to record the departure anyway: a merchant forcing it has\ndecided the box left whatever the ledger claims.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer is in transit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Ship even if it drives the source below zero"}}}}}}}},"/api/v3/admin/stock_transfers/{stock_transfer_id}/stock_receipts":{"parameters":[{"name":"stock_transfer_id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries counted in against a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the destination counted in, with what it accepted and refused.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[number_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `receivable_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `receivable_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `received_by_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `received_by_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `created_at`, `id`, `number`, `receivable_id`, `receivable_type`, `received_at`, `received_by_id`, `received_by_type`, `reference`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"StockReceipt","sortable":["created_at","id","number","receivable_id","receivable_type","received_at","received_by_id","received_by_type","reference","updated_at"]},"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Count a delivery in","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records one delivery the destination warehouse counted in, as a stock\nreceipt. Partial receipt is the normal case: ten left, eight arrived,\ntwo were crushed in transit. Quantities are this delivery's counts —\na second box adds to the first rather than restating it.\n\n`quantity_accepted` lands on the destination's shelf;\n`quantity_rejected` is refused and recorded with a `rejection_reason`\n(`damaged`, `wrong_item`, `expired` or `other`), never stocked. A\nrefused unit still arrived, so it counts toward the trip being over.\nOmit `items` to count in everything still outstanding, intact.\n\nThe transfer stays `partially_received` while units are still on the\nroad, settles in `received` once everything has arrived, and in\n`over_received` once more arrived than was shipped.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery counted in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"transfer has not shipped yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Take a transfer back to draft","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unfreezes a ready-to-ship transfer so its lines can be changed. Nothing has left the source, so nothing is undone.\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Close a transfer short","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received transfer whose missing units are not going\nto turn up. Nothing moves — they already left the source — and the\ntransfer settles in `received` with `closed_short_at` and the\n`reason` recorded, the outstanding count left on each line.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/stock_transfers/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Calls the trip off.\n\nCancelling a draft or a packed transfer costs nothing — no stock has\nmoved. Cancelling one already in transit needs `on_in_transit`, because\nthe units are physically gone from the source: either they come back\n(`restock`, as if the transfer had never shipped) or they are written\noff as lost (`write_off`). There is no default — guessing would either\ninvent stock or destroy it — so an in-flight cancellation without it is\nrefused with a 422.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"transfer cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"422":{"description":"in-transit cancellation needs a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"on_in_transit":{"type":"string","enum":["restock","write_off"],"description":"Required once the units have left the source"},"reason":{"type":"string","nullable":true,"description":"Recorded against the written-off lines"}}}}}}}},"/api/v3/admin/suppliers":{"get":{"summary":"List suppliers","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Who the merchant buys stock from. A supplier is an address-book entry\nwith a purchasing history — not a party that sells on the store, which\nis a seller.\n\nSuppliers belong to one store, and are soft-deleted so the purchase\norders that name them stay readable.\n\nFilter with Ransack predicates such as\n`q[name_or_contact_name_or_email_cont]` or `q[country_code_eq]`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"q[search]","in":"query","required":false,"schema":{"type":"string"},"description":"Matches any of name, contact name, and email (partial, case-insensitive)."},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q","in":"query","required":false,"style":"deepObject","explode":true,"schema":{"type":"object","additionalProperties":true},"description":"Attribute filters, as `q[<attribute>_<predicate>]=value`. See Filters above for the list."}],"x-mint":{"content":"## Filters\n\nFilter with `q[<attribute>_<predicate>]=value`, for example `q[name_cont]=…`. Send a list as `q[<attribute>_in][]=a&q[<attribute>_in][]=b`. [How filters work](/api-reference/admin-api/querying#which-filters-an-endpoint-accepts).\n\n| Attribute | Kind | Predicates |\n|---|---|---|\n| `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `contact_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |\n| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |\n| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |\n\n**Sort by:** `city`, `contact_name`, `country_code`, `created_at`, `email`, `id`, `name`, `phone`, `updated_at`. Prefix a field with `-` to sort descending."},"x-spree-filters":{"table":"Supplier","sortable":["city","contact_name","country_code","created_at","email","id","name","phone","updated_at"]},"responses":{"200":{"description":"suppliers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a supplier to this store's address book. The address is inline —\nstreet, city, state and country live on the supplier itself, the same\nshape a stock location uses.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"supplier created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"required":["name"]}}},"required":true}}},"/api/v3/admin/suppliers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Supplier ID","schema":{"type":"string"}}],"get":{"summary":"Get a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"404":{"description":"supplier not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"supplier updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}}}},"required":true}},"delete":{"summary":"Delete a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the supplier, so the purchase orders naming it stay\nreadable. Refused with a 422 while a purchase order still points at it.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"supplier deleted"}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject short names, e.g. [\"product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceSchema":{"type":"object","description":"The JSON Schema (draft 2020-12) of a type's `preferences`: one property per setting, with `format` (`money`, `currency`, `iso-country`, `prefixed-id`, …), `enum`, `default`, `x-spree-secret` for a secret and `x-spree-prefix` for an id list. Unknown keys are refused.","additionalProperties":true},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"Actor":{"type":"object","properties":{"id":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"label":{"type":"string","nullable":true}},"required":["id","type","label"],"x-typelizer":true},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by_label":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email","created_by_type","created_by_label"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"order_minimum":{"type":"string","nullable":true},"order_minimum_shortfall":{"type":"string","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","currency","locale","total_quantity","warnings","coupon_code","item_total","adjustment_total","discount_total","tax_total","included_tax_total","additional_tax_total","total","gift_card_total","amount_due","delivery_total","fee_total","store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string","enum":["explicit","automatic","base"]},"break_count":{"type":"number"},"amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"amount":{"type":"string"}},"required":["min_quantity","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"external_references":{"type":"object"},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","external_references","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"]},"guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_routing_strategy":{"type":"string","nullable":true,"description":"Order routing strategy; null inherits the store setting. Built-in: rules. Extensions may register more."},"stock_location_ids":{"type":"array","items":{"type":"string"}},"default_catalog_id":{"type":"string","nullable":true}},"required":["id","name","code","active","default","storefront_access","guest_checkout","created_at","updated_at","order_routing_strategy","stock_location_ids","default_catalog_id"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","pre_tax_amount","included_tax_total","additional_tax_total","tax_total","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["open","approved","resolved","denied","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id","created_by_type"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["is_equal_to","is_not_equal_to","contains","does_not_contain"]},"type":{"type":"string","description":"Rule type. Built-in: tag, available_on, sale. Extensions may register more."}},"required":["id","value","match_policy","type"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["percentage","fixed"]},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string","enum":["percentage","fixed"]},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more."},"commission_rate_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/CommissionRulePreferences"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"seller_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"sellers":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","product_ids","seller_ids","category_ids"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"]},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"array","items":{"type":"object"}},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string","enum":["checkout","registration","account","admin","newsletter","anonymization","unknown","import","storefront"]},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"array","items":{"type":"object"}}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"resource_type":{"type":"string","description":"Shorthand of the resource the field attaches to, for example product, variant, order, customer or category. Discover the full list from the resource_types endpoint; extensions may register more."}},"required":["id","namespace","key","label","field_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at","resource_type"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DashboardCounter":{"type":"object","properties":{"key":{"type":"string","description":"Registered counter name. The dashboard translates it; built-in: orders_to_fulfill, payments_to_collect, open_returns, open_exchanges, open_claims, low_stock_items, out_of_stock_items."},"value":{"type":"number"},"link":{"type":"object","nullable":true,"description":"The list filter that shows exactly the rows counted, or null when no list can."},"nav":{"type":"string","nullable":true,"description":"Sidebar entry key this count badges, or null."}},"required":["key","value","link","nav"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string","enum":["access","erasure"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more."},"preferences":{"$ref":"#/components/schemas/DeliveryMethodRulePreferences"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","preferences","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"fulfillment_provider":{"type":"string","description":"Fulfillment provider. Built-in: manual, digital, pickup, pickup_point. Provider gems register more (e.g. easy_post)."},"pickup_point_provider":{"type":"string","nullable":true,"description":"Pickup point network. None built in; provider gems register them."},"rate_provider":{"type":"string","nullable":true,"description":"Rate provider; null prices through the calculator. Built-in: internal, freight. Provider gems register more (e.g. easy_post)."},"calculator":{"allOf":[{"$ref":"#/components/schemas/DeliveryMethodCalculator"}],"nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","storefront_visible","tracking_url","available_to_sellers","created_at","updated_at","deleted_at","markup_flat","markup_percent","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","fulfillment_provider","pickup_point_provider","rate_provider","calculator"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Profile kind. Built-in: shipping, digital. Extensions may register more."},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"array","items":{"type":"object"}},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","unpriced","freight_summary","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","pre_transit","in_transit","out_for_delivery","available_for_pickup","delivered","return_to_sender","failure","unknown"]},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_type":{"type":"string","nullable":true,"description":"Digital asset provider; null is an uploaded file. Built-in: file. Extensions may register more."},"provider_name":{"type":"string","description":"Digital asset provider name. Built-in: File. Extensions may register more."},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_settings","created_at","updated_at","provider_type","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"expires_at":{"type":"string","nullable":true},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","expires_at","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string","enum":["promotion","manual"]},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","metadata","created_at","updated_at"],"x-typelizer":true},"EmailTemplateDraft":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"lock_version":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"updated_by_id":{"type":"string","nullable":true},"updated_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"updated_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","lock_version","created_at","updated_at","updated_by_id","updated_by_type"],"x-typelizer":true},"EmailTemplatePreview":{"type":"object","properties":{"id":{"type":"string","nullable":true},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"email_key":{"type":"string"},"variables":{"type":"object"}},"required":["id","subject","html","text","email_key","variables"],"x-typelizer":true},"EmailTemplateRevision":{"type":"object","properties":{"id":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"created_at":{"type":"string"},"published_by_id":{"type":"string","nullable":true},"published_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"published_by":{"$ref":"#/components/schemas/Actor"}},"required":["id","subject","body","created_at","published_by_id","published_by_type"],"x-typelizer":true},"EmailTemplateSampleRecord":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"created_at":{"type":"string"}},"required":["id","label","created_at"],"x-typelizer":true},"EmailTemplate":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string"},"language":{"type":"string"},"customized_languages":{"type":"array","items":{"type":"string"}},"kind":{"type":"string","enum":["email","layout","partial"]},"customized":{"type":"boolean"},"published_at":{"type":"string","nullable":true},"default_subject":{"type":"string","nullable":true},"default_body":{"type":"string"},"published_language":{"type":"string","nullable":true},"default_changed":{"type":"boolean"},"base_subject":{"type":"string","nullable":true},"base_body":{"type":"string","nullable":true},"draft":{"allOf":[{"$ref":"#/components/schemas/EmailTemplateDraft"}],"nullable":true}},"required":["id","key","subject","body","language","customized_languages","kind","customized","published_at","default_subject","default_body","published_language","default_changed","base_subject","base_body","draft"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_tax_total":{"type":"string"},"new_tax_total":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_tax_total","new_tax_total","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","fulfilled","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"anyOf":[{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty","exchange"]},{"type":"string"}],"description":"What sort of charge this is. `duty` is a customs duty on a cross-border order and is not taxed; the other kinds are. Extensions may register further kinds."},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","metadata","created_at","updated_at"],"x-typelizer":true},"FileUpload":{"type":"object","properties":{"signed_id":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"number"},"visibility":{"type":"string","enum":["public","private"]},"expires_at":{"type":"string"},"upload":{"allOf":[{"$ref":"#/components/schemas/FileUploadTarget"}],"nullable":true}},"required":["signed_id","filename","content_type","byte_size","visibility","expires_at","upload"],"x-typelizer":true},"FileUploadTarget":{"type":"object","properties":{"method":{"type":"string"},"url":{"type":"string"},"headers":{"type":"object"}},"required":["method","url","headers"],"x-typelizer":true},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["on_hand","backordered","shipped","returned"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["unfulfilled","fulfilled","delivered","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"fulfilled_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"array","items":{"type":"object"}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","unpriced","cost","total","discount_total","additional_tax_total","included_tax_total","tax_total","status","fulfillment_type","fulfilled_at","delivered_at","items","deliveries","metadata","created_at","updated_at","adjustment_total","pre_tax_amount","order_id","stock_location_id","documents","labels","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["active","partially_redeemed","redeemed","canceled","expired"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true,"description":"Import type. Built-in: products, product_translations, customers, price_list_prices. Extensions may register more."},"status":{"anyOf":[{"type":"string","enum":["pending","mapping","completed_mapping","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"delimiter":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","delimiter","price_list_id","seller_name","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Integration type, registered by the provider gem that owns it (for example the EasyPost provider). Core ships none."},"group":{"type":"string","nullable":true},"preferences":{"$ref":"#/components/schemas/IntegrationPreferences"}},"required":["id","name","active","created_at","updated_at","type","group","preferences"],"x-typelizer":true},"InvitationAcceptanceLink":{"type":"object","properties":{"id":{"type":"string"},"acceptance_url":{"type":"string"}},"required":["id","acceptance_url"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"total":{"type":"string"},"adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"price_list_name":{"type":"string","nullable":true},"catalog_id":{"type":"string","nullable":true},"catalog_name":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","total","adjustment_total","additional_tax_total","included_tax_total","discount_total","pre_tax_amount","discounted_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","price_list_id","price_list_name","catalog_id","catalog_name","cost_price","tax_category_id"],"x-typelizer":true},"Market":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"country_codes":{"type":"array","items":{"type":"string"}},"country_isos":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_provider":{"type":"string","nullable":true,"description":"Tax provider; null uses the store default. Built-in: internal. Provider gems register more."}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","country_isos","supported_locales","created_at","updated_at","tax_provider"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string","enum":["image","video","external_video"]},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string","enum":["dropdown","color_swatch","buttons"]},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderCancellationReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","confirmation_delivered","store_owner_notification_delivered","created_at","updated_at","payments"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: preferred_location, default_location, minimize_splits. Extensions may register more."},"channel_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/OrderRoutingRulePreferences"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"total":{"type":"string"},"gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"delivery_total":{"type":"string"},"fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"external_references":{"type":"object"},"status":{"type":"string","enum":["draft","placed","canceled"]},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"metadata":{"type":"object"},"cancel_note":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment_total":{"type":"string"},"commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"approver_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"approver":{"$ref":"#/components/schemas/Actor"},"canceler_id":{"type":"string","nullable":true},"canceler_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"canceler":{"$ref":"#/components/schemas/Actor"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","adjustment_total","discount_total","tax_total","included_tax_total","additional_tax_total","total","gift_card_total","amount_due","delivery_total","fee_total","store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","metadata","cancel_note","canceled_at","approved_at","created_at","updated_at","payment_total","commission_amount_total","commission_tax_total","commission_total","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","approver_type","canceler_id","canceler_type","created_by_id","created_by_type","cancel_reason_id","cancel_reason_name","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"volume":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume","seller_id","seller_name"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","description":"Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe."},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"$ref":"#/components/schemas/PaymentMethodPreferences"},"logo_url":{"type":"string","nullable":true},"docs_url":{"type":"string","nullable":true},"third_party":{"type":"boolean"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","logo_url","docs_url","third_party"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["checkout","processing","pending","completed","failed","void","invalid"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"amount":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}}},"required":["id","payment_method_id","response_code","number","status","amount","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"PaymentSplit":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"authorized_amount":{"type":"string"},"captured_amount":{"type":"string"},"refunded_amount":{"type":"string"},"claimed_amount":{"type":"string"},"net_captured_amount":{"type":"string"},"refundable_amount":{"type":"string"},"payment_id":{"type":"string"},"payment_number":{"type":"string","nullable":true},"order_id":{"type":"string"},"order_number":{"type":"string","nullable":true}},"required":["id","currency","created_at","updated_at","authorized_amount","captured_amount","refunded_amount","claimed_amount","net_captured_amount","refundable_amount","payment_id","payment_number","order_id","order_number"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","currency","amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["draft","active","inactive","scheduled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"position":{"type":"number"},"match_policy":{"type":"string","enum":["all","any"]},"adjust_compare_at":{"type":"boolean"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: channel_rule, customer_group_rule, market_rule, user_rule, volume_rule, zone_rule. Extensions may register more."},"price_list_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/PriceRulePreferences"},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"min_quantity":{"type":"number"},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","currency","amount","compare_at_amount","price_list_id","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"anyOf":[{"type":"string","enum":["draft","active","archived","proposed","rejected"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","withdrawn"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Action type. Built-in: create_adjustment, create_item_adjustments, create_line_items, free_shipping. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: currency, country, channel, market, item_total, product, customer, customer_group, first_order, customer_logged_in, one_use_per_user, category, option_value. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"$ref":"#/components/schemas/PromotionRulePreferences"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"option_value_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","product_ids","category_ids","customer_ids","option_value_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"PurchaseOrderItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_ordered":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"currency":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"unit_cost":{"type":"string"},"total_cost":{"type":"string"},"purchase_order_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_ordered","quantity_received","quantity_rejected","quantity_over","outstanding","currency","created_at","updated_at","unit_cost","total_cost","purchase_order_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"PurchaseOrder":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"ordered_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expected_at":{"type":"string","nullable":true},"cancel_by":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_ordered_total":{"type":"number"},"editable":{"type":"boolean"},"subtotal":{"type":"string"},"supplier_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"supplier":{"$ref":"#/components/schemas/Supplier"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","currency","reference","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","ordered_at","received_at","closed_short_at","created_at","updated_at","expected_at","cancel_by","closed_short","quantity_ordered_total","editable","subtotal","supplier_id","destination_location_id"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_amount":{"type":"string"},"refunder_id":{"type":"string","nullable":true},"refunder_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"refunder":{"$ref":"#/components/schemas/Actor"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at","tax_amount","refunder_id","refunder_type"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"tax_total":{"type":"string"},"refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","included_tax_total","additional_tax_total","tax_total","refund_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["requested","approved","received","refunded","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"refund_tax_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"documents":{"type":"array","items":{"type":"object"}},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"required":["id","number","status","order_id","reason_id","refund_total","refund_tax_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","created_by_type","refunded_total","refundable_total","documents","labels","deliveries"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"SavedReport":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"query":{"type":"object"},"seeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"author_name":{"type":"string","nullable":true}},"required":["id","name","description","query","seeded","created_at","updated_at","user_id","author_name"],"x-typelizer":true},"SellerBalance":{"type":"object","properties":{"currency":{"type":"string"},"settlement_currency":{"type":"string"},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"earned":{"type":"string"},"pending":{"type":"string"},"payable":{"type":"string"},"paid":{"type":"string"},"balance":{"type":"string"}},"required":["currency","settlement_currency","converted","seller_id","earned","pending","payable","paid","balance"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","status","currency","reference","metadata","period_start","period_end","created_at","updated_at","amount","seller_id","seller_name","transfers_count","provider"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"$ref":"#/components/schemas/SellerRequirementPreferences"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string","enum":["complete","incomplete","pending","rejected"]},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted","rejected","waived"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["pending","invited","canceled","onboarding","ready_for_review","approved","rejected","suspended"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["earning","refund_reversal"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"settled_amount":{"type":"string","nullable":true},"settled_currency":{"type":"string","nullable":true},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"provider":{"type":"string","description":"Payout provider. Built-in: system. Provider gems register more (e.g. stripe)."}},"required":["id","kind","status","currency","reference","metadata","created_at","updated_at","amount","settled_amount","settled_currency","converted","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number","provider"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["purchased","uploaded"]},"status":{"anyOf":[{"type":"string","enum":["purchased","refund_requested","refunded"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string","enum":["fulfillment","return"]},"cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"type":"object","properties":{"id":{"type":"string"},"count_on_hand":{"type":"number"},"backorderable":{"type":"boolean"},"stock_location_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"reserved_count":{"type":"number"},"incoming_count":{"type":"number"},"purchasable_count":{"type":"number"},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_name":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"allocated_count":{"type":"number"},"available_count":{"type":"number"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","count_on_hand","backorderable","stock_location_id","variant_id","external_references","metadata","reserved_count","incoming_count","purchasable_count","variant_name","variant_sku","created_at","updated_at","stock_location_name","product_id","options_text","thumbnail_url","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"external_references":{"type":"object"},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"anyOf":[{"type":"string","enum":["warehouse","store","fulfillment_center"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true,"enum":["received","allocated","shipped","released","adjusted"]},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"stock_location_name":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true},"stock_receipt_id":{"type":"string","nullable":true},"purchase_order_id":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"return_number":{"type":"string","nullable":true},"exchange_number":{"type":"string","nullable":true},"stock_transfer_number":{"type":"string","nullable":true},"purchase_order_number":{"type":"string","nullable":true},"unit_cost":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","stock_location_id","stock_location_name","variant_id","variant_name","variant_sku","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id","stock_receipt_id","purchase_order_id","order_number","return_number","exchange_number","stock_transfer_number","purchase_order_number","unit_cost"],"x-typelizer":true},"StockReceiptItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"number"},"quantity_rejected":{"type":"number"},"rejection_reason":{"type":"string","nullable":true,"enum":["damaged","wrong_item","expired","other"]},"notes":{"type":"string","nullable":true},"line_type":{"type":"string","enum":["purchase_order_item","stock_transfer_item"]},"line_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_accepted","quantity_rejected","rejection_reason","notes","line_type","line_id","variant_id","product_id","variant_name","variant_sku","thumbnail_url"],"x-typelizer":true},"StockReceipt":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"quantity_accepted_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"received_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"receivable_type":{"type":"string","enum":["purchase_order","stock_transfer"]},"receivable_id":{"type":"string"},"received_by_id":{"type":"string","nullable":true},"received_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"received_by":{"$ref":"#/components/schemas/Actor"},"items_count":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockReceiptItem"}}},"required":["id","number","reference","notes","metadata","quantity_accepted_total","quantity_rejected_total","received_at","created_at","updated_at","receivable_type","receivable_id","received_by_id","received_by_type","items_count"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransferItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_shipped":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_transfer_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_shipped","quantity_received","quantity_rejected","quantity_over","outstanding","created_at","updated_at","stock_transfer_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"shipped_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_shipped_total":{"type":"number"},"editable":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","created_at","updated_at","source_location_id","destination_location_id","status","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","shipped_at","received_at","closed_short_at","deleted_at","closed_short","quantity_shipped_total","editable"],"x-typelizer":true},"StoreCreditEvent":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"authorization_code":{"type":"string","nullable":true},"display_action":{"type":"string","nullable":true},"amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"store_credit_id":{"type":"string"},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true}},"required":["id","action","authorization_code","display_action","amount","created_at","updated_at","store_credit_id","originator_type","originator_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount_authorized":{"type":"string"},"outstanding":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"}},"required":["id","amount","amount_used","amount_remaining","currency","memo","metadata","created_at","updated_at","amount_authorized","outstanding","customer_id","created_by_id","originator_type","originator_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"default_country_code":{"type":"string","nullable":true},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_routing_strategy":{"type":"string","description":"Order routing strategy. Built-in: rules. Extensions may register more."},"payout_provider":{"type":"string","nullable":true,"description":"Payout provider; null uses the installation default. Built-in: system. Provider gems register more (e.g. stripe)."},"admin_locale":{"type":"string","nullable":true},"timezone":{"type":"string"},"storefront_url":{"type":"string","nullable":true},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"unit_system":{"type":"string"},"storefront_access":{"type":"string","enum":["public","prices_hidden","login_required"]},"guest_checkout":{"type":"boolean"},"always_include_confirm_step":{"type":"boolean"},"company_field_enabled":{"type":"boolean"},"address_requires_company":{"type":"boolean"},"address_requires_phone":{"type":"boolean"},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"track_inventory_levels":{"type":"boolean"},"stock_reservations_enabled":{"type":"boolean"},"low_stock_threshold":{"type":"number"},"tax_using_ship_address":{"type":"boolean"},"track_price_history":{"type":"boolean"},"show_products_without_price":{"type":"boolean"},"disable_sku_validation":{"type":"boolean"},"pricing_provider":{"type":"string"},"inventory_provider":{"type":"string"},"pricing_provider_failure_policy":{"type":"string","enum":["fallback","strict"]},"inventory_provider_failure_policy":{"type":"string","enum":["fallback","strict"]},"default_payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"]},"auto_approve_sellers":{"type":"boolean"},"auto_approve_seller_products":{"type":"boolean"},"send_seller_transactional_emails":{"type":"boolean"},"document_number_format":{"type":"string","enum":["sequential","random"]},"order_number_prefix":{"type":"string"},"order_number_suffix":{"type":"string"},"order_number_sequence_start":{"type":"number"},"limit_digital_download_count":{"type":"boolean"},"digital_asset_authorized_clicks":{"type":"number"},"limit_digital_download_days":{"type":"boolean"},"digital_asset_authorized_days":{"type":"number"},"send_consumer_transactional_emails":{"type":"boolean"},"email_accent_color":{"type":"string","nullable":true},"email_background_color":{"type":"string","nullable":true},"email_card_color":{"type":"string","nullable":true},"email_text_color":{"type":"string","nullable":true},"email_heading_color":{"type":"string","nullable":true},"email_font":{"type":"string","nullable":true,"enum":["inter","system","helvetica","georgia","roboto","lato","merriweather"]},"order_number_sequence_started":{"type":"boolean"},"default_minimum_payout_amount":{"type":"string","nullable":true},"default_commission_tax_rate":{"type":"string","nullable":true},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","created_at","updated_at","order_routing_strategy","payout_provider","admin_locale","timezone","storefront_url","weight_unit","unit_system","storefront_access","guest_checkout","always_include_confirm_step","company_field_enabled","address_requires_company","address_requires_phone","capture_method","track_inventory_levels","stock_reservations_enabled","low_stock_threshold","tax_using_ship_address","track_price_history","show_products_without_price","disable_sku_validation","pricing_provider","inventory_provider","pricing_provider_failure_policy","inventory_provider_failure_policy","default_payouts_schedule_interval","auto_approve_sellers","auto_approve_seller_products","send_seller_transactional_emails","document_number_format","order_number_prefix","order_number_suffix","order_number_sequence_start","limit_digital_download_count","digital_asset_authorized_clicks","limit_digital_download_days","digital_asset_authorized_days","send_consumer_transactional_emails","email_accent_color","email_background_color","email_card_color","email_text_color","email_heading_color","email_font","order_number_sequence_started","default_minimum_payout_amount","default_commission_tax_rate","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"Supplier":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"purchase_orders_count":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"can_be_deleted":{"type":"boolean"}},"required":["id","name","contact_name","email","phone","notes","address1","address2","city","state_name","state_code","country_code","postal_code","purchase_orders_count","metadata","created_at","updated_at","deleted_at","can_be_deleted"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","verified","expired","revoked"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more."},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true,"enum":["pending","verified","unverified","unavailable","unsupported"]},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true,"enum":["override","company","customer"]},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"credit":{"type":"boolean"},"rate":{"type":"string","nullable":true},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"return_line_item_id":{"type":"string","nullable":true},"claim_line_item_id":{"type":"string","nullable":true},"exchange_line_item_id":{"type":"string","nullable":true},"amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"original_tax_line_id":{"type":"string","nullable":true}},"required":["id","label","included","credit","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","return_line_item_id","claim_line_item_id","exchange_line_item_id","amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at","original_tax_line_id"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"rate":{"type":"string","nullable":true},"rate_percent":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","rate","rate_percent","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true,"enum":["unit","carton"]},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","weight_unit","dimensions_unit","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","cost_price","preorderable","tax_category_id","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true},"WebhookEvent":{"type":"object","properties":{"name":{"type":"string"},"group":{"type":"string"},"credential_permission":{"type":"string","nullable":true},"credential":{"type":"boolean"},"deprecated":{"type":"boolean"},"replaced_by":{"type":"string","nullable":true}},"required":["name","group","credential_permission","credential","deprecated","replaced_by"],"x-typelizer":true},"CommissionRuleCategoryRulePreferences":{"type":"object","properties":{"category_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ctg_[A-Za-z0-9]+$","x-spree-prefix":"ctg"},"default":[]}},"additionalProperties":false},"CommissionRuleItemTotalRulePreferences":{"type":"object","properties":{"min_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"max_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"CommissionRuleProductRulePreferences":{"type":"object","properties":{},"additionalProperties":false},"CommissionRuleSellerRulePreferences":{"type":"object","properties":{"seller_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^sel_[A-Za-z0-9]+$","x-spree-prefix":"sel"},"default":[]}},"additionalProperties":false},"CommissionRulePreferences":{"description":"Settings of a commission rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/CommissionRuleCategoryRulePreferences"},{"$ref":"#/components/schemas/CommissionRuleItemTotalRulePreferences"},{"$ref":"#/components/schemas/CommissionRuleProductRulePreferences"},{"$ref":"#/components/schemas/CommissionRuleSellerRulePreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"category_rule":"#/components/schemas/CommissionRuleCategoryRulePreferences","item_total_rule":"#/components/schemas/CommissionRuleItemTotalRulePreferences","product_rule":"#/components/schemas/CommissionRuleProductRulePreferences","seller_rule":"#/components/schemas/CommissionRuleSellerRulePreferences"}},"DeliveryCalculatorDigitalDeliveryPreferences":{"type":"object","properties":{"amounts":{"type":"object","additionalProperties":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"default":{},"x-spree-property-names":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorFlatPercentItemTotalPreferences":{"type":"object","properties":{"flat_percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"}},"additionalProperties":false},"DeliveryCalculatorFlatRatePreferences":{"type":"object","properties":{"amounts":{"type":"object","additionalProperties":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"default":{},"x-spree-property-names":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorFlexiRatePreferences":{"type":"object","properties":{"first_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"additional_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"max_items":{"type":"integer","default":0},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorPerItemPreferences":{"type":"object","properties":{"amounts":{"type":"object","additionalProperties":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"default":{},"x-spree-property-names":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorPriceSackPreferences":{"type":"object","properties":{"minimal_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"normal_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"discount_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"DeliveryCalculatorPreferences":{"description":"Settings of a delivery calculator, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/DeliveryCalculatorDigitalDeliveryPreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorFlatPercentItemTotalPreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorFlatRatePreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorFlexiRatePreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorPerItemPreferences"},{"$ref":"#/components/schemas/DeliveryCalculatorPriceSackPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"digital_delivery":"#/components/schemas/DeliveryCalculatorDigitalDeliveryPreferences","flat_percent_item_total":"#/components/schemas/DeliveryCalculatorFlatPercentItemTotalPreferences","flat_rate":"#/components/schemas/DeliveryCalculatorFlatRatePreferences","flexi_rate":"#/components/schemas/DeliveryCalculatorFlexiRatePreferences","per_item":"#/components/schemas/DeliveryCalculatorPerItemPreferences","price_sack":"#/components/schemas/DeliveryCalculatorPriceSackPreferences"}},"DeliveryMethodRuleChannelRulePreferences":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ch_[A-Za-z0-9]+$","x-spree-prefix":"ch"},"default":[]}},"additionalProperties":false},"DeliveryMethodRuleCompanyRulePreferences":{"type":"object","properties":{"company_orders_only":{"type":"boolean","default":true}},"additionalProperties":false},"DeliveryMethodRuleExcludedProductsRulePreferences":{"type":"object","properties":{},"additionalProperties":false},"DeliveryMethodRuleItemTotalRulePreferences":{"type":"object","properties":{"minimum_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"maximum_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"DeliveryMethodRuleVolumeRulePreferences":{"type":"object","properties":{"minimum_volume":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"maximum_volume":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"DeliveryMethodRuleWeightRulePreferences":{"type":"object","properties":{"minimum_weight":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"maximum_weight":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true}},"additionalProperties":false},"DeliveryMethodRulePreferences":{"description":"Settings of a delivery method rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/DeliveryMethodRuleChannelRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleCompanyRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleExcludedProductsRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleItemTotalRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleVolumeRulePreferences"},{"$ref":"#/components/schemas/DeliveryMethodRuleWeightRulePreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"channel_rule":"#/components/schemas/DeliveryMethodRuleChannelRulePreferences","company_rule":"#/components/schemas/DeliveryMethodRuleCompanyRulePreferences","excluded_products_rule":"#/components/schemas/DeliveryMethodRuleExcludedProductsRulePreferences","item_total_rule":"#/components/schemas/DeliveryMethodRuleItemTotalRulePreferences","volume_rule":"#/components/schemas/DeliveryMethodRuleVolumeRulePreferences","weight_rule":"#/components/schemas/DeliveryMethodRuleWeightRulePreferences"}},"IntegrationPreferences":{"description":"Settings of a integration, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{}},"OrderRoutingRuleDefaultLocationPreferences":{"type":"object","properties":{},"additionalProperties":false},"OrderRoutingRuleMinimizeSplitsPreferences":{"type":"object","properties":{},"additionalProperties":false},"OrderRoutingRulePreferredLocationPreferences":{"type":"object","properties":{},"additionalProperties":false},"OrderRoutingRulePreferences":{"description":"Settings of a order routing rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/OrderRoutingRuleDefaultLocationPreferences"},{"$ref":"#/components/schemas/OrderRoutingRuleMinimizeSplitsPreferences"},{"$ref":"#/components/schemas/OrderRoutingRulePreferredLocationPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"default_location":"#/components/schemas/OrderRoutingRuleDefaultLocationPreferences","minimize_splits":"#/components/schemas/OrderRoutingRuleMinimizeSplitsPreferences","preferred_location":"#/components/schemas/OrderRoutingRulePreferredLocationPreferences"}},"PaymentMethodBogusPreferences":{"type":"object","properties":{"dummy_key":{"type":"string","default":"PUBLICKEY123"},"dummy_secret_key":{"type":"string","x-spree-secret":true,"nullable":true}},"additionalProperties":false},"PaymentMethodCheckPreferences":{"type":"object","properties":{},"additionalProperties":false},"PaymentMethodCustomPaymentSourceMethodPreferences":{"type":"object","properties":{},"additionalProperties":false},"PaymentMethodStoreCreditPreferences":{"type":"object","properties":{},"additionalProperties":false},"PaymentMethodPreferences":{"description":"Settings of a payment method, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PaymentMethodBogusPreferences"},{"$ref":"#/components/schemas/PaymentMethodCheckPreferences"},{"$ref":"#/components/schemas/PaymentMethodCustomPaymentSourceMethodPreferences"},{"$ref":"#/components/schemas/PaymentMethodStoreCreditPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"bogus":"#/components/schemas/PaymentMethodBogusPreferences","check":"#/components/schemas/PaymentMethodCheckPreferences","custom_payment_source_method":"#/components/schemas/PaymentMethodCustomPaymentSourceMethodPreferences","store_credit":"#/components/schemas/PaymentMethodStoreCreditPreferences"}},"PriceRuleChannelRulePreferences":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ch_[A-Za-z0-9]+$","x-spree-prefix":"ch"},"default":[]}},"additionalProperties":false},"PriceRuleCustomerGroupRulePreferences":{"type":"object","properties":{"customer_group_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^cg_[A-Za-z0-9]+$","x-spree-prefix":"cg"},"default":[]}},"additionalProperties":false},"PriceRuleMarketRulePreferences":{"type":"object","properties":{"market_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^mkt_[A-Za-z0-9]+$","x-spree-prefix":"mkt"},"default":[]}},"additionalProperties":false},"PriceRuleUserRulePreferences":{"type":"object","properties":{"user_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^cust_[A-Za-z0-9]+$","x-spree-prefix":"cust"},"default":[]}},"additionalProperties":false},"PriceRuleVolumeRulePreferences":{"type":"object","properties":{"min_quantity":{"type":"integer","default":1},"max_quantity":{"type":"integer","nullable":true}},"additionalProperties":false},"PriceRulePreferences":{"description":"Settings of a price rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PriceRuleChannelRulePreferences"},{"$ref":"#/components/schemas/PriceRuleCustomerGroupRulePreferences"},{"$ref":"#/components/schemas/PriceRuleMarketRulePreferences"},{"$ref":"#/components/schemas/PriceRuleUserRulePreferences"},{"$ref":"#/components/schemas/PriceRuleVolumeRulePreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"channel_rule":"#/components/schemas/PriceRuleChannelRulePreferences","customer_group_rule":"#/components/schemas/PriceRuleCustomerGroupRulePreferences","market_rule":"#/components/schemas/PriceRuleMarketRulePreferences","user_rule":"#/components/schemas/PriceRuleUserRulePreferences","volume_rule":"#/components/schemas/PriceRuleVolumeRulePreferences"}},"PromotionCalculatorFlatPercentItemTotalPreferences":{"type":"object","properties":{"flat_percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"}},"additionalProperties":false},"PromotionCalculatorFlatRatePreferences":{"type":"object","properties":{"amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"},"apply_only_on_full_priced_items":{"type":"boolean","default":false}},"additionalProperties":false},"PromotionCalculatorFlexiRatePreferences":{"type":"object","properties":{"first_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"additional_item":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"max_items":{"type":"integer","default":0},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"},"apply_only_on_full_priced_items":{"type":"boolean","default":false}},"additionalProperties":false},"PromotionCalculatorPercentOnLineItemPreferences":{"type":"object","properties":{"percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"apply_only_on_full_priced_items":{"type":"boolean","default":false}},"additionalProperties":false},"PromotionCalculatorTieredFlatRatePreferences":{"type":"object","properties":{"tiers":{"type":"array","items":{"type":"object","properties":{"threshold":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"value":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["threshold","value"],"additionalProperties":false},"default":[]},"base_amount":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"},"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$"}},"additionalProperties":false},"PromotionCalculatorTieredPercentPreferences":{"type":"object","properties":{"tiers":{"type":"array","items":{"type":"object","properties":{"threshold":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$"},"value":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$"}},"required":["threshold","value"],"additionalProperties":false},"default":[]},"base_percent":{"type":"string","pattern":"^-?\\d+(\\.\\d+)?$","default":"0"}},"additionalProperties":false},"PromotionCalculatorPreferences":{"description":"Settings of a promotion calculator, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PromotionCalculatorFlatPercentItemTotalPreferences"},{"$ref":"#/components/schemas/PromotionCalculatorFlatRatePreferences"},{"$ref":"#/components/schemas/PromotionCalculatorFlexiRatePreferences"},{"$ref":"#/components/schemas/PromotionCalculatorPercentOnLineItemPreferences"},{"$ref":"#/components/schemas/PromotionCalculatorTieredFlatRatePreferences"},{"$ref":"#/components/schemas/PromotionCalculatorTieredPercentPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"flat_percent_item_total":"#/components/schemas/PromotionCalculatorFlatPercentItemTotalPreferences","flat_rate":"#/components/schemas/PromotionCalculatorFlatRatePreferences","flexi_rate":"#/components/schemas/PromotionCalculatorFlexiRatePreferences","percent_on_line_item":"#/components/schemas/PromotionCalculatorPercentOnLineItemPreferences","tiered_flat_rate":"#/components/schemas/PromotionCalculatorTieredFlatRatePreferences","tiered_percent":"#/components/schemas/PromotionCalculatorTieredPercentPreferences"}},"PromotionRuleCategoryPreferences":{"type":"object","properties":{"match_policy":{"type":"string","enum":["any","all"],"default":"any"}},"additionalProperties":false},"PromotionRuleChannelPreferences":{"type":"object","properties":{"channel_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^ch_[A-Za-z0-9]+$","x-spree-prefix":"ch"},"default":[]}},"additionalProperties":false},"PromotionRuleCountryPreferences":{"type":"object","properties":{"country_codes":{"type":"array","items":{"type":"string","format":"iso-country","pattern":"^[A-Z]{2}$"},"default":[]},"country_id":{"type":"integer","nullable":true},"country_code":{"type":"string","format":"iso-country","pattern":"^[A-Z]{2}$","nullable":true}},"additionalProperties":false},"PromotionRuleCurrencyPreferences":{"type":"object","properties":{"currency":{"type":"string","format":"currency","pattern":"^[A-Z]{3}$","nullable":true}},"additionalProperties":false},"PromotionRuleCustomerPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleCustomerGroupPreferences":{"type":"object","properties":{"customer_group_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^cg_[A-Za-z0-9]+$","x-spree-prefix":"cg"},"default":[]}},"additionalProperties":false},"PromotionRuleCustomerLoggedInPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleFirstOrderPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleItemTotalPreferences":{"type":"object","properties":{"amount_min":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","default":"100"},"operator_min":{"type":"string","default":">"},"amount_max":{"type":"string","format":"money","pattern":"^-?\\d+(\\.\\d+)?$","nullable":true},"operator_max":{"type":"string","default":"<"}},"additionalProperties":false},"PromotionRuleMarketPreferences":{"type":"object","properties":{"market_ids":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^mkt_[A-Za-z0-9]+$","x-spree-prefix":"mkt"},"default":[]}},"additionalProperties":false},"PromotionRuleOneUsePerUserPreferences":{"type":"object","properties":{},"additionalProperties":false},"PromotionRuleOptionValuePreferences":{"type":"object","properties":{"match_policy":{"type":"string","enum":["any"],"default":"any"},"eligible_values":{"type":"array","items":{"type":"string","format":"prefixed-id","pattern":"^optval_[A-Za-z0-9]+$","x-spree-prefix":"optval"},"default":[]}},"additionalProperties":false},"PromotionRuleProductPreferences":{"type":"object","properties":{"match_policy":{"type":"string","enum":["any","all","none"],"default":"any"}},"additionalProperties":false},"PromotionRulePreferences":{"description":"Settings of a promotion rule, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/PromotionRuleCategoryPreferences"},{"$ref":"#/components/schemas/PromotionRuleChannelPreferences"},{"$ref":"#/components/schemas/PromotionRuleCountryPreferences"},{"$ref":"#/components/schemas/PromotionRuleCurrencyPreferences"},{"$ref":"#/components/schemas/PromotionRuleCustomerPreferences"},{"$ref":"#/components/schemas/PromotionRuleCustomerGroupPreferences"},{"$ref":"#/components/schemas/PromotionRuleCustomerLoggedInPreferences"},{"$ref":"#/components/schemas/PromotionRuleFirstOrderPreferences"},{"$ref":"#/components/schemas/PromotionRuleItemTotalPreferences"},{"$ref":"#/components/schemas/PromotionRuleMarketPreferences"},{"$ref":"#/components/schemas/PromotionRuleOneUsePerUserPreferences"},{"$ref":"#/components/schemas/PromotionRuleOptionValuePreferences"},{"$ref":"#/components/schemas/PromotionRuleProductPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"category":"#/components/schemas/PromotionRuleCategoryPreferences","channel":"#/components/schemas/PromotionRuleChannelPreferences","country":"#/components/schemas/PromotionRuleCountryPreferences","currency":"#/components/schemas/PromotionRuleCurrencyPreferences","customer":"#/components/schemas/PromotionRuleCustomerPreferences","customer_group":"#/components/schemas/PromotionRuleCustomerGroupPreferences","customer_logged_in":"#/components/schemas/PromotionRuleCustomerLoggedInPreferences","first_order":"#/components/schemas/PromotionRuleFirstOrderPreferences","item_total":"#/components/schemas/PromotionRuleItemTotalPreferences","market":"#/components/schemas/PromotionRuleMarketPreferences","one_use_per_user":"#/components/schemas/PromotionRuleOneUsePerUserPreferences","option_value":"#/components/schemas/PromotionRuleOptionValuePreferences","product":"#/components/schemas/PromotionRuleProductPreferences"}},"SellerRequirementAcceptTermsPreferences":{"type":"object","properties":{"terms_body":{"type":"string","x-spree-widget":"textarea","nullable":true},"terms_effective_from":{"type":"string","format":"date","nullable":true},"terms_url":{"type":"string","nullable":true}},"additionalProperties":false},"SellerRequirementAttestationPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementBillingAddressPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementCompleteProfilePreferences":{"type":"object","properties":{"require_about":{"type":"boolean","default":true},"require_logo":{"type":"boolean","default":true},"require_cover_photo":{"type":"boolean","default":false},"require_contact_email":{"type":"boolean","default":true}},"additionalProperties":false},"SellerRequirementDeliveryMethodPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementDocumentPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementMinimumProductsPreferences":{"type":"object","properties":{"minimum_count":{"type":"integer","default":1}},"additionalProperties":false},"SellerRequirementOperatorReviewPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPackageTypePreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPayoutAccountPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPolicyPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementRequiredCustomFieldsPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementReturnsAddressPreferences":{"type":"object","properties":{},"additionalProperties":false},"SellerRequirementPreferences":{"description":"Settings of a seller requirement, shaped by its `type` (see `x-spree-preferences-by-type`). A type an extension registers is a plain object, described by the `schema` its `/types` entry carries.","anyOf":[{"$ref":"#/components/schemas/SellerRequirementAcceptTermsPreferences"},{"$ref":"#/components/schemas/SellerRequirementAttestationPreferences"},{"$ref":"#/components/schemas/SellerRequirementBillingAddressPreferences"},{"$ref":"#/components/schemas/SellerRequirementCompleteProfilePreferences"},{"$ref":"#/components/schemas/SellerRequirementDeliveryMethodPreferences"},{"$ref":"#/components/schemas/SellerRequirementDocumentPreferences"},{"$ref":"#/components/schemas/SellerRequirementMinimumProductsPreferences"},{"$ref":"#/components/schemas/SellerRequirementOperatorReviewPreferences"},{"$ref":"#/components/schemas/SellerRequirementPackageTypePreferences"},{"$ref":"#/components/schemas/SellerRequirementPayoutAccountPreferences"},{"$ref":"#/components/schemas/SellerRequirementPolicyPreferences"},{"$ref":"#/components/schemas/SellerRequirementRequiredCustomFieldsPreferences"},{"$ref":"#/components/schemas/SellerRequirementReturnsAddressPreferences"},{"type":"object","additionalProperties":true}],"x-spree-preferences-by-type":{"accept_terms":"#/components/schemas/SellerRequirementAcceptTermsPreferences","attestation":"#/components/schemas/SellerRequirementAttestationPreferences","billing_address":"#/components/schemas/SellerRequirementBillingAddressPreferences","complete_profile":"#/components/schemas/SellerRequirementCompleteProfilePreferences","delivery_method":"#/components/schemas/SellerRequirementDeliveryMethodPreferences","document":"#/components/schemas/SellerRequirementDocumentPreferences","minimum_products":"#/components/schemas/SellerRequirementMinimumProductsPreferences","operator_review":"#/components/schemas/SellerRequirementOperatorReviewPreferences","package_type":"#/components/schemas/SellerRequirementPackageTypePreferences","payout_account":"#/components/schemas/SellerRequirementPayoutAccountPreferences","policy":"#/components/schemas/SellerRequirementPolicyPreferences","required_custom_fields":"#/components/schemas/SellerRequirementRequiredCustomFieldsPreferences","returns_address":"#/components/schemas/SellerRequirementReturnsAddressPreferences"}},"DeliveryMethodCalculator":{"type":"object","description":"How the delivery method prices a shipment","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"preferences":{"$ref":"#/components/schemas/DeliveryCalculatorPreferences"}},"required":["type","preferences"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"preferences":{"$ref":"#/components/schemas/PromotionCalculatorPreferences"}},"required":["type","preferences"]}}}}\ No newline at end of filediff --git a/packages/cli/src/generated/resource-paths.json b/packages/cli/src/generated/resource-paths.jsonindex 8440739e72..8161717ad0 100644--- a/packages/cli/src/generated/resource-paths.json+++ b/packages/cli/src/generated/resource-paths.json@@ -1 +1 @@-["/admin_users","/allowed_origins","/api_keys","/auth","/catalogs","/categories","/channels","/claim_reasons","/claims","/collection_rules","/collections","/commission_lines","/commission_rates","/companies","/consent_records","/custom_field_definitions","/customer_groups","/customers","/data_requests","/delivery_methods","/delivery_profiles","/delivery_zones","/digital_links","/email_templates","/exchanges","/exports","/gift_card_batches","/gift_cards","/imports","/integrations","/invitations","/locales","/markets","/me","/media","/option_types","/order_cancellation_reasons","/order_groups","/order_routing_rules","/orders","/package_types","/payment_methods","/permissions","/policies","/price_lists","/prices","/product_types","/products","/promotion_actions","/promotion_rules","/promotions","/purchase_orders","/refund_reasons","/reporting","/return_reasons","/returns","/roles","/seller_payouts","/seller_requirements","/seller_transfers","/sellers","/stock_levels","/stock_locations","/stock_movements","/stock_reservations","/stock_transfers","/store","/store_credits","/suppliers","/tags","/tax_categories","/tax_rates","/translatable_resources","/translations","/variants","/webhook_endpoints","/webhook_events"]\ No newline at end of file+["/admin_users","/allowed_origins","/api_keys","/auth","/catalogs","/categories","/channels","/claim_reasons","/claims","/collection_rules","/collections","/commission_lines","/commission_rates","/companies","/consent_records","/custom_field_definitions","/customer_groups","/customers","/data_requests","/delivery_methods","/delivery_profiles","/delivery_zones","/digital_links","/email_templates","/exchanges","/exports","/files","/gift_card_batches","/gift_cards","/imports","/integrations","/invitations","/locales","/markets","/me","/media","/option_types","/order_cancellation_reasons","/order_groups","/order_routing_rules","/orders","/package_types","/payment_methods","/permissions","/policies","/price_lists","/prices","/product_types","/products","/promotion_actions","/promotion_rules","/promotions","/purchase_orders","/refund_reasons","/reporting","/return_reasons","/returns","/roles","/seller_payouts","/seller_requirements","/seller_transfers","/sellers","/stock_levels","/stock_locations","/stock_movements","/stock_reservations","/stock_transfers","/store","/store_credits","/suppliers","/tags","/tax_categories","/tax_rates","/translatable_resources","/translations","/variants","/webhook_endpoints","/webhook_events"]\ No newline at end of filediff --git a/packages/dashboard-core/package.json b/packages/dashboard-core/package.jsonindex bd78130d07..b31d47e85d 100644--- a/packages/dashboard-core/package.json+++ b/packages/dashboard-core/package.json@@ -76,11 +76,9 @@"@dnd-kit/sortable": "^10.0.0","@dnd-kit/utilities": "^3.2.2","@tailwindcss/vite": "^4.2.4",- "@types/spark-md5": "^3.0.5","date-fns": "^4.1.0","date-fns-tz": "^3.2.0","lucide-react": "^1.47.0",- "spark-md5": "^3.0.2","zod": "^4.4.3"},"devDependencies": {diff --git a/packages/dashboard-core/src/api-client.ts b/packages/dashboard-core/src/api-client.tsindex 6d61ad5e38..537673e186 100644--- a/packages/dashboard-core/src/api-client.ts+++ b/packages/dashboard-core/src/api-client.ts@@ -14,7 +14,7 @@* promise the seller panel methods its API does not have.*/-import type { PermissionRule } from '@spree/admin-sdk'+import type { PermissionRule, UploadFileOptions } from '@spree/admin-sdk'/** What a panel may change on the signed-in person's own account. */export interface PanelAccountParams {@@ -23,11 +23,11 @@ export interface PanelAccountParams {/** The panel's UI language, as a bundle code the panel ships (e.g. `de`). */selected_locale?: string/**- * ActiveStorage signed id to set the photo, or `null` to remove it. Omit to+ * A `signed_id` from an upload to set the photo, or `null` to remove it. Omit to* leave the current one alone — the only field here where `null` means* something the API acts on.*/- avatar?: string | null+ avatar_signed_id?: string | null}/**@@ -105,19 +105,15 @@ export interface PanelApiClient {* fulfillments, so they retire one by deactivating it.*//**- * Exchanges blob metadata for a presigned upload URL.+ * Uploads a file through the panel's own `POST /files` and resolves to its+ * `signed_id`.** Registered rather than imported for the same reason as everything else* here: the shared upload field would otherwise work only in the* operator's panel, and a seller uploading an onboarding document would* get a 401 from an API they hold no key for.*/- createDirectUpload?(params: {- blob: { filename: string; byte_size: number; checksum: string; content_type: string }- }): Promise<{- direct_upload: { url: string; headers: Record<string, string> }- signed_id: string- }>+ uploadFile?(file: File, options: UploadFileOptions): Promise<{ signed_id: string }>/*** Writes the signed-in person's own account — their name, photo and the* panel's language.@@ -455,8 +451,8 @@ export interface PanelImportRow {export interface PanelImportCreateParams {type: string- /** Signed blob id of the already direct-uploaded CSV. */- attachment: string+ /** The `signed_id` of the already uploaded CSV. */+ attachment_signed_id: string/** CSV column separator — the four both APIs accept. */delimiter?: PanelImportDelimiter/** The price list a `price_list_prices` import merges into. */diff --git a/packages/dashboard-core/src/components/file-upload-field.tsx b/packages/dashboard-core/src/components/file-upload-field.tsxindex 6c7e3cae63..1f250beb08 100644--- a/packages/dashboard-core/src/components/file-upload-field.tsx+++ b/packages/dashboard-core/src/components/file-upload-field.tsx@@ -15,7 +15,7 @@ import {import { FileIcon, UploadCloudIcon, XIcon } from '@spree/dashboard-ui/icons'import { type ReactNode, useState } from 'react'import { useTranslation } from 'react-i18next'-import { useDirectUpload } from '../hooks/use-direct-upload'+import { useFileUpload } from '../hooks/use-file-upload'/*** Controlled upload state. A field is in exactly one of three states:@@ -89,7 +89,7 @@ export interface FileUploadFieldProps {}/**- * Universal single-file upload field backed by ActiveStorage direct upload.+ * Universal single-file upload field backed by `POST /files`.* Picking or dropping a file uploads it immediately; the attached file (or* the persisted server-side one) renders as an `Attachment` with a remove* action. Fully controlled — the consumer maps {@link FileUploadValue} onto@@ -115,7 +115,7 @@ export function FileUploadField({onUploadingChange,}: FileUploadFieldProps) {const { t } = useTranslation()- const directUpload = useDirectUpload({ private: privateStorage })+ const fileUpload = useFileUpload({ visibility: privateStorage ? 'private' : 'public' })const [pending, setPending] = useState<File | null>(null)const isImage = variant === 'image'@@ -153,7 +153,7 @@ export function FileUploadField({setPending(file)onUploadingChange?.(true)try {- const result = await directUpload.mutateAsync(file)+ const result = await fileUpload.mutateAsync(file)// Revoke a preview we're replacing in-place; the object URL otherwise// lives in caller-owned state, so its lifetime is their responsibility// (a hidden-then-shown card must not remount with a dead URL).diff --git a/packages/dashboard-core/src/components/import-button.tsx b/packages/dashboard-core/src/components/import-button.tsxindex 2e466b505d..2c02ddfcc1 100644--- a/packages/dashboard-core/src/components/import-button.tsx+++ b/packages/dashboard-core/src/components/import-button.tsx@@ -75,7 +75,7 @@ interface ImportButtonProps {/*** Toolbar entry point for CSV imports: opens a Sheet with the upload form- * (file, delimiter, template download). The CSV direct-uploads on pick via+ * (file, delimiter, template download). The CSV uploads on pick via* `FileUploadField`; submitting creates the import from the signed blob id* and hands it to `onCreated`.*/@@ -190,6 +190,9 @@ export function ImportButton({// Windows browsers report `.csv` as `application/vnd.ms-excel`,// which the server's content-type validation rejects.transformFile={(picked) => new File([picked], picked.name, { type: 'text/csv' })}+ // Imports are kept on private storage: a CSV can carry+ // customer data.+ private/><Field>diff --git a/packages/dashboard-core/src/hooks/use-direct-upload.ts b/packages/dashboard-core/src/hooks/use-direct-upload.tsdeleted file mode 100644index 422b1c7377..0000000000--- a/packages/dashboard-core/src/hooks/use-direct-upload.ts+++ /dev/null@@ -1,117 +0,0 @@-import { useMutation } from '@tanstack/react-query'-import SparkMD5 from 'spark-md5'-import { getApiClient } from '../api-client'--function computeMD5Checksum(file: File): Promise<string> {- return new Promise((resolve, reject) => {- const chunkSize = 2097152 // 2MB chunks- const spark = new SparkMD5.ArrayBuffer()- const reader = new FileReader()- let currentChunk = 0- const chunks = Math.ceil(file.size / chunkSize)-- reader.onload = (e) => {- spark.append(e.target!.result as ArrayBuffer)- currentChunk++-- if (currentChunk < chunks) {- loadNext()- } else {- // Active Storage expects base64-encoded raw MD5 digest- resolve(btoa(spark.end(true)))- }- }-- reader.onerror = () => reject(reader.error)-- function loadNext() {- const start = currentChunk * chunkSize- const end = Math.min(start + chunkSize, file.size)- reader.readAsArrayBuffer(file.slice(start, end))- }-- loadNext()- })-}--interface UploadResult {- signedId: string- previewUrl: string-}--function sameOriginIfRailsDisk(url: string): string {- try {- const parsed = new URL(url)- if (parsed.pathname.startsWith('/rails/active_storage/')) {- return parsed.pathname + parsed.search- }- return url- } catch {- return url- }-}--interface DirectUploadOptions {- /**- * Upload to private storage instead of the public bucket. Required for files- * that are only ever served through an authorized, signed link — attaching a- * blob never moves it between services, so this has to be decided up front.- */- private?: boolean-}--export function useDirectUpload(options: DirectUploadOptions = {}) {- return useMutation({- mutationFn: async (file: File): Promise<UploadResult> => {- const checksum = await computeMD5Checksum(file)-- // Step 1: Get presigned upload URL- let response: {- direct_upload: { url: string; headers: Record<string, string> }- signed_id: string- }- try {- const presign = getApiClient().createDirectUpload- if (!presign) throw new Error('This panel cannot upload files.')-- response = await presign({- blob: {- filename: file.name,- byte_size: file.size,- checksum,- content_type: file.type || 'application/octet-stream',- },- ...(options.private ? { private: true } : {}),- })- } catch (err) {- throw new Error(`Presign failed: ${err instanceof Error ? err.message : err}`)- }-- // Step 2: Upload file directly to storage.- //- // Active Storage's Disk service issues an absolute URL against the Rails- // origin (e.g. http://localhost:3000/rails/active_storage/disk/...). In- // dev the SPA runs on a different port and that controller doesn't speak- // CORS, so the browser blocks the cross-origin PUT before any response- // ("Failed to fetch"). When the URL points at a `/rails/active_storage/`- // path we drop the host so the request goes through Vite's `/rails`- // proxy and stays same-origin. Production S3 URLs are untouched.- const uploadUrl = sameOriginIfRailsDisk(response.direct_upload.url)- const uploadResponse = await fetch(uploadUrl, {- method: 'PUT',- headers: response.direct_upload.headers,- body: file,- })-- if (!uploadResponse.ok) {- const text = await uploadResponse.text().catch(() => '')- throw new Error(`Storage upload failed (${uploadResponse.status}): ${text}`)- }-- return {- signedId: response.signed_id,- previewUrl: URL.createObjectURL(file),- }- },- })-}diff --git a/packages/dashboard-core/src/hooks/use-file-upload.ts b/packages/dashboard-core/src/hooks/use-file-upload.tsnew file mode 100644index 0000000000..1894006f39--- /dev/null+++ b/packages/dashboard-core/src/hooks/use-file-upload.ts@@ -0,0 +1,51 @@+import { useMutation } from '@tanstack/react-query'+import { getApiClient } from '../api-client'++interface UploadResult {+ signedId: string+ previewUrl: string+}++// Active Storage's Disk service issues an absolute URL against the Rails+// origin (e.g. http://localhost:3000/rails/active_storage/disk/...). In dev the+// SPA runs on a different port and that controller doesn't speak CORS, so the+// browser blocks the cross-origin PUT before any response ("Failed to fetch").+// When the URL points at a `/rails/active_storage/` path we drop the host so+// the request goes through Vite's `/rails` proxy and stays same-origin.+// Production storage URLs are untouched.+function sameOriginIfRailsDisk(url: string): string {+ try {+ const parsed = new URL(url)+ if (parsed.pathname.startsWith('/rails/active_storage/')) {+ return parsed.pathname + parsed.search+ }+ return url+ } catch {+ return url+ }+}++interface FileUploadOptions {+ /**+ * `private` for files only ever served through an authorized link+ * (documents, imports, digital products). Attaching a file never moves it+ * between storage services, so this has to be decided up front.+ */+ visibility?: 'public' | 'private'+}++export function useFileUpload(options: FileUploadOptions = {}) {+ return useMutation({+ mutationFn: async (file: File): Promise<UploadResult> => {+ const uploadFile = getApiClient().uploadFile+ if (!uploadFile) throw new Error('This panel cannot upload files.')++ const { signed_id } = await uploadFile(file, {+ visibility: options.visibility ?? 'public',+ resolveUploadUrl: sameOriginIfRailsDisk,+ })++ return { signedId: signed_id, previewUrl: URL.createObjectURL(file) }+ },+ })+}diff --git a/packages/dashboard-core/src/hooks/use-import.ts b/packages/dashboard-core/src/hooks/use-import.tsindex 6f44cd4dee..86e7cd58e5 100644--- a/packages/dashboard-core/src/hooks/use-import.ts+++ b/packages/dashboard-core/src/hooks/use-import.ts@@ -90,12 +90,12 @@ function imports() {/** Create-time parameters beyond the ones every import shares. */export type ImportCreateExtras = Omit<PanelImportCreateParams,- 'type' | 'attachment' | 'delimiter' | 'results_url'+ 'type' | 'attachment_signed_id' | 'delimiter' | 'results_url'>export interface CreateImportInput {type: string- /** Signed blob id of the already direct-uploaded CSV (see `FileUploadField`). */+ /** The `signed_id` of the already uploaded CSV (see `FileUploadField`). */signedId: stringpreferredDelimiter?: PanelImportDelimiter/**@@ -111,7 +111,7 @@ export interface CreateImportInput {}/**- * Creates the import from a direct-uploaded CSV; the response is in the+ * Creates the import from an uploaded CSV; the response is in the* `mapping` state and carries the mapping payload.*/export function useCreateImport() {@@ -128,7 +128,7 @@ export function useCreateImport() {imports().create({...params,type,- attachment: signedId,+ attachment_signed_id: signedId,delimiter: preferredDelimiter,// The import-done email deep-links back to the wizard (`?import=<id>`// appended server-side). Only honored when this origin is on thediff --git a/packages/dashboard-core/src/index.ts b/packages/dashboard-core/src/index.tsindex d646529667..c4508cc7ef 100644--- a/packages/dashboard-core/src/index.ts+++ b/packages/dashboard-core/src/index.ts@@ -63,9 +63,9 @@ export * from './hooks/use-auto-collapse-sidebar'export * from './hooks/use-command-palette'export * from './hooks/use-countries'export * from './hooks/use-custom-fields'-export * from './hooks/use-direct-upload'export * from './hooks/use-display-name'export * from './hooks/use-export'+export * from './hooks/use-file-upload'export * from './hooks/use-global-search'export * from './hooks/use-host-form'export * from './hooks/use-import'diff --git a/packages/dashboard-core/src/lib/form-mappers.ts b/packages/dashboard-core/src/lib/form-mappers.tsindex ebd88ceb4b..8b6ff0658c 100644--- a/packages/dashboard-core/src/lib/form-mappers.ts+++ b/packages/dashboard-core/src/lib/form-mappers.ts@@ -135,12 +135,31 @@ export function accountFormToParams(values: {first_name: values.first_name ?? undefined,last_name: values.last_name ?? undefined,selected_locale: blankToUndefined(values.selected_locale),- ...avatarParam(values.avatar_signed_id, values.avatar_cleared),+ ...signedIdParam('avatar', values.avatar_signed_id, values.avatar_cleared),}}-function avatarParam(signedId: string | null, cleared: boolean) {- if (signedId) return { avatar: signedId }- if (cleared) return { avatar: null }+/**+ * The write for one attachment slot, under the API's `<slot>_signed_id` name:+ * a fresh upload sends its signed id, an explicit clear sends `null` to remove+ * the file, and an untouched field is left out entirely.+ */+export function signedIdParam<Slot extends string>(+ slot: Slot,+ signedId: string | null | undefined,+): Partial<Record<`${Slot}_signed_id`, string>>+export function signedIdParam<Slot extends string>(+ slot: Slot,+ signedId: string | null | undefined,+ cleared: boolean | undefined,+): Partial<Record<`${Slot}_signed_id`, string | null>>+export function signedIdParam<Slot extends string>(+ slot: Slot,+ signedId: string | null | undefined,+ cleared?: boolean,+): Partial<Record<`${Slot}_signed_id`, string | null>> {+ const key = `${slot}_signed_id` as `${Slot}_signed_id`+ if (signedId) return { [key]: signedId } as Record<`${Slot}_signed_id`, string>+ if (cleared) return { [key]: null } as Record<`${Slot}_signed_id`, null>return {}}diff --git a/packages/dashboard-core/src/products/product-form-cards.tsx b/packages/dashboard-core/src/products/product-form-cards.tsxindex 0154ef04f4..f8f7109c82 100644--- a/packages/dashboard-core/src/products/product-form-cards.tsx+++ b/packages/dashboard-core/src/products/product-form-cards.tsx@@ -20,7 +20,7 @@ import {parseVideoUrl,ResourceMultiAutocomplete,TagCombobox,- useDirectUpload,+ useFileUpload,useOptionalStore,} from '@spree/dashboard-core'import {@@ -296,7 +296,7 @@ export function MediaCard({form: UseFormReturn<ProductFormValues, any, any>}) {const { t } = useTranslation()- const directUpload = useDirectUpload()+ const fileUpload = useFileUpload()const deleteMedia = useDeleteProductMedia(productId ?? '')const confirm = useConfirm()const [pending, setPending] = useState<PendingUpload[]>([])@@ -349,7 +349,7 @@ export function MediaCard({const preview = URL.createObjectURL(file)setPending((prev) => [...prev, { id: uploadId, file, preview, progress: 'uploading' }])try {- const result = await directUpload.mutateAsync(file)+ const result = await fileUpload.mutateAsync(file)const current = form.getValues('media') ?? []form.setValue('media',@@ -384,7 +384,7 @@ export function MediaCard({}}},- [directUpload, form, t],+ [fileUpload, form, t],)const handleDrop = useCallback(diff --git a/packages/dashboard-core/src/products/product-schema.ts b/packages/dashboard-core/src/products/product-schema.tsindex 4f258bf48a..284def375e 100644--- a/packages/dashboard-core/src/products/product-schema.ts+++ b/packages/dashboard-core/src/products/product-schema.ts@@ -98,7 +98,7 @@ export const customFieldFormSchema = z.object({export type CustomFieldFormValues = z.infer<typeof customFieldFormSchema>// Media in form state. Persisted entries carry an `id`; pre-save entries carry-// a `signed_id` (from a completed ActiveStorage direct upload) or a+// a `signed_id` (from a completed upload) or a// `source_media_id` (a file picked from the library). All can hold edits to// alt, position, and variant_ids that the parent product PATCH/POST ships// inline. previewUrl + uploadId are UI-only; stripped at submit.diff --git a/packages/dashboard/e2e/companies.spec.ts b/packages/dashboard/e2e/companies.spec.tsindex 958ede2f85..aa5601328a 100644--- a/packages/dashboard/e2e/companies.spec.ts+++ b/packages/dashboard/e2e/companies.spec.ts@@ -165,6 +165,35 @@ test.describe('companies', () => {await expect(addressBook.getByText('400 Dock Rd')).toBeVisible({ timeout: 15_000 })})+ // The document goes to private storage: a PDF is refused by the public+ // allowlist, so this fails if the field ever uploads publicly again.+ test('adds a tax exemption certificate with a PDF document', async ({ page }) => {+ const creds = await login(page)+ await createCompany(page, creds.store_id, `E2E Exempt ${Date.now()}`)++ const certificates = card(page, /exemption certificates/i)+ await certificates.getByRole('button', { name: /add certificate/i }).click()+ const sheet = page.getByRole('dialog')+ await expect(sheet.getByText(/add exemption certificate/i)).toBeVisible()++ const certificateNumber = `RESALE-${Date.now()}`+ await sheet.locator('#certificate_number').fill(certificateNumber)+ await sheet.locator('#reason_code').click()+ await page.getByRole('option', { name: /^resale$/i }).click()+ await sheet.locator('input[type="file"]').setInputFiles({+ name: 'certificate.pdf',+ mimeType: 'application/pdf',+ buffer: Buffer.from('%PDF-1.4\n%%EOF\n'),+ })++ // Creating mid-upload would save the certificate without its document.+ await expect(sheet.getByText(/attached file/i)).toBeVisible({ timeout: 30_000 })+ await sheet.getByRole('button', { name: /^create$/i }).click()++ await expect(certificates.getByText(certificateNumber)).toBeVisible({ timeout: 15_000 })+ await expect(certificates.getByRole('button', { name: /certificate\.pdf/i })).toBeVisible()+ })+test('deletes a company from the list', async ({ page }) => {const creds = await login(page)const name = `E2E Dissolved ${Date.now()}`diff --git a/packages/dashboard/e2e/order-fulfillments.spec.ts b/packages/dashboard/e2e/order-fulfillments.spec.tsindex f2dc7ec370..a59d063c2d 100644--- a/packages/dashboard/e2e/order-fulfillments.spec.ts+++ b/packages/dashboard/e2e/order-fulfillments.spec.ts@@ -1,5 +1,5 @@import { expect, type Page, test } from '@playwright/test'-import { FIXTURE_PROMO_PRODUCT, login } from './helpers'+import { createPlacedOrder, FIXTURE_PROMO_PRODUCT, login } from './helpers'const NEW_ORDER_PATH = (storeId: string) => `/${storeId}/orders/new`@@ -86,4 +86,36 @@ test.describe('order fulfillments', () => {await expect(card.getByRole('button', { name: /buy label/i })).toHaveCount(0)await expect(card.getByRole('button', { name: /print label/i })).toHaveCount(0)})++ // A label bought elsewhere goes to private storage, under the+ // `file_signed_id` name the label endpoint now requires.+ test('uploads a label bought elsewhere onto a placed order', async ({ page }) => {+ const creds = await login(page)+ const order = await createPlacedOrder(page, creds.accessToken, { ship: false })+ await page.goto(`/${creds.store_id}/orders/${order.id}`)++ const card = fulfillmentsCard(page)+ await card+ .getByRole('button', { name: /^actions$/i })+ .first()+ .click({ timeout: 15_000 })+ await page.getByRole('menuitem', { name: /^upload label$/i }).click()++ const dialog = page.getByRole('dialog')+ await dialog.locator('input[type="file"]').setInputFiles({+ name: 'label.pdf',+ mimeType: 'application/pdf',+ buffer: Buffer.from('%PDF-1.4\n%%EOF\n'),+ })+ await dialog.locator('#label-tracking-number').fill(`1Z${Date.now()}`)++ // Saving is disabled until the upload resolves.+ const submit = dialog.getByRole('button', { name: /^upload label$/i })+ await expect(submit).toBeEnabled({ timeout: 30_000 })+ await submit.click()++ await expect(dialog).toBeHidden({ timeout: 15_000 })+ await expect(card.getByText(/^uploaded$/i)).toBeVisible({ timeout: 15_000 })+ await expect(card.getByRole('button', { name: /print label/i })).toBeVisible()+ })})diff --git a/packages/dashboard/e2e/store-settings.spec.ts b/packages/dashboard/e2e/store-settings.spec.tsindex ad7afbcf87..73a61b150c 100644--- a/packages/dashboard/e2e/store-settings.spec.ts+++ b/packages/dashboard/e2e/store-settings.spec.ts@@ -1,6 +1,13 @@+import * as path from 'node:path'+import { fileURLToPath } from 'node:url'import { expect, test } from '@playwright/test'import { login, openProfileDialog } from './helpers'+const FIXTURE_IMAGE = path.join(+ path.dirname(fileURLToPath(import.meta.url)),+ 'fixtures/test-image.png',+)+const STORE_PATH = (storeId: string) => `/${storeId}/settings/store`const EMAILS_PATH = (storeId: string) => `/${storeId}/settings/emails`@@ -277,6 +284,35 @@ test.describe('store settings — emails', () => {await expect(page.locator('#store-new-order-notifications-email')).toHaveValue(ops)})+ // Uploads, saves and then removes the logo, so the shared store ends where+ // it started.+ test('uploads the email logo, then removes it', async ({ page }) => {+ const creds = await login(page)+ await page.goto(EMAILS_PATH(creds.store_id))+ await expect(page.locator('#store-mail-from-address')).toBeVisible({ timeout: 15_000 })++ const savedLogo = page.getByText(/^attached file$/i)+ const save = page.getByRole('button', { name: /^save$/i })++ await page.locator('input[type="file"]').setInputFiles(FIXTURE_IMAGE)+ await expect(page.getByText(/uploading/i)).toBeHidden({ timeout: 30_000 })+ await expect(savedLogo).toBeVisible()+ await save.click()+ await expect(save).toBeDisabled({ timeout: 15_000 })++ await page.reload()+ await expect(savedLogo).toBeVisible({ timeout: 15_000 })++ await page.getByRole('button', { name: /^remove$/i }).click()+ await expect(savedLogo).toHaveCount(0)+ await save.click()+ await expect(save).toBeDisabled({ timeout: 15_000 })++ await page.reload()+ await expect(page.locator('#store-mail-from-address')).toBeVisible({ timeout: 15_000 })+ await expect(savedLogo).toHaveCount(0)+ })+test('flags an invalid mail_from_address inline', async ({ page }) => {const creds = await login(page)await page.goto(EMAILS_PATH(creds.store_id))diff --git a/packages/dashboard/package.json b/packages/dashboard/package.jsonindex 3d2a4aee12..b49e5af7d3 100644--- a/packages/dashboard/package.json+++ b/packages/dashboard/package.json@@ -90,7 +90,6 @@"react-hook-form": "^7.75.0","react-i18next": "^17.0.8","recharts": "3.10.1",- "spark-md5": "^3.0.2","tailwind-merge": "^3.5.0","tw-animate-css": "^1.4.0","zod": "^4.4.3"@@ -101,7 +100,6 @@"@types/node": "^25.6.0","@types/react": "^19.2.14","@types/react-dom": "^19.2.3",- "@types/spark-md5": "^3.0.5","@vitejs/plugin-react": "^6.0.1","shadcn": "^4.21.0","tailwindcss": "^4.2.4",diff --git a/packages/dashboard/src/api-client-setup.ts b/packages/dashboard/src/api-client-setup.tsindex 42b7c5c64d..82eca35c5b 100644--- a/packages/dashboard/src/api-client-setup.ts+++ b/packages/dashboard/src/api-client-setup.ts@@ -22,7 +22,7 @@ setApiClient({// shared component does not have to know which API it is talking to.updateAccount: (params) => adminClient.me.update(params),listCountries: () => adminClient.countries.list({ expand: ['states'] }),- createDirectUpload: (params) => adminClient.directUploads.create(params),+ uploadFile: (file, options) => adminClient.files.upload(file, options),// Backs the shared CSV import wizard, which both panels render. The// operator imports every registered dataset; a seller's client narrows// `types` to their own.diff --git a/packages/dashboard/src/components/spree/media-rich-text-editor.tsx b/packages/dashboard/src/components/spree/media-rich-text-editor.tsxindex f236b73652..f7b1d0b3ce 100644--- a/packages/dashboard/src/components/spree/media-rich-text-editor.tsx+++ b/packages/dashboard/src/components/spree/media-rich-text-editor.tsx@@ -1,5 +1,5 @@import type { Media } from '@spree/admin-sdk'-import { adminClient, MediaPickerSheet, useDirectUpload } from '@spree/dashboard-core'+import { adminClient, MediaPickerSheet, useFileUpload } from '@spree/dashboard-core'import { RichTextEditor, type RichTextEditorProps } from '@spree/dashboard-ui'import { useCallback, useRef, useState } from 'react'import { useCreateMediaLibraryFile } from '../../hooks/use-media-library'@@ -16,7 +16,7 @@ import { useCreateMediaLibraryFile } from '../../hooks/use-media-library'*/export function MediaRichTextEditor(props: Omit<RichTextEditorProps, 'onRequestImage'>) {const [picking, setPicking] = useState(false)- const directUpload = useDirectUpload()+ const fileUpload = useFileUpload()const createFile = useCreateMediaLibraryFile()// The editor asks for an image and waits; the sheet answers later, once the@@ -68,7 +68,7 @@ export function MediaRichTextEditor(props: Omit<RichTextEditorProps, 'onRequestI})}onUpload={async (file) => {- const upload = await directUpload.mutateAsync(file)+ const upload = await fileUpload.mutateAsync(file)return createFile.mutateAsync({ signed_id: upload.signedId, alt: file.name })}}onConfirm={(picked) => {diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsxindex feb258f430..03aa5796ee 100644--- a/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx+++ b/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx@@ -59,7 +59,7 @@ export function FulfillmentLabelUploadDialog({try {await buyLabel.mutateAsync({fulfillmentId,- file: file.signedId,+ file_signed_id: file.signedId,tracking_number: values.tracking_number.trim(),carrier: values.carrier.trim() || undefined,cost: values.cost.trim() || undefined,diff --git a/packages/dashboard/src/components/spree/orders/order-purchase-order-card.tsx b/packages/dashboard/src/components/spree/orders/order-purchase-order-card.tsxindex 644653b164..5463f0fbc1 100644--- a/packages/dashboard/src/components/spree/orders/order-purchase-order-card.tsx+++ b/packages/dashboard/src/components/spree/orders/order-purchase-order-card.tsx@@ -6,6 +6,7 @@ import {FileUploadField,type FileUploadValue,getApiClient,+ signedIdParam,useAuth,} from '@spree/dashboard-core'import {@@ -28,7 +29,7 @@ const PO_DOCUMENT_ACCEPT ='application/pdf,image/jpeg,image/png,image/heic,image/webp,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document'/** Narrowed from the SDK's own contract so the payload cannot drift from it. */-type UpdateParams = Pick<OrderUpdateParams, 'po_number' | 'po_document'>+type UpdateParams = Pick<OrderUpdateParams, 'po_number' | 'po_document_signed_id'>/*** The buyer's own purchase-order reference and the document behind it.@@ -68,12 +69,10 @@ export function OrderPurchaseOrderCard({ order }: { order: Order }) {event.preventDefault()const data = new FormData(event.currentTarget)- const params: UpdateParams = { po_number: data.get('po_number') as string }- // Three states: a new upload sends its signed id, an explicit removal- // sends null, and an untouched field is omitted so the save leaves- // whatever is attached alone.- if (document.signedId) params.po_document = document.signedId- else if (document.cleared) params.po_document = null+ const params: UpdateParams = {+ po_number: data.get('po_number') as string,+ ...signedIdParam('po_document', document.signedId, document.cleared),+ }mutation.mutate(params, {onSuccess: stopEditing,diff --git a/packages/dashboard/src/components/spree/products/digital-assets-card.tsx b/packages/dashboard/src/components/spree/products/digital-assets-card.tsxindex c82f74964b..57f149fd6b 100644--- a/packages/dashboard/src/components/spree/products/digital-assets-card.tsx+++ b/packages/dashboard/src/components/spree/products/digital-assets-card.tsx@@ -1,5 +1,5 @@import type { DigitalAsset, DigitalAssetProvider, Variant } from '@spree/admin-sdk'-import { formatFileSize, useDirectUpload } from '@spree/dashboard-core'+import { formatFileSize, useFileUpload } from '@spree/dashboard-core'import {Button,Card,@@ -61,7 +61,7 @@ export function DigitalAssetsCard({// Digital files live on private storage: they are only ever served through an// authorized, signed link, never from the public bucket.- const directUpload = useDirectUpload({ private: true })+ const fileUpload = useFileUpload({ visibility: 'private' })const { data, isLoading } = useDigitalAssets(productId ?? '', page, Boolean(productId))const { data: providersData } = useDigitalAssetProviders(productId ?? '', Boolean(productId))const createAsset = useCreateDigitalAsset(productId ?? '')@@ -84,7 +84,7 @@ export function DigitalAssetsCard({try {for (const file of list) {try {- const { signedId } = await directUpload.mutateAsync(file)+ const { signedId } = await fileUpload.mutateAsync(file)await createAsset.mutateAsync({ signed_id: signedId })} catch (err) {// The create mutation suppresses its own toast for validationdiff --git a/packages/dashboard/src/components/spree/products/digital-files-form-card.tsx b/packages/dashboard/src/components/spree/products/digital-files-form-card.tsxindex daa13e251c..8f06728eb1 100644--- a/packages/dashboard/src/components/spree/products/digital-files-form-card.tsx+++ b/packages/dashboard/src/components/spree/products/digital-files-form-card.tsx@@ -1,4 +1,4 @@-import { formatFileSize, type ProductFormValues, useDirectUpload } from '@spree/dashboard-core'+import { formatFileSize, type ProductFormValues, useFileUpload } from '@spree/dashboard-core'import {Button,Card,@@ -43,7 +43,7 @@ export function DigitalFilesFormCard({const confirm = useConfirm()// Files are only ever served through an authorized, signed link, so they go// to private storage — never the public bucket.- const directUpload = useDirectUpload({ private: true })+ const fileUpload = useFileUpload({ visibility: 'private' })const [pending, setPending] = useState<PendingUpload[]>([])const fileInputRef = useRef<HTMLInputElement>(null)@@ -56,7 +56,7 @@ export function DigitalFilesFormCard({const uploadId = crypto.randomUUID()setPending((prev) => [...prev, { id: uploadId, name: file.name }])try {- const { signedId } = await directUpload.mutateAsync(file)+ const { signedId } = await fileUpload.mutateAsync(file)const current = form.getValues('digital_assets') ?? []form.setValue('digital_assets',@@ -77,7 +77,7 @@ export function DigitalFilesFormCard({}}},- [directUpload, form, t],+ [fileUpload, form, t],)function handleFileInput(event: React.ChangeEvent<HTMLInputElement>) {diff --git a/packages/dashboard/src/components/spree/resource-image-field.tsx b/packages/dashboard/src/components/spree/resource-image-field.tsxindex bced4d5029..0067a73c93 100644--- a/packages/dashboard/src/components/spree/resource-image-field.tsx+++ b/packages/dashboard/src/components/spree/resource-image-field.tsx@@ -3,7 +3,7 @@ import {adminClient,ImageUploadField,MediaPickerSheet,- useDirectUpload,+ useFileUpload,} from '@spree/dashboard-core'import { Button } from '@spree/dashboard-ui'import { LibraryIcon } from '@spree/dashboard-ui/icons'@@ -13,7 +13,7 @@ import { useTranslation } from 'react-i18next'import { useCreateMediaLibraryFile } from '../../hooks/use-media-library'/**- * The form fields backing one image: a freshly direct-uploaded blob+ * The form fields backing one image: a freshly uploaded file* (`<name>_signed_id`), a transient object URL for the just-picked file* (`<name>_preview_url`), and a flag marking the persisted attachment for* removal (`<name>_cleared`). Together they form the three-state machine the@@ -73,7 +73,7 @@ export function ResourceImageField<Name extends string, T extends ImageFieldsFor}) {const { t } = useTranslation()const [picking, setPicking] = useState(false)- const directUpload = useDirectUpload()+ const fileUpload = useFileUpload()const createLibraryFile = useCreateMediaLibraryFile()// The adapter only ever touches this one image triple, and always by the@@ -127,7 +127,7 @@ export function ResourceImageField<Name extends string, T extends ImageFieldsFor})}onUpload={async (file) => {- const upload = await directUpload.mutateAsync(file)+ const upload = await fileUpload.mutateAsync(file)return createLibraryFile.mutateAsync({ signed_id: upload.signedId, alt: file.name })}}// Picking hands over the file's own blob, so this field and the librarydiff --git a/packages/dashboard/src/components/spree/tax-exemption-certificates-card.tsx b/packages/dashboard/src/components/spree/tax-exemption-certificates-card.tsxindex 7e55cfea4f..bbcaec5eb9 100644--- a/packages/dashboard/src/components/spree/tax-exemption-certificates-card.tsx+++ b/packages/dashboard/src/components/spree/tax-exemption-certificates-card.tsx@@ -533,6 +533,7 @@ function CertificateSheet({}}onChange={(next) => field.onChange(next.signedId)}accept="application/pdf,image/png,image/jpeg"+ private/>)}/>diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/orders/new.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/orders/new.tsxindex 21017dd49f..3221bcfddc 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/orders/new.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/orders/new.tsx@@ -109,7 +109,7 @@ function NewOrderPage() {if (values.po_number) payload.po_number = values.po_number// The bytes are already in private storage by now; the create carries// only the signed id the upload handed back.- if (poDocument.signedId) payload.po_document = poDocument.signedId+ if (poDocument.signedId) payload.po_document_signed_id = poDocument.signedIdif (values.coupon_code) payload.coupon_code = values.coupon_codeif (values.channel_id) payload.channel_id = values.channel_idreturn adminClient.orders.create(payload)diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/media.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/media.tsxindex 08879eecbb..e1e565689a 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/media.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/media.tsx@@ -5,7 +5,7 @@ import {ImageUploadField,PageHeader,Subject,- useDirectUpload,+ useFileUpload,usePermissions,} from '@spree/dashboard-core'import {@@ -111,7 +111,7 @@ function MediaLibraryPage() {const [uploading, setUploading] = useState(false)const fileInputRef = useRef<HTMLInputElement>(null)- const directUpload = useDirectUpload()+ const fileUpload = useFileUpload()const createFile = useCreateMediaLibraryFile()const deleteFile = useDeleteMediaLibraryFile()@@ -147,7 +147,7 @@ function MediaLibraryPage() {// Per file, so one bad file doesn't discard the ones that worked and// the merchant is told which failed.try {- const upload = await directUpload.mutateAsync(file)+ const upload = await fileUpload.mutateAsync(file)await createFile.mutateAsync({signed_id: upload.signedId,alt: file.name,diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsxindex 24370c55e8..f74912b01e 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsx@@ -24,7 +24,7 @@ import {resourceSearchSchema,runtimeListParams,Subject,- useDirectUpload,+ useFileUpload,usePermissions,} from '@spree/dashboard-core'import {@@ -725,7 +725,7 @@ function OptionValueImageField({const { t } = useTranslation()const fileInputId = useId()const fileInputRef = useRef<HTMLInputElement>(null)- const directUpload = useDirectUpload()+ const fileUpload = useFileUpload()const [localPreview, setLocalPreview] = useState<string | null>(null)const [uploading, setUploading] = useState(false)const [zoomOpen, setZoomOpen] = useState(false)@@ -750,7 +750,7 @@ function OptionValueImageField({if (!file) returnsetUploading(true)try {- const result = await directUpload.mutateAsync(file)+ const result = await fileUpload.mutateAsync(file)if (localPreview) URL.revokeObjectURL(localPreview)setLocalPreview(result.previewUrl)form.setValue(`option_values.${index}.image_signed_id`, result.signedId, {diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails/index.tsxindex 308da3a70d..26ce297a46 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails/index.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/emails/index.tsx@@ -5,6 +5,7 @@ import {mapSpreeErrorsToForm,PageHeader,Subject,+ signedIdParam,usePermissions,} from '@spree/dashboard-core'import {@@ -86,13 +87,7 @@ function formValuesToApiParams(values: StoreEmailsFormValues): StoreUpdateParamsemail_text_color: values.email_text_color || null,email_heading_color: values.email_heading_color || null,email_font: values.email_font,- }- // Three states for the logo: untouched (omit), uploaded (send signed_id),- // explicitly cleared (send null). Sending an empty value would be ambiguous.- if (values.mailer_logo_signed_id) {- params.mailer_logo = values.mailer_logo_signed_id- } else if (values.mailer_logo_cleared) {- params.mailer_logo = null+ ...signedIdParam('mailer_logo', values.mailer_logo_signed_id, values.mailer_logo_cleared),}return params}diff --git a/packages/dashboard/src/schemas/category.ts b/packages/dashboard/src/schemas/category.tsindex 0e6d97c463..23d268ca39 100644--- a/packages/dashboard/src/schemas/category.ts+++ b/packages/dashboard/src/schemas/category.ts@@ -1,5 +1,5 @@import type { Category } from '@spree/admin-sdk'-import { customFieldFormSchema } from '@spree/dashboard-core'+import { customFieldFormSchema, signedIdParam } from '@spree/dashboard-core'import { requiredMessage } from '@spree/dashboard-ui'import { z } from 'zod/v4'import type { ProductMembershipStagingValue } from '../components/spree/product-membership-staging'@@ -105,15 +105,7 @@ export function categoryToParams(values: CategoryFormValues) {...(values.custom_fields && values.custom_fields.length > 0? { custom_fields: values.custom_fields }: {}),- ...imageParam('image', values.image_signed_id, values.image_cleared),- ...imageParam('square_image', values.square_image_signed_id, values.square_image_cleared),+ ...signedIdParam('image', values.image_signed_id, values.image_cleared),+ ...signedIdParam('square_image', values.square_image_signed_id, values.square_image_cleared),}}--// Three-state mapping: a fresh upload sends the signed_id, an explicit clear-// sends null (purges the attachment), and an untouched field is omitted.-function imageParam(key: 'image' | 'square_image', signedId: string | null, cleared: boolean) {- if (signedId) return { [key]: signedId }- if (cleared) return { [key]: null }- return {}-}diff --git a/packages/dashboard/src/schemas/collection.ts b/packages/dashboard/src/schemas/collection.tsindex 9159cc53e7..cca9ecb91c 100644--- a/packages/dashboard/src/schemas/collection.ts+++ b/packages/dashboard/src/schemas/collection.ts@@ -1,5 +1,5 @@import type { Collection, CollectionRuleParam, CollectionSortOrder } from '@spree/admin-sdk'-import { customFieldFormSchema } from '@spree/dashboard-core'+import { customFieldFormSchema, signedIdParam } from '@spree/dashboard-core'import { requiredMessage } from '@spree/dashboard-ui'import { z } from 'zod/v4'import type { ProductMembershipStagingValue } from '../components/spree/product-membership-staging'@@ -193,15 +193,7 @@ export function collectionToParams(values: CollectionFormValues) {...(values.custom_fields && values.custom_fields.length > 0? { custom_fields: values.custom_fields }: {}),- ...imageParam('image', values.image_signed_id, values.image_cleared),- ...imageParam('square_image', values.square_image_signed_id, values.square_image_cleared),+ ...signedIdParam('image', values.image_signed_id, values.image_cleared),+ ...signedIdParam('square_image', values.square_image_signed_id, values.square_image_cleared),}}--// Three-state mapping: a fresh upload sends the signed_id, an explicit clear-// sends null (purges the attachment), and an untouched field is omitted.-function imageParam(key: 'image' | 'square_image', signedId: string | null, cleared: boolean) {- if (signedId) return { [key]: signedId }- if (cleared) return { [key]: null }- return {}-}diff --git a/packages/dashboard/src/schemas/company.ts b/packages/dashboard/src/schemas/company.tsindex f9bda4a269..13f05b051f 100644--- a/packages/dashboard/src/schemas/company.ts+++ b/packages/dashboard/src/schemas/company.ts@@ -3,7 +3,7 @@ import type {TaxExemptionCertificateParams,TaxIdentifierParams,} from '@spree/admin-sdk'-import { blankToNull } from '@spree/dashboard-core'+import { blankToNull, signedIdParam } from '@spree/dashboard-core'import { requiredMessage } from '@spree/dashboard-ui'import { z } from 'zod/v4'@@ -107,6 +107,6 @@ export function taxExemptionCertificateValuesToParams(issued_at: blankToNull(values.issued_at),expires_at: blankToNull(values.expires_at),issuing_authority: blankToNull(values.issuing_authority),- ...(values.document_signed_id ? { document: values.document_signed_id } : {}),+ ...signedIdParam('document', values.document_signed_id),}}diff --git a/packages/dashboard/src/schemas/option-type.ts b/packages/dashboard/src/schemas/option-type.tsindex 97ea590d4d..68754a0668 100644--- a/packages/dashboard/src/schemas/option-type.ts+++ b/packages/dashboard/src/schemas/option-type.ts@@ -1,5 +1,5 @@import type { OptionValue, OptionValueParams } from '@spree/admin-sdk'-import { i18n } from '@spree/dashboard-core'+import { i18n, signedIdParam } from '@spree/dashboard-core'import { requiredMessage } from '@spree/dashboard-ui'import { z } from 'zod/v4'@@ -64,15 +64,15 @@ export function optionValueToFormRow(ov: OptionValue): OptionValueFormValue {* Build the API payload for a single option_value row. `index` is the row's* current array position; we send `position: index + 1` (1-indexed) so* `acts_as_list` persists the drag-reordered order. The frontend-only image- * upload state collapses into the API's `image` field: a fresh signed_id is- * sent, an explicit clear sends `null`, and an untouched row omits `image`- * entirely so the existing attachment stays.+ * upload state collapses into the API's `image_signed_id` field: a fresh+ * signed_id is sent, an explicit clear sends `null`, and an untouched row+ * omits it entirely so the existing attachment stays.*/export function valueToParam(v: OptionValueFormValue, index: number): OptionValueParams {const { image_signed_id, image_url: _imageUrl, image_cleared, ...rest } = vreturn {...rest,position: index + 1,- ...(image_signed_id ? { image: image_signed_id } : image_cleared ? { image: null } : {}),+ ...signedIdParam('image', image_signed_id, image_cleared),}}diff --git a/packages/dashboard/src/schemas/seller.ts b/packages/dashboard/src/schemas/seller.tsindex 71a884fadd..5dfa1f0fab 100644--- a/packages/dashboard/src/schemas/seller.ts+++ b/packages/dashboard/src/schemas/seller.ts@@ -1,5 +1,5 @@import type { SellerCreateParams } from '@spree/admin-sdk'-import { blankToNull } from '@spree/dashboard-core'+import { blankToNull, signedIdParam } from '@spree/dashboard-core'import { requiredMessage } from '@spree/dashboard-ui'import { z } from 'zod/v4'@@ -91,26 +91,14 @@ export function sellerValuesToParams(values: SellerFormValues): SellerCreatePara/** The image params only, for the sheet that owns the branding. */export function sellerImageParams(values: SellerFormValues,-): Pick<SellerCreateParams, 'logo' | 'square_logo' | 'cover_photo'> {+): Pick<SellerCreateParams, 'logo_signed_id' | 'square_logo_signed_id' | 'cover_photo_signed_id'> {return {- ...imageParam('logo', values.logo_signed_id, values.logo_cleared),- ...imageParam('square_logo', values.square_logo_signed_id, values.square_logo_cleared),- ...imageParam('cover_photo', values.cover_photo_signed_id, values.cover_photo_cleared),+ ...signedIdParam('logo', values.logo_signed_id, values.logo_cleared),+ ...signedIdParam('square_logo', values.square_logo_signed_id, values.square_logo_cleared),+ ...signedIdParam('cover_photo', values.cover_photo_signed_id, values.cover_photo_cleared),}}-// Three-state mapping: a fresh upload sends the signed_id, an explicit clear-// sends null (purges the attachment), and an untouched field is omitted.-function imageParam(- key: 'logo' | 'square_logo' | 'cover_photo',- signedId: string | null,- cleared: boolean,-): Partial<Record<'logo' | 'square_logo' | 'cover_photo', string | null>> {- if (signedId) return { [key]: signedId }- if (cleared) return { [key]: null }- return {}-}-export const sellerInviteSchema = z.object({email: z.email({ error: requiredMessage('email') }),})diff --git a/packages/dashboard/src/schemas/store-emails.ts b/packages/dashboard/src/schemas/store-emails.tsindex fd14824709..cb15d5420d 100644--- a/packages/dashboard/src/schemas/store-emails.ts+++ b/packages/dashboard/src/schemas/store-emails.ts@@ -47,11 +47,11 @@ export const storeEmailsFormSchema = z.object({email_heading_color: optionalColor,email_font: z.enum(EMAIL_FONTS),- // Active Storage signed_id from a fresh direct upload. Frontend-only state.+ // signed_id from a fresh upload. Frontend-only state.mailer_logo_signed_id: z.string().nullable().optional(),// Local blob URL for the just-picked file so the preview updates before save.mailer_logo_preview_url: z.string().nullable().optional(),- // Tracks the user clicking "Remove logo" — collapses to `mailer_logo: null`.+ // Tracks the user clicking "Remove logo" — collapses to `mailer_logo_signed_id: null`.mailer_logo_cleared: z.boolean().optional(),})diff --git a/packages/sdk-core/package.json b/packages/sdk-core/package.jsonindex 690555bf26..a0428b3f35 100644--- a/packages/sdk-core/package.json+++ b/packages/sdk-core/package.json@@ -33,6 +33,8 @@"clean": "rm -rf dist"},"devDependencies": {+ "@types/spark-md5": "^3.0.5",+ "spark-md5": "^3.0.2","tsup": "^8.5.1","typescript": "^6.0.3","yaml": "^2.9.1"diff --git a/packages/sdk-core/src/index.ts b/packages/sdk-core/src/index.tsindex abfbbb0fbb..97ac8b5015 100644--- a/packages/sdk-core/src/index.ts+++ b/packages/sdk-core/src/index.ts@@ -54,3 +54,5 @@ export type {ProviderLogin,ValidationErrorDetail,} from './types'+export type { FileUploadCreateParams, FileUploadResponse, UploadFileOptions } from './uploads'+export { computeChecksum, uploadFile } from './uploads'diff --git a/packages/sdk-core/src/request.ts b/packages/sdk-core/src/request.tsindex 5b8d203122..709feb9e54 100644--- a/packages/sdk-core/src/request.ts+++ b/packages/sdk-core/src/request.ts@@ -155,9 +155,12 @@ export function createRequestFn(}})}+ // A multipart body sets its own Content-Type, boundary included.+ const isFormData = typeof FormData !== 'undefined' && body instanceof FormData+// Build headersconst requestHeaders: Record<string, string> = {- 'Content-Type': 'application/json',+ ...(isFormData ? {} : { 'Content-Type': 'application/json' }),...headers,}@@ -207,7 +210,7 @@ export function createRequestFn(const response = await config.fetchFn(url.toString(), {method,headers: requestHeaders,- body: body ? JSON.stringify(body) : undefined,+ body: isFormData ? body : body ? JSON.stringify(body) : undefined,credentials: config.credentials,})diff --git a/packages/sdk-core/src/uploads.ts b/packages/sdk-core/src/uploads.tsnew file mode 100644index 0000000000..fd6b44394b--- /dev/null+++ b/packages/sdk-core/src/uploads.ts@@ -0,0 +1,97 @@+import SparkMD5 from 'spark-md5'++/** What `POST /files` accepts as JSON, for a presigned upload. */+export interface FileUploadCreateParams {+ filename: string+ content_type: string+ byte_size: number+ /** Base64-encoded MD5 digest of the file; the storage service checks the bytes against it. */+ checksum: string+ /** `public` (the default) for images and videos customers see, `private` for anything else. */+ visibility?: 'public' | 'private'+}++/** The parts of the `POST /files` response the upload helper reads. */+export interface FileUploadResponse {+ signed_id: string+ upload: { method: string; url: string; headers: Record<string, string> } | null+}++export interface UploadFileOptions {+ visibility?: 'public' | 'private'+ /** Defaults to the file's own name, when it has one. */+ filename?: string+ /** Defaults to the file's own type. */+ contentType?: string+ /**+ * `presigned` (the default) sends the bytes straight to storage, for files+ * of any size. `multipart` sends them in the request itself, which needs no+ * checksum but is limited to 10 MB by default.+ */+ method?: 'presigned' | 'multipart'+ /** Rewrites the storage URL before the bytes are sent, e.g. to keep a dev proxy same-origin. */+ resolveUploadUrl?: (url: string) => string+ /** Used for the storage request. Defaults to the global `fetch`. */+ fetch?: typeof fetch+}++const MD5_CHUNK_SIZE = 2 * 1024 * 1024++/** Base64-encoded MD5 digest of a file, read in chunks so large files stay out of memory. */+export async function computeChecksum(file: Blob): Promise<string> {+ const spark = new SparkMD5.ArrayBuffer()+ for (let start = 0; start < file.size; start += MD5_CHUNK_SIZE) {+ spark.append(await file.slice(start, start + MD5_CHUNK_SIZE).arrayBuffer())+ }+ return btoa(spark.end(true))+}++/**+ * Uploads a file through `POST /files` and resolves to the response, whose+ * `signed_id` is what the endpoint that uses the file takes.+ *+ * @param create - the client's `files.create`+ */+export async function uploadFile<T extends FileUploadResponse>(+ create: (body: FileUploadCreateParams | FormData) => Promise<T>,+ file: Blob,+ options: UploadFileOptions = {},+): Promise<T> {+ const filename = options.filename ?? (file as Blob & { name?: string }).name ?? 'file'+ const contentType = options.contentType || file.type || 'application/octet-stream'+ const visibility = options.visibility ?? 'public'++ if (options.method === 'multipart') {+ const form = new FormData()+ form.append('file', file, filename)+ form.append('filename', filename)+ form.append('content_type', contentType)+ form.append('visibility', visibility)+ return create(form)+ }++ const response = await create({+ filename,+ content_type: contentType,+ byte_size: file.size,+ checksum: await computeChecksum(file),+ visibility,+ })+ if (!response.upload) return response++ const url = options.resolveUploadUrl+ ? options.resolveUploadUrl(response.upload.url)+ : response.upload.url+ const fetchFn = options.fetch ?? fetch.bind(globalThis)+ const stored = await fetchFn(url, {+ method: response.upload.method,+ headers: response.upload.headers,+ body: file,+ })+ if (!stored.ok) {+ const text = await stored.text().catch(() => '')+ throw new Error(`Storage upload failed (${stored.status}): ${text}`)+ }++ return response+}diff --git a/packages/sdk-core/tsup.config.ts b/packages/sdk-core/tsup.config.tsindex 3b22e6dbc1..b7017bc802 100644--- a/packages/sdk-core/tsup.config.ts+++ b/packages/sdk-core/tsup.config.ts@@ -11,4 +11,6 @@ export default defineConfig({clean: true,treeshake: true,minify: false,+ // Inlined so the SDKs that bundle sdk-core ship no extra dependency.+ noExternal: ['spark-md5'],})diff --git a/packages/sdk/src/types/generated/FileUpload.ts b/packages/sdk/src/types/generated/FileUpload.tsnew file mode 100644index 0000000000..81ba092905--- /dev/null+++ b/packages/sdk/src/types/generated/FileUpload.ts@@ -0,0 +1,16 @@+// Typelizer digest 7a884ae6d631bee1659086d1f953f34f+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.+import type {FileUploadTarget} from '@/types'++interface FileUpload {+ signed_id: string;+ filename: string;+ content_type: string;+ byte_size: number;+ visibility: 'public' | 'private';+ expires_at: string;+ upload: FileUploadTarget | null;+}++export default FileUpload;diff --git a/packages/sdk/src/types/generated/FileUploadTarget.ts b/packages/sdk/src/types/generated/FileUploadTarget.tsnew file mode 100644index 0000000000..3555bc4eb0--- /dev/null+++ b/packages/sdk/src/types/generated/FileUploadTarget.ts@@ -0,0 +1,11 @@+// Typelizer digest a9603f6f347f9719ba7630c7eeead99e+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface FileUploadTarget {+ method: string;+ url: string;+ headers: Record<string, string>;+}++export default FileUploadTarget;diff --git a/packages/sdk/src/types/generated/index.ts b/packages/sdk/src/types/generated/index.tsindex e3aa167690..2ef16b56fd 100644--- a/packages/sdk/src/types/generated/index.ts+++ b/packages/sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest 505cb4a7b71e98e2e6a49b5fdd2928fd+// Typelizer digest 5bc3efa86f6c9405fc4a497b233395f3//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { ClaimStatus, DataRequestStatus, ExchangeStatus, FeeKind, FulfillmentStatus, GiftCardStatus, ImportRowStatus, ImportStatus, InvitationStatus, PaymentSessionStatus, PaymentSetupSessionStatus, PaymentStatus, ProductSubmissionStatus, ReturnStatus, ShippingLabelStatus } from './Enums'@@ -35,6 +35,8 @@ export type { default as ExchangeLineItem } from './ExchangeLineItem'export type { default as Exchange } from './Exchange'export type { default as Export } from './Export'export type { default as Fee } from './Fee'+export type { default as FileUpload } from './FileUpload'+export type { default as FileUploadTarget } from './FileUploadTarget'export type { default as FreightSummary } from './FreightSummary'export type { default as Fulfillment } from './Fulfillment'export type { default as GiftCardBatch } from './GiftCardBatch'diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.tsindex 51debf13ba..139a94d60f 100644--- a/packages/sdk/src/types/index.ts+++ b/packages/sdk/src/types/index.ts@@ -202,10 +202,10 @@ export interface UpdateCartParams {*/po_number?: string | null/**- * ActiveStorage signed blob id of the buyer's purchase order, from+ * The `signed_id` of the buyer's purchase order, from* `POST /store/carts/:id/po_document`. Blank detaches the document.*/- po_document?: string | null+ po_document_signed_id?: string | null}// Paymentsdiff --git a/packages/sdk/src/zod/generated/FileUpload.ts b/packages/sdk/src/zod/generated/FileUpload.tsnew file mode 100644index 0000000000..8cdf6ec602--- /dev/null+++ b/packages/sdk/src/zod/generated/FileUpload.ts@@ -0,0 +1,15 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';+import { FileUploadTargetSchema } from './FileUploadTarget';++export const FileUploadSchema = z.object({+ signed_id: z.string(),+ filename: z.string(),+ content_type: z.string(),+ byte_size: z.number(),+ visibility: z.string(),+ expires_at: z.string(),+ upload: FileUploadTargetSchema.nullable(),+});++export type FileUpload = z.infer<typeof FileUploadSchema>;diff --git a/packages/sdk/src/zod/generated/FileUploadTarget.ts b/packages/sdk/src/zod/generated/FileUploadTarget.tsnew file mode 100644index 0000000000..ab0d27aa76--- /dev/null+++ b/packages/sdk/src/zod/generated/FileUploadTarget.ts@@ -0,0 +1,10 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';++export const FileUploadTargetSchema = z.object({+ method: z.string(),+ url: z.string(),+ headers: z.record(z.string(), z.string()),+});++export type FileUploadTarget = z.infer<typeof FileUploadTargetSchema>;diff --git a/packages/sdk/src/zod/generated/index.ts b/packages/sdk/src/zod/generated/index.tsindex b9912498bd..2dd239652b 100644--- a/packages/sdk/src/zod/generated/index.ts+++ b/packages/sdk/src/zod/generated/index.ts@@ -32,6 +32,8 @@ export { ExchangeSchema, type Exchange } from './Exchange';export { ExchangeLineItemSchema, type ExchangeLineItem } from './ExchangeLineItem';export { ExportSchema, type Export } from './Export';export { FeeSchema, type Fee } from './Fee';+export { FileUploadSchema, type FileUpload } from './FileUpload';+export { FileUploadTargetSchema, type FileUploadTarget } from './FileUploadTarget';export { FreightSummarySchema, type FreightSummary } from './FreightSummary';export { FulfillmentSchema, type Fulfillment } from './Fulfillment';export { GiftCardSchema, type GiftCard } from './GiftCard';diff --git a/packages/seller-dashboard/src/api-client.ts b/packages/seller-dashboard/src/api-client.tsindex 42d3973518..9b3d298b1b 100644--- a/packages/seller-dashboard/src/api-client.ts+++ b/packages/seller-dashboard/src/api-client.ts@@ -71,7 +71,7 @@ export function createSellerApiClient({// The shared address form reads countries through the registered client,// so it works in a panel that has no admin credential.listCountries: () => sellerClient().countries.list(),- createDirectUpload: (params) => sellerClient().directUploads.create(params),+ uploadFile: (file, options) => sellerClient().files.upload(file, options),// A file download is a bare fetch, so it does not go through the client// and picks up none of its headers. Without the seller header the Seller// API refuses the request before the action runs, so an export woulddiff --git a/packages/seller-dashboard/src/components/orders/fulfillment-label-upload-dialog.tsx b/packages/seller-dashboard/src/components/orders/fulfillment-label-upload-dialog.tsxindex cadbb67e6b..4a793b9b33 100644--- a/packages/seller-dashboard/src/components/orders/fulfillment-label-upload-dialog.tsx+++ b/packages/seller-dashboard/src/components/orders/fulfillment-label-upload-dialog.tsx@@ -59,7 +59,7 @@ export function FulfillmentLabelUploadDialog({try {await uploadLabel.mutateAsync({fulfillmentId,- file: file.signedId,+ file_signed_id: file.signedId,tracking_number: values.tracking_number.trim(),carrier: values.carrier.trim() || undefined,cost: values.cost.trim() || undefined,diff --git a/packages/seller-dashboard/src/hooks/use-fulfillments.ts b/packages/seller-dashboard/src/hooks/use-fulfillments.tsindex 796cc55c85..3608f03dc6 100644--- a/packages/seller-dashboard/src/hooks/use-fulfillments.ts+++ b/packages/seller-dashboard/src/hooks/use-fulfillments.ts@@ -125,7 +125,7 @@ export function useFulfillmentActions(orderId: string) {...params}: {fulfillmentId: string- file: string+ file_signed_id: string// Required: a label with no tracking number is refused server-side,// since nothing could then follow the parcel it prints.tracking_number: stringdiff --git a/packages/seller-dashboard/src/pages/onboarding.tsx b/packages/seller-dashboard/src/pages/onboarding.tsxindex 9148c599a2..467bc924aa 100644--- a/packages/seller-dashboard/src/pages/onboarding.tsx+++ b/packages/seller-dashboard/src/pages/onboarding.tsx@@ -244,7 +244,7 @@ function RequirementAction({ requirement }: { requirement: RequirementStatus })mutationFn: () =>sellerClient().requirementSubmissions.create(requirement.id, {note: note || undefined,- file: file.signedId || undefined,+ file_signed_id: file.signedId || undefined,}),onSuccess: () => {setNote('')@@ -349,6 +349,7 @@ function RequirementAction({ requirement }: { requirement: RequirementStatus })value={file}onChange={setFile}accept={requirement.accepted_content_types?.join(',')}+ privatelabel={t('onboarding.document_label')}help={t('onboarding.document_help')}/>diff --git a/packages/seller-sdk/src/index.ts b/packages/seller-sdk/src/index.tsindex af4e768e2b..24af935d68 100644--- a/packages/seller-sdk/src/index.ts+++ b/packages/seller-sdk/src/index.ts@@ -1,4 +1,9 @@-export type { RequestOptions, RetryConfig } from '@spree/sdk-core'+export type {+ FileUploadCreateParams,+ RequestOptions,+ RetryConfig,+ UploadFileOptions,+} from '@spree/sdk-core'// Request infrastructure (re-exported from sdk-core)export {compareMoney,diff --git a/packages/seller-sdk/src/seller-client.ts b/packages/seller-sdk/src/seller-client.tsindex 7936181a2a..a3a17536e1 100644--- a/packages/seller-sdk/src/seller-client.ts+++ b/packages/seller-sdk/src/seller-client.ts@@ -1,11 +1,13 @@import type {+ FileUploadCreateParams,ListParams,PaginatedResponse,PreferenceSchema,RequestFn,RequestOptions,+ UploadFileOptions,} from '@spree/sdk-core'-import { transformListParams } from '@spree/sdk-core'+import { transformListParams, uploadFile } from '@spree/sdk-core'import type {Account,AuthTokens,@@ -17,6 +19,7 @@ import type {DeliveryZone,Exchange,Export,+ FileUpload,Fulfillment,Import,ImportFilters,@@ -681,8 +684,8 @@ export class SellerClient {* elsewhere and print it back; buying and refunding need the operator's* carrier account, so neither is offered here.*- * Upload the file with `directUploads.create()` and pass the returned- * `signed_id` as `file`.+ * Upload the file with `files.upload()` and pass the returned+ * `signed_id` as `file_signed_id`.*/labels: {list: (@@ -712,7 +715,7 @@ export class SellerClient {orderId: string,fulfillmentId: string,params: {- file: string+ file_signed_id: stringtracking_number: stringcarrier?: stringservice?: string@@ -1002,20 +1005,30 @@ export class SellerClient {}/**- * Presigning for the documents onboarding asks for. Exchange the blob's- * metadata for an upload URL, PUT the file to it, then post the returned- * `signed_id` as a submission's `file`.+ * Uploading the files a profile, a requirement submission or an import+ * uses. Each upload returns a `signed_id`: pass it unchanged as the+ * submission's `file_signed_id`, the profile's `logo_signed_id`, and so on,+ * within a day, after which it expires.*/- readonly directUploads = {+ readonly files = {+ /**+ * Creates an upload. JSON metadata returns `upload`, the storage target to+ * send the bytes to; a `FormData` body with a `file` part stores the bytes+ * directly and returns `upload: null`. `upload()` does both steps for you.+ */create: (- params: {- blob: { filename: string; byte_size: number; checksum: string; content_type: string }- },+ params: FileUploadCreateParams | FormData,options?: RequestOptions,- ): Promise<{- direct_upload: { url: string; headers: Record<string, string> }- signed_id: string- }> => this.request('POST', '/direct_uploads', { ...options, body: params }),+ ): Promise<FileUpload> =>+ this.request<FileUpload>('POST', '/files', { ...options, body: params }),++ /** Uploads a file and resolves to the response, whose `signed_id` the endpoint using the file takes. */+ upload: (+ file: Blob,+ options: UploadFileOptions = {},+ requestOptions?: RequestOptions,+ ): Promise<FileUpload> =>+ uploadFile((body) => this.files.create(body, requestOptions), file, options),}/**@@ -1323,7 +1336,7 @@ export class SellerClient {/*** Bulk-listing this seller's catalog from a CSV.*- * The flow is the operator's: upload the file with `directUploads.create()`,+ * The flow is the operator's: upload the file with `files.upload()`,* `create()` the import from the returned `signed_id`, and the response* comes back in the `mapping` state carrying `schema_fields`, `csv_headers`,* a `sample_row` and the auto-assigned `mappings`. Adjust those and call@@ -1414,10 +1427,10 @@ export type SellerImportType = 'products'export interface ImportCreateParams {type: SellerImportType/**- * ActiveStorage signed blob id of the uploaded CSV, from- * `directUploads.create()`.+ * The `signed_id` of the uploaded CSV, from `files.upload()` with+ * `visibility: 'private'`.*/- attachment: string+ attachment_signed_id: string/** CSV column separator. Defaults to a comma on the server. */delimiter?: ',' | ';' | '|' | '\t'/**@@ -1607,8 +1620,8 @@ export interface OnboardingResponse {export interface RequirementSubmissionParams {note?: stringreference?: string- /** A direct-upload signed blob id, for kinds that ask for a document. */- file?: string+ /** A `signed_id` from `files.upload()`, for kinds that ask for a document. */+ file_signed_id?: string}/** The fields a seller may set on their own product. */@@ -1764,10 +1777,10 @@ export interface AccountUpdateParams {/** The panel's UI language, as a bundle code the panel ships (e.g. `de`). */selected_locale?: string/**- * ActiveStorage signed id to set the photo, or `null` to remove it. Omit to- * leave the current one alone.+ * A `signed_id` from `files.upload()` to set the photo, or `null` to remove+ * it. Omit to leave the current one alone.*/- avatar?: string | null+ avatar_signed_id?: string | null}/** The fields a seller may change on their own record. */@@ -1777,10 +1790,10 @@ export interface ProfileUpdateParams {billing_email?: string | null/** Sanitized HTML — the seller's public description. */about?: string | null- /** ActiveStorage signed ids; `null` removes the attachment. */- logo?: string | null- square_logo?: string | null- cover_photo?: string | null+ /** `signed_id`s from `files.upload()`; `null` removes the image. */+ logo_signed_id?: string | null+ square_logo_signed_id?: string | null+ cover_photo_signed_id?: string | null/** The business a commission invoice is made out to. */legal_name?: string | nullregistration_number?: string | nulldiff --git a/packages/seller-sdk/src/types/generated/FileUpload.ts b/packages/seller-sdk/src/types/generated/FileUpload.tsnew file mode 100644index 0000000000..fbca555d15--- /dev/null+++ b/packages/seller-sdk/src/types/generated/FileUpload.ts@@ -0,0 +1,16 @@+// Typelizer digest 7a884ae6d631bee1659086d1f953f34f+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.+import type {FileUploadTarget} from '@/types'++type FileUpload = {+ signed_id: string;+ filename: string;+ content_type: string;+ byte_size: number;+ visibility: 'public' | 'private';+ expires_at: string;+ upload: FileUploadTarget | null;+}++export default FileUpload;diff --git a/packages/seller-sdk/src/types/generated/FileUploadTarget.ts b/packages/seller-sdk/src/types/generated/FileUploadTarget.tsnew file mode 100644index 0000000000..d4cc594cfa--- /dev/null+++ b/packages/seller-sdk/src/types/generated/FileUploadTarget.ts@@ -0,0 +1,11 @@+// Typelizer digest a9603f6f347f9719ba7630c7eeead99e+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++type FileUploadTarget = {+ method: string;+ url: string;+ headers: Record<string, string>;+}++export default FileUploadTarget;diff --git a/packages/seller-sdk/src/types/generated/index.ts b/packages/seller-sdk/src/types/generated/index.tsindex f66ca355f5..9dce3550c7 100644--- a/packages/seller-sdk/src/types/generated/index.ts+++ b/packages/seller-sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest e1a3efc688a8d706b62f652cdc101318+// Typelizer digest 8e3f7f5fe36c8db2ba7aeb82704bdb86//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { ClaimStatus, ExchangeStatus, FulfillmentStatus, ImportRowStatus, ImportStatus, InvitationStatus, ProductStatus, ProductSubmissionStatus, ReturnStatus, SellerRequirementSubmissionStatus, SellerStatus, ShippingLabelStatus, StockLocationKind } from './Enums'@@ -20,6 +20,8 @@ export type { default as DeliveryZone } from './DeliveryZone'export type { default as ExchangeLineItem } from './ExchangeLineItem'export type { default as Exchange } from './Exchange'export type { default as Export } from './Export'+export type { default as FileUpload } from './FileUpload'+export type { default as FileUploadTarget } from './FileUploadTarget'export type { default as FulfillmentItem } from './FulfillmentItem'export type { default as Fulfillment } from './Fulfillment'export type { default as ImportMapping } from './ImportMapping'diff --git a/packages/seller-sdk/src/zod/generated/FileUpload.ts b/packages/seller-sdk/src/zod/generated/FileUpload.tsnew file mode 100644index 0000000000..8cdf6ec602--- /dev/null+++ b/packages/seller-sdk/src/zod/generated/FileUpload.ts@@ -0,0 +1,15 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';+import { FileUploadTargetSchema } from './FileUploadTarget';++export const FileUploadSchema = z.object({+ signed_id: z.string(),+ filename: z.string(),+ content_type: z.string(),+ byte_size: z.number(),+ visibility: z.string(),+ expires_at: z.string(),+ upload: FileUploadTargetSchema.nullable(),+});++export type FileUpload = z.infer<typeof FileUploadSchema>;diff --git a/packages/seller-sdk/src/zod/generated/FileUploadTarget.ts b/packages/seller-sdk/src/zod/generated/FileUploadTarget.tsnew file mode 100644index 0000000000..ab0d27aa76--- /dev/null+++ b/packages/seller-sdk/src/zod/generated/FileUploadTarget.ts@@ -0,0 +1,10 @@+// This file is auto-generated. Do not edit directly.+import { z } from 'zod';++export const FileUploadTargetSchema = z.object({+ method: z.string(),+ url: z.string(),+ headers: z.record(z.string(), z.string()),+});++export type FileUploadTarget = z.infer<typeof FileUploadTargetSchema>;diff --git a/packages/seller-sdk/src/zod/generated/index.ts b/packages/seller-sdk/src/zod/generated/index.tsindex 7b37a0150e..470ec48c02 100644--- a/packages/seller-sdk/src/zod/generated/index.ts+++ b/packages/seller-sdk/src/zod/generated/index.ts@@ -15,6 +15,8 @@ export { DeliveryZoneSchema, type DeliveryZone } from './DeliveryZone';export { ExchangeSchema, type Exchange } from './Exchange';export { ExchangeLineItemSchema, type ExchangeLineItem } from './ExchangeLineItem';export { ExportSchema, type Export } from './Export';+export { FileUploadSchema, type FileUpload } from './FileUpload';+export { FileUploadTargetSchema, type FileUploadTarget } from './FileUploadTarget';export { FulfillmentSchema, type Fulfillment } from './Fulfillment';export { FulfillmentItemSchema, type FulfillmentItem } from './FulfillmentItem';export { ImportSchema, type Import } from './Import';diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 862ec158e9..7ad7700ca8 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -256,9 +256,6 @@ importers:recharts:specifier: 3.10.1version: 3.10.1(@types/[email protected])([email protected]([email protected]))([email protected])([email protected])([email protected])- spark-md5:- specifier: ^3.0.2- version: 3.0.2tailwind-merge:specifier: ^3.5.0version: 3.7.0@@ -284,9 +281,6 @@ importers:'@types/react-dom':specifier: ^19.2.3version: 19.3.0(@types/[email protected])- '@types/spark-md5':- specifier: ^3.0.5- version: 3.0.5'@vitejs/plugin-react':specifier: ^6.0.1version: 6.1.2([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected]))@@ -338,9 +332,6 @@ importers:'@tanstack/react-table':specifier: ^8.21.3- '@types/spark-md5':- specifier: ^3.0.5- version: 3.0.5date-fns:specifier: ^4.1.0version: 4.4.0@@ -365,9 +356,6 @@ importers:react-i18next:specifier: ^17.0.8version: 17.0.16([email protected]([email protected]))([email protected]([email protected]))([email protected])([email protected])- spark-md5:- specifier: ^3.0.2- version: 3.0.2zod:specifier: ^4.4.3version: 4.6.5@@ -690,6 +678,12 @@ importers:packages/sdk-core:devDependencies:+ '@types/spark-md5':+ specifier: ^3.0.5+ version: 3.0.5+ spark-md5:+ specifier: ^3.0.2+ version: 3.0.2tsup:specifier: ^8.5.1version: 8.5.1([email protected])([email protected])([email protected])([email protected])([email protected])diff --git a/spree/api/app/controllers/concerns/spree/api/v3/direct_uploads.rb b/spree/api/app/controllers/concerns/spree/api/v3/direct_uploads.rbdeleted file mode 100644index 47a5881286..0000000000--- a/spree/api/app/controllers/concerns/spree/api/v3/direct_uploads.rb+++ /dev/null@@ -1,35 +0,0 @@-module Spree- module Api- module V3- # Presigning for direct-to-storage uploads: a caller exchanges blob- # metadata for an upload URL and gets back a signed id to reference when- # it creates or updates a resource.- #- # Shared by the admin and seller branches because the exchange itself is- # audience-neutral — a blob created here is attached to nothing. What- # differs is the gate each branch puts in front of it, which stays on the- # including controller as its `scoped_resource`.- module DirectUploads- extend ActiveSupport::Concern-- def create- blob = ActiveStorage::Blob.create_before_direct_upload!(**blob_params)-- render json: {- direct_upload: {- url: blob.service_url_for_direct_upload,- headers: blob.service_headers_for_direct_upload- },- signed_id: blob.signed_id- }, status: :created- end-- private-- def blob_params- params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys- end- end- end- end-enddiff --git a/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb b/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rbindex 7c68c597f2..b0dcc27f67 100644--- a/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb+++ b/spree/api/app/controllers/concerns/spree/api/v3/error_handler.rb@@ -107,6 +107,7 @@ module Spreerescue_from ActiveRecord::RecordNotSaved, with: :handle_record_not_savedrescue_from ArgumentError, with: :handle_argument_errorrescue_from ActionDispatch::Http::Parameters::ParseError, with: :handle_parse_error+ rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :handle_invalid_signatureendprotected@@ -277,6 +278,16 @@ module Spree)end+ # A `signed_id` that was tampered with, or has expired (they last a+ # day), is a bad parameter rather than a server fault.+ def handle_invalid_signature(_exception)+ render_error(+ code: ERROR_CODES[:parameter_invalid],+ message: I18n.t('spree.upload_reference_invalid'),+ status: :unprocessable_content+ )+ end+def handle_parse_error(exception)Rails.error.report(exception, context: error_context, source: 'spree.api.v3')message = exception.respond_to?(:original_message) ? exception.original_message : exception.message@@ -298,10 +309,14 @@ module Spreeend# A setting the API reads and writes under its plain name reports its- # errors under that name too, never the `preferred_` one the model uses.+ # errors under that name too, never the `preferred_` one the model uses;+ # an attachment slot reports them under the `<slot>_signed_id` it is+ # written with.def wire_error_attribute(errors, attribute)record_class = errors.objects.first&.base&.class- (record_class.exposed_preference_name(attribute) if record_class.respond_to?(:exposed_preference_name)) || attribute+ (record_class.exposed_preference_name(attribute) if record_class.respond_to?(:exposed_preference_name)) ||+ (record_class.signed_id_attribute_for(attribute) if record_class.respond_to?(:signed_id_attribute_for)) ||+ attributeend# Infer error code from contextdiff --git a/spree/api/app/controllers/concerns/spree/api/v3/file_uploads.rb b/spree/api/app/controllers/concerns/spree/api/v3/file_uploads.rbnew file mode 100644index 0000000000..264d20cd6e--- /dev/null+++ b/spree/api/app/controllers/concerns/spree/api/v3/file_uploads.rb@@ -0,0 +1,35 @@+module Spree+ module Api+ module V3+ # `POST /files`: accepts a file for the current store and returns the+ # opaque, expiring `signed_id` an endpoint that uses the file takes+ # (docs/plans/6.0-uploads-and-file-ownership.md).+ #+ # A JSON request carries the file's metadata and gets back a storage+ # target to send the bytes to; a multipart request carries the bytes in+ # its `file` part. Shared by the admin and seller branches: a file+ # stored here is attached to nothing, so what differs is only the gate+ # each branch puts in front of it, which stays on the including+ # controller as its `scoped_resource`.+ module FileUploads+ extend ActiveSupport::Concern++ def create+ file_upload = Spree::FileUpload.new(store: current_store, **file_upload_params)++ if file_upload.save+ render json: file_upload_serializer.new(file_upload, params: serializer_params).to_h, status: :created+ else+ render_validation_error(file_upload.errors)+ end+ end++ private++ def file_upload_params+ params.permit(:filename, :content_type, :byte_size, :checksum, :visibility, :file).to_h.symbolize_keys+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/concerns/spree/api/v3/orders/shipping_label_actions.rb b/spree/api/app/controllers/concerns/spree/api/v3/orders/shipping_label_actions.rbindex c8f97d24c1..10be259ec5 100644--- a/spree/api/app/controllers/concerns/spree/api/v3/orders/shipping_label_actions.rb+++ b/spree/api/app/controllers/concerns/spree/api/v3/orders/shipping_label_actions.rb@@ -18,9 +18,6 @@ module Spreeincluded doinclude ActiveStorage::SetCurrentinclude Spree::Api::V3::StreamsShippingLabel-- rescue_from ActiveSupport::MessageVerifier::InvalidSignature,- with: :render_invalid_signatureend# GET .../labels/:id/download@@ -84,7 +81,7 @@ module Spreeprivatedef label_permitted_keys- [:file, :tracking_number, :carrier, :service,+ [:file_signed_id, :tracking_number, :carrier, :service,:cost, :currency, :file_format, :tracking_url]end@@ -96,27 +93,19 @@ module Spree## Every key is passed whether or not the request carried it, so the# workflow sees a missing tracking number as a blank one to reject- # rather than a keyword it was never given.+ # rather than a keyword it was never given. The workflow takes any+ # attachable as `file`; the API names the reference `file_signed_id`.def record_uploaded_labelwith_order_lock doresult = Spree.shipping_label_record_workflow.call(owner: @parent,- **label_permitted_keys.index_with { |key| label_params[key] }+ file: label_params[:file_signed_id],+ **(label_permitted_keys - [:file_signed_id]).index_with { |key| label_params[key] })render_result(result, status: :created)endend-- # A tampered or expired direct-upload signature is a bad parameter,- # not a server fault.- def render_invalid_signature- render_error(- code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:parameter_invalid],- message: I18n.t('spree.shipping_labels.errors.file_required'),- status: :unprocessable_content- )- endendendenddiff --git a/spree/api/app/controllers/spree/api/v3/admin/categories_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/categories_controller.rbindex 5736b6d2b4..d327a6b782 100644--- a/spree/api/app/controllers/spree/api/v3/admin/categories_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/categories_controller.rb@@ -70,7 +70,7 @@ module Spree*model_additional_permitted_attributes,:name, :description, :permalink,:meta_title, :meta_description, :meta_keywords,- :image, :square_image,+ :image_signed_id, :square_image_signed_id,# Inline custom field values keyed by definition id. The model# setter (Spree::HasCustomFields#custom_fields=) validates each entry# against its definition. `value` is permitted as a scalar AND asdiff --git a/spree/api/app/controllers/spree/api/v3/admin/collections_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/collections_controller.rbindex 29030ddff9..7bac8773a9 100644--- a/spree/api/app/controllers/spree/api/v3/admin/collections_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/collections_controller.rb@@ -41,7 +41,7 @@ module Spreeparams.permit(:name, :description, :permalink, :position,:meta_title, :meta_description, :meta_keywords,- :image, :square_image,+ :image_signed_id, :square_image_signed_id,:automatic, :rules_match_policy, :sort_order,rules: [:id, :type, :value, :match_policy],# Inline custom field values keyed by definition id (seediff --git a/spree/api/app/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller.rbindex 67f3b5e4d9..4ce6b2fe47 100644--- a/spree/api/app/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller.rb@@ -14,9 +14,6 @@ module Spree# standard actions have to be listed alongside the custom ones.before_action :set_resource, only: [:show, :update, :destroy, :verify, :revoke, :download]- # A tampered signed id would otherwise surface as a 500.- rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_signature-# PATCH /api/v3/admin/companies/:company_id/tax_exemption_certificates/:id/verifydef verifyresult = Spree.tax_exemption_certificate_verify_workflow.call(@@ -88,11 +85,10 @@ module Spree[{ document_attachment: :blob }]end- # `document` is an ActiveStorage signed blob id from- # POST /api/v3/admin/direct_uploads.+ # `document_signed_id` comes from POST /api/v3/admin/files.def permitted_paramsparams.permit(:certificate_number, :reason_code, :issuing_authority,- :issued_at, :expires_at, :country_code, :state_code, :document,+ :issued_at, :expires_at, :country_code, :state_code, :document_signed_id,metadata: {})end@@ -111,16 +107,6 @@ module Spreeauthorize!(mapped, resource)end-- private-- def render_invalid_signature- render_error(- code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],- message: 'Invalid document signed id',- status: :unprocessable_content- )- endendendenddiff --git a/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rbindex ea55073ff8..50f0e2e718 100644--- a/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rb@@ -262,7 +262,7 @@ module Spree*model_additional_permitted_attributes,:email, :first_name, :last_name, :phone,:password, :password_confirmation, :selected_locale,- :avatar, :accepts_email_marketing, :internal_note,+ :avatar_signed_id, :accepts_email_marketing, :internal_note,metadata: {}, tags: [], customer_group_ids: [])enddiff --git a/spree/api/app/controllers/spree/api/v3/admin/direct_uploads_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/direct_uploads_controller.rbdeleted file mode 100644index bd8b24b754..0000000000--- a/spree/api/app/controllers/spree/api/v3/admin/direct_uploads_controller.rb+++ /dev/null@@ -1,54 +0,0 @@-module Spree- module Api- module V3- module Admin- class DirectUploadsController < Admin::BaseController- include Spree::Api::V3::DirectUploads-- # Direct uploads is a write-adjacent presigning helper: callers exchange- # blob metadata for an upload URL, then reference the resulting- # signed_id when creating/updating a resource (product media, customer- # avatar, etc). The narrowest scope it can map to is `write_products`- # since that covers the dominant upload flow (product/variant media).- # Other admin-write flows that take signed_ids (e.g. customer avatar)- # already require the relevant `write_<resource>` scope on the- # subsequent PATCH, so this gate is the floor, not the only check.- scoped_resource :products-- skip_before_action :authenticate_user-- # POST /api/v3/admin/direct_uploads- #- # Overrides the shared concern's create to select the storage service:- # digital assets must land on private storage up front, since attaching- # a signed id never moves a blob between services.- def create- blob = ActiveStorage::Blob.create_before_direct_upload!(service_name: storage_service_name, **blob_params)-- render json: {- direct_upload: {- url: blob.service_url_for_direct_upload,- headers: blob.service_headers_for_direct_upload- },- signed_id: blob.signed_id- }, status: :created- end-- private-- # Attaching a signed id never moves the blob between services, so a- # file destined for a private attachment has to be uploaded to the- # private service up front. `private: true` asks for that; everything- # else keeps landing on the public service as before.- def storage_service_name- if params[:private].to_b- Spree.private_storage_service_name- else- Spree.public_storage_service_name- end- end- end- end- end- end-enddiff --git a/spree/api/app/controllers/spree/api/v3/admin/files_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/files_controller.rbnew file mode 100644index 0000000000..e871db665e--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/admin/files_controller.rb@@ -0,0 +1,24 @@+module Spree+ module Api+ module V3+ module Admin+ class FilesController < Admin::BaseController+ include Spree::Api::V3::FileUploads++ # The endpoint that uses a file checks its own scope (`write_customers`+ # for an avatar, and so on), so this gate is the floor, not the only+ # check. `write_products` covers the dominant flow, product media.+ scoped_resource :products++ skip_before_action :authenticate_user++ private++ def file_upload_serializer+ Spree.api.admin_file_upload_serializer+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/spree/api/v3/admin/imports_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/imports_controller.rbindex c45491b214..a46c19b28a 100644--- a/spree/api/app/controllers/spree/api/v3/admin/imports_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/imports_controller.rb@@ -23,8 +23,8 @@ module Spree# POST /api/v3/admin/imports#- # `attachment` is an ActiveStorage signed blob id obtained from- # POST /api/v3/admin/direct_uploads. On success the import advances+ # `attachment_signed_id` is a signed id obtained from+ # POST /api/v3/admin/files. On success the import advances# straight into `mapping` (auto-assigning file columns from the CSV# headers), so the response already carries the mapping payload.def create@@ -52,12 +52,6 @@ module Spreeelserender_errors(@resource.errors)end- rescue ActiveSupport::MessageVerifier::InvalidSignature- render_error(- code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],- message: 'Invalid attachment signed id',- status: :unprocessable_content- )end# PATCH /api/v3/admin/imports/:id/complete_mapping@@ -263,7 +257,7 @@ module Spreeenddef permitted_params- params.permit(*model_additional_permitted_attributes, :type, :attachment, :delimiter, :results_url, :price_list_id)+ params.permit(*model_additional_permitted_attributes, :type, :attachment_signed_id, :delimiter, :results_url, :price_list_id)end# A price-list import writes into one list, named by its prefixed id.diff --git a/spree/api/app/controllers/spree/api/v3/admin/me_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/me_controller.rbindex a4f66175fc..6b0d885f32 100644--- a/spree/api/app/controllers/spree/api/v3/admin/me_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/me_controller.rb@@ -33,8 +33,8 @@ module Spree# name, admin UI language, and avatar) — it operates on `current_user`# directly, so it needs no per-record authorization. Distinct from# PATCH /admin_users/:id, which is store-scoped staff management of- # *other* users. `avatar` accepts an ActiveStorage direct-upload- # signed id to set the photo, or `null` to remove it.+ # *other* users. `avatar_signed_id` takes a signed id from+ # POST /files to set the photo, or `null` to remove it.def updateif current_user.update(permitted_params)render json: me_response@@ -70,7 +70,7 @@ module Spreeenddef permitted_params- params.permit(:selected_locale, :first_name, :last_name, :avatar)+ params.permit(:selected_locale, :first_name, :last_name, :avatar_signed_id)enddef me_responsediff --git a/spree/api/app/controllers/spree/api/v3/admin/option_types_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/option_types_controller.rbindex a8f52f6c4e..8660caaf49 100644--- a/spree/api/app/controllers/spree/api/v3/admin/option_types_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/option_types_controller.rb@@ -24,7 +24,7 @@ module Spree*model_additional_permitted_attributes,:name, :label, :position, :filterable, :kind,option_values: [- :id, :name, :label, :position, :color_code, :image+ :id, :name, :label, :position, :color_code, :image_signed_id])enddiff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/labels_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/labels_controller.rbindex cc17ce5536..b950b54d27 100644--- a/spree/api/app/controllers/spree/api/v3/admin/orders/labels_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/labels_controller.rb@@ -15,12 +15,16 @@ module Spree# POST .../labels#- # Buys the label through the parcel's provider, or — when a `file`+ # Buys the label through the parcel's provider, or — when a `file_signed_id`# is given — records one the merchant bought elsewhere.def createauthorize!(:create, Spree::ShippingLabel)- return record_uploaded_label if label_params[:file].present?+ return record_uploaded_label if label_params[:file_signed_id].present?+ # Buying is the default only when no file is sent at all. A file+ # under its old name would otherwise fall through to buying a+ # label on the carrier account.+ return render_misnamed_label_file if params.key?(:file)with_order_lock doresult = Spree.shipping_label_purchase_workflow.call(owner: @parent)@@ -59,6 +63,16 @@ module Spree@order.fulfillments.find_by_prefix_id!(params[:fulfillment_id])endend++ private++ def render_misnamed_label_file+ render_error(+ code: ERROR_CODES[:parameter_invalid],+ message: I18n.t('spree.shipping_labels.errors.file_renamed'),+ status: :unprocessable_content+ )+ endendendenddiff --git a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rbindex 661faaa5b8..bb00f47b9c 100644--- a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb@@ -7,12 +7,9 @@ module Spreescoped_resource :orders- # The order accepts a `po_document` signed blob id and streams it back.+ # The order accepts a `po_document_signed_id` and streams it back.include ActiveStorage::SetCurrent- # A tampered signed id would otherwise surface as a 500.- rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_po_document-skip_before_action :set_resource, only: [:index, :create]before_action :set_resource, only: [:show, :update, :destroy, :complete, :cancel, :approve, :resend_confirmation, :resend_digital_links, :po_document]@@ -244,14 +241,6 @@ module Spreeprivate- def render_invalid_po_document- render_error(- code: ERROR_CODES[:validation_error],- message: I18n.t('spree.po_document_invalid_signed_id'),- status: :unprocessable_content- )- end-def resolve_customercustomer_param = params[:customer_id].presencereturn unless customer_param@@ -279,7 +268,7 @@ module Spree# The buyer's own purchase-order reference, and the signed blob# id of the document behind it — a PO arriving by email and# keyed in is the draft-order flow plus these two fields.- :po_number, :po_document,+ :po_number, :po_document_signed_id,:shipping_address_id, :billing_address_id,:preferred_stock_location_id, :company_id,:coupon_code,@@ -298,7 +287,7 @@ module Spreeparams.permit(:email, :customer_id,:customer_note, :internal_note,- :po_number, :po_document,+ :po_number, :po_document_signed_id,:currency, :locale, :market_id, :channel_id,:preferred_stock_location_id, :company_id,metadata: {},diff --git a/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rbindex d9f232c13a..74d8283090 100644--- a/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/sellers_controller.rb@@ -140,7 +140,7 @@ module Spreedef permitted_paramsnormalize_params(params.permit(:name, :slug, :contact_email, :billing_email, :about,- :logo, :square_logo, :cover_photo,+ :logo_signed_id, :square_logo_signed_id, :cover_photo_signed_id,:tax_remittance, :payouts_schedule_interval, :minimum_payout_amount,:holiday_mode_until,:legal_name, :registration_number,diff --git a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rbindex 53a70aaaba..20d591aa5e 100644--- a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb@@ -125,7 +125,8 @@ module Spree:email_text_color,:email_heading_color,:email_font,- :mailer_logo+ :logo_signed_id,+ :mailer_logo_signed_id)endenddiff --git a/spree/api/app/controllers/spree/api/v3/seller/direct_uploads_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/direct_uploads_controller.rbdeleted file mode 100644index 27ee184bd3..0000000000--- a/spree/api/app/controllers/spree/api/v3/seller/direct_uploads_controller.rb+++ /dev/null@@ -1,21 +0,0 @@-module Spree- module Api- module V3- module Seller- # Presigning for a seller's own uploads — today the documents their- # onboarding asks for.- #- # A blob created here is not attached to anything yet: it becomes a- # submission only when the seller posts its signed id, and that- # endpoint is the one that checks the requirement is theirs. So the- # narrowest meaningful gate is the seller's own profile, which every- # member of a seller's team holds.- class DirectUploadsController < Seller::BaseController- include Spree::Api::V3::DirectUploads-- scoped_resource :seller_profile- end- end- end- end-enddiff --git a/spree/api/app/controllers/spree/api/v3/seller/files_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/files_controller.rbnew file mode 100644index 0000000000..11cbd385ae--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/seller/files_controller.rb@@ -0,0 +1,23 @@+module Spree+ module Api+ module V3+ module Seller+ # A file stored here is attached to nothing until the seller sends its+ # `signed_id` to an endpoint that checks the target is theirs, so the+ # narrowest meaningful gate is the seller's own profile, which every+ # member of a seller's team holds.+ class FilesController < Seller::BaseController+ include Spree::Api::V3::FileUploads++ scoped_resource :seller_profile++ private++ def file_upload_serializer+ Spree.api.seller_file_upload_serializer+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/spree/api/v3/seller/imports_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/imports_controller.rbindex a43f160d4d..8aeed67139 100644--- a/spree/api/app/controllers/spree/api/v3/seller/imports_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/imports_controller.rb@@ -38,8 +38,8 @@ module Spree# POST /api/v3/seller/imports#- # `attachment` is an ActiveStorage signed blob id from- # POST /api/v3/seller/direct_uploads. On success the import is+ # `attachment_signed_id` is a signed id from+ # POST /api/v3/seller/files. On success the import is# already in `mapping`, carrying the auto-assigned columns.def create@resource = build_resource@@ -63,12 +63,6 @@ module Spreeelserender_errors(@resource.errors)end- rescue ActiveSupport::MessageVerifier::InvalidSignature- render_error(- code: Spree::Api::V3::ErrorHandler::ERROR_CODES[:validation_error],- message: 'Invalid attachment signed id',- status: :unprocessable_content- )end# PATCH /api/v3/seller/imports/:id/complete_mapping@@ -252,7 +246,7 @@ module Spreeenddef permitted_params- params.permit(*model_additional_permitted_attributes, :type, :attachment, :delimiter, :results_url)+ params.permit(*model_additional_permitted_attributes, :type, :attachment_signed_id, :delimiter, :results_url)end# The registered Import subclass matching `name`, or nil.diff --git a/spree/api/app/controllers/spree/api/v3/seller/me_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/me_controller.rbindex 07a2826ad3..ab25d32b28 100644--- a/spree/api/app/controllers/spree/api/v3/seller/me_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/me_controller.rb@@ -27,8 +27,8 @@ module Spree# seller they are acting for.## Distinct from PATCH /profile, which writes the seller business.- # `avatar` accepts an ActiveStorage direct-upload signed id to set- # the photo, or `null` to remove it.+ # `avatar_signed_id` takes a signed id from POST /files to set the+ # photo, or `null` to remove it.def updateif current_user.update(permitted_params)render json: me_response@@ -40,7 +40,7 @@ module Spreeprivatedef permitted_params- params.permit(:selected_locale, :first_name, :last_name, :avatar)+ params.permit(:selected_locale, :first_name, :last_name, :avatar_signed_id)enddef me_responsediff --git a/spree/api/app/controllers/spree/api/v3/seller/orders/labels_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/orders/labels_controller.rbindex e1272ad0e2..406df63778 100644--- a/spree/api/app/controllers/spree/api/v3/seller/orders/labels_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/orders/labels_controller.rb@@ -24,7 +24,7 @@ module Spreedef createauthorize!(:create, Spree::ShippingLabel)- if label_params[:file].blank?+ if label_params[:file_signed_id].blank?return render_error(code: ERROR_CODES[:validation_error],message: I18n.t('spree.shipping_labels.errors.file_required'),diff --git a/spree/api/app/controllers/spree/api/v3/seller/profile_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/profile_controller.rbindex a02c1f2493..d190a46de2 100644--- a/spree/api/app/controllers/spree/api/v3/seller/profile_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/profile_controller.rb@@ -107,7 +107,7 @@ module Spreenormalize_params(params.permit(:name, :contact_email, :billing_email, :about,:legal_name, :registration_number,- :logo, :square_logo, :cover_photo,+ :logo_signed_id, :square_logo_signed_id, :cover_photo_signed_id,billing_address: Spree::Api::V3::AddressParams::ADDRESS_KEYS,custom_fields: [:id, :custom_field_definition_id, :value,{ value: [] }, { value: {} }])diff --git a/spree/api/app/controllers/spree/api/v3/seller/requirement_submissions_controller.rb b/spree/api/app/controllers/spree/api/v3/seller/requirement_submissions_controller.rbindex 00b8fc0f93..c0a627089e 100644--- a/spree/api/app/controllers/spree/api/v3/seller/requirement_submissions_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/seller/requirement_submissions_controller.rb@@ -24,7 +24,7 @@ module Spreerequirement: @requirement,note: attributes[:note],reference: attributes[:reference],- file: attributes[:file],+ file: attributes[:file_signed_id],submitted_by: try_spree_current_user)@@ -57,11 +57,11 @@ module Spreeprotected- # What a seller may say about a requirement. `file` is a direct-upload- # signed id, so it is a string like the rest — the bytes are already- # in storage by the time this runs.+ # What a seller may say about a requirement. `file_signed_id` comes+ # from POST /files, so the bytes are already in storage by the time+ # this runs.def permitted_params- params.permit(:note, :reference, :file)+ params.permit(:note, :reference, :file_signed_id)enddef read_actionsdiff --git a/spree/api/app/controllers/spree/api/v3/store/carts/po_documents_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts/po_documents_controller.rbindex 79cd9cfcb0..cfa0cf9334 100644--- a/spree/api/app/controllers/spree/api/v3/store/carts/po_documents_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/store/carts/po_documents_controller.rb@@ -12,7 +12,7 @@ module Spree# unconditional presigner would let anyone holding one mint blobs in# the merchant's bucket. Reaching this action means holding the cart.#- # Blobs are minted on private storage, because attaching a signed id+ # Files are minted on private storage, because attaching a signed id# never moves a blob between services and a purchase order carries the# buyer's prices, terms and internal cost codes.class PoDocumentsController < Store::BaseController@@ -23,8 +23,9 @@ module Spree# POST /api/v3/store/carts/:cart_id/po_document#- # Exchanges blob metadata for an upload URL. The returned signed id- # is then sent back as `po_document` on a cart update, which is what+ # Takes the same flat request as the Admin API's `POST /files` and+ # answers with the same shape. The returned signed id is then sent+ # back as `po_document_signed_id` on a cart update, which is what# actually attaches it.## The declared size and type are checked here, before any URL is@@ -34,20 +35,20 @@ module Spree# only runs once the bytes are already stored. It is a gate on the# cheap lie, not a substitute: the attach-time check still reads# the stored object, which is what catches an under-declared size.+ # Bytes in the request itself are not accepted here: a publishable+ # key is public.def create- return render_po_document_invalid unless acceptable_upload?-- blob = ActiveStorage::Blob.create_before_direct_upload!(- service_name: Spree.private_storage_service_name, **blob_params+ file_upload = Spree::FileUpload.new(+ store: current_store,+ visibility: 'private',+ max_byte_size: Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE,+ allowed_content_types: Spree::Purchase::PurchaseOrder::PO_DOCUMENT_CONTENT_TYPES,+ **params.permit(:filename, :content_type, :byte_size, :checksum).to_h.symbolize_keys)- render json: {- direct_upload: {- url: blob.service_url_for_direct_upload,- headers: blob.service_headers_for_direct_upload- },- signed_id: blob.signed_id- }, status: :created+ return render_po_document_invalid unless file_upload.save++ render json: Spree.api.file_upload_serializer.new(file_upload, params: serializer_params).to_h, status: :createdend# GET /api/v3/store/carts/:cart_id/po_document@@ -79,18 +80,6 @@ module Spreeprivate- def blob_params- params.require(:blob).permit(:filename, :byte_size, :checksum, :content_type).to_h.symbolize_keys- end-- def acceptable_upload?- declared_size = Integer(blob_params[:byte_size].to_s, exception: false)-- declared_size&.positive? &&- declared_size <= Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE &&- Spree::Purchase::PurchaseOrder::PO_DOCUMENT_CONTENT_TYPES.include?(blob_params[:content_type])- end-def render_po_document_invalidrender_error(code: ERROR_CODES[:parameter_invalid],diff --git a/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb b/spree/api/app/controllers/spree/api/v3/store/carts_controller.rbindex f20551e8f0..5868923a7a 100644--- a/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/store/carts_controller.rb@@ -5,12 +5,9 @@ module Spreeclass CartsController < Store::ResourceControllerinclude Spree::Api::V3::CartResolvableinclude Spree::Api::V3::OrderLock- # The cart accepts a `po_document` signed blob id.+ # The cart accepts a `po_document_signed_id`.include ActiveStorage::SetCurrent- # A tampered signed id would otherwise surface as a 500.- rescue_from ActiveSupport::MessageVerifier::InvalidSignature, with: :render_invalid_po_document-skip_before_action :set_resourceprepend_before_action :require_authentication!, only: [:index, :associate]@@ -184,14 +181,6 @@ module Spreeprivate- def render_invalid_po_document- render_error(- code: ERROR_CODES[:validation_error],- message: I18n.t('spree.po_document_invalid_signed_id'),- status: :unprocessable_content- )- end-def permitted_paramsparams.permit(*model_additional_permitted_attributes,@@ -207,7 +196,7 @@ module Spree# The buyer's own purchase-order reference, and the signed blob id# of the document behind it (from POST .../carts/:id/po_document).:po_number,- :po_document,+ :po_document_signed_id,:use_shipping,shipping_address: address_params,billing_address: address_params,diff --git a/spree/api/app/serializers/spree/api/v3/admin/file_upload_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/file_upload_serializer.rbnew file mode 100644index 0000000000..8f00587306--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/admin/file_upload_serializer.rb@@ -0,0 +1,11 @@+module Spree+ module Api+ module V3+ module Admin+ class FileUploadSerializer < V3::FileUploadSerializer+ one :upload_target, key: :upload, resource: proc { Spree.api.admin_file_upload_target_serializer }+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/file_upload_target_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/file_upload_target_serializer.rbnew file mode 100644index 0000000000..ef47e336cc--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/admin/file_upload_target_serializer.rb@@ -0,0 +1,10 @@+module Spree+ module Api+ module V3+ module Admin+ class FileUploadTargetSerializer < V3::FileUploadTargetSerializer+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rbindex 0cccb2a449..3eab68c02c 100644--- a/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/media_serializer.rb@@ -52,9 +52,10 @@ module Spree# (a category image, a store logo) accepts on write. Handing it over# lets those fields adopt a library file, sharing the blob instead of# uploading a second copy — the same economics as placing media on a- # product, through endpoints that need no change.+ # product, through endpoints that need no change. Minted fresh, with+ # the same expiry as an upload, on every read.attribute :signed_id do |asset|- asset.attachment_blob&.signed_id+ Spree::Uploads.signed_id_for(asset.attachment_blob) if asset.attachment_blobendprefixed_id_attributes :viewablediff --git a/spree/api/app/serializers/spree/api/v3/file_upload_serializer.rb b/spree/api/app/serializers/spree/api/v3/file_upload_serializer.rbnew file mode 100644index 0000000000..e30c506198--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/file_upload_serializer.rb@@ -0,0 +1,28 @@+module Spree+ module Api+ module V3+ # A file accepted by an upload endpoint ({Spree::FileUpload}).+ #+ # `signed_id` is opaque: clients pass it back unchanged to the endpoint+ # that uses the file and never parse it. It stops being attachable at+ # `expires_at`. `upload` is where a presigned upload sends its bytes, and+ # null once the file is already stored.+ class FileUploadSerializer < BaseSerializer+ # A value object, not a record — it has no id of its own.+ _attributes.delete(:id)++ typelize signed_id: :string,+ filename: :string,+ content_type: :string,+ byte_size: :number,+ visibility: [:string, enum: Spree::FileUpload::VISIBILITIES],+ expires_at: :string,+ upload: [:FileUploadTarget, nullable: true]++ attributes :signed_id, :filename, :content_type, :byte_size, :visibility, expires_at: :iso8601++ one :upload_target, key: :upload, resource: proc { Spree.api.file_upload_target_serializer }+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/file_upload_target_serializer.rb b/spree/api/app/serializers/spree/api/v3/file_upload_target_serializer.rbnew file mode 100644index 0000000000..d2488a4220--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/file_upload_target_serializer.rb@@ -0,0 +1,17 @@+module Spree+ module Api+ module V3+ # Where a presigned upload sends its bytes. Clients send them with+ # `method` to `url` carrying exactly `headers`, and treat all three as+ # opaque: the storage service decides them.+ class FileUploadTargetSerializer < BaseSerializer+ _attributes.delete(:id)++ typelize method: :string, url: :string, headers: 'Record<string, string>'++ attribute :method, &:http_method+ attributes :url, :headers+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/seller/file_upload_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/file_upload_serializer.rbnew file mode 100644index 0000000000..7324abe54d--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/seller/file_upload_serializer.rb@@ -0,0 +1,11 @@+module Spree+ module Api+ module V3+ module Seller+ class FileUploadSerializer < V3::FileUploadSerializer+ one :upload_target, key: :upload, resource: proc { Spree.api.seller_file_upload_target_serializer }+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/seller/file_upload_target_serializer.rb b/spree/api/app/serializers/spree/api/v3/seller/file_upload_target_serializer.rbnew file mode 100644index 0000000000..a1aed159ae--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/seller/file_upload_target_serializer.rb@@ -0,0 +1,10 @@+module Spree+ module Api+ module V3+ module Seller+ class FileUploadTargetSerializer < V3::FileUploadTargetSerializer+ end+ end+ end+ end+enddiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex ad05846dcb..3e16217ac5 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -299,8 +299,8 @@ Spree::Core::Engine.add_routes doresources :roles, only: [:index, :show, :create, :update, :destroy]resources :permissions, only: [:index]- # Direct Uploads (Active Storage)- resources :direct_uploads, only: [:create]+ # File uploads — see docs/plans/6.0-uploads-and-file-ownership.md+ resources :files, only: [:create]# CSV Exports — see docs/plans/5.5-admin-spa-csv-export.mdresources :exports, only: [:index, :show, :create, :destroy] do@@ -961,7 +961,7 @@ Spree::Core::Engine.add_routes do# Registry data — which carriers a tracking number can be pinned to.resources :tracking_carriers, only: [:index]- resources :direct_uploads, only: [:create]+ resources :files, only: [:create]# CSV of what this seller sold, or of their catalogue. Created, polled# and downloaded — no index, since a seller has no history page todiff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex cb5eba8b13..d9a48384de 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -18,7 +18,7 @@ module Spreeproduct_filter_sort_option media_event return return_line_item exchange exchange_line_item claimclaim_line_item return_reason claim_reason digital_asset export gift_card_batch import import_rowinvitation newsletter_subscriber promotion refund stock_level stock_movement stock_reservation- stock_transfer company company_membership company_invitation seller].freeze+ stock_transfer company company_membership company_invitation seller file_upload file_upload_target].freezeADMIN_SERIALIZERS =%i[country state applied_promotion discount tax_line cart delivery_zone delivery_profile@@ -42,7 +42,7 @@ module Spreeinvitation_acceptance_link role permission export saved_report import import_row import_mapping promotionpromotion_action promotion_rule coupon_code price_adjustment_tier price_list price_ruleresource_translations email_template email_template_draft email_template_revision email_template_preview- email_template_sample_record].freeze+ email_template_sample_record file_upload file_upload_target].freezeSELLER_SERIALIZERS =%i[profile policy team_member account invitation invitation_acceptance_link product product_type@@ -50,7 +50,8 @@ module Spreeorder_line_item fulfillment fulfillment_item delivery delivery_rate shipping_label returnreturn_line_item exchange exchange_line_item claim claim_line_item reason package_type stock_locationrequirement_custom_field tax_identifier requirement_status import import_row import_mapping- requirement_submission export transfer payout balance payment_split price price_history].freeze+ requirement_submission export transfer payout balance payment_split price price_history file_upload+ file_upload_target].freezeINJECTION_POINTS_WITH_DEFAULTS = {**STORE_SERIALIZERS.to_h { |name| [:"#{name}_serializer", "Spree::Api::V3::#{name.to_s.camelize}Serializer"] },diff --git a/spree/api/lib/spree/api/middleware/request_size_limit.rb b/spree/api/lib/spree/api/middleware/request_size_limit.rbindex 2a67b404fa..c674843be7 100644--- a/spree/api/lib/spree/api/middleware/request_size_limit.rb+++ b/spree/api/lib/spree/api/middleware/request_size_limit.rb@@ -2,13 +2,24 @@ module Spreemodule Apimodule Middlewareclass RequestSizeLimit+ # `POST /files` takes a file's bytes in the request itself, so it is+ # held to the multipart upload limit instead, plus room for the other+ # form fields.+ FILE_UPLOAD_PATH = %r{\A/api/v3/(admin|seller)/files/?\z}+ MULTIPART_ENVELOPE = 64.kilobytes+def initialize(app, limit: nil)@app = app@limit = limitenddef call(env)- if api_request?(env) && content_length_exceeded?(env)+ if file_upload?(env) && chunked?(env)+ # A chunked body has no length to check here, and these bytes pass+ # through the application.+ body = { error: { code: 'request_too_large', message: 'Send the file with a Content-Length header' } }+ [411, { 'Content-Type' => 'application/json' }, [body.to_json]]+ elsif api_request?(env) && content_length_exceeded?(env)body = { error: { code: 'request_too_large', message: 'Request body too large' } }[413, { 'Content-Type' => 'application/json' }, [body.to_json]]else@@ -24,12 +35,22 @@ module Spreedef content_length_exceeded?(env)content_length = env['CONTENT_LENGTH'].to_i- content_length > max_body_size+ content_length > max_body_size(env)end- def max_body_size+ def max_body_size(env)+ return Spree::Config[:max_multipart_upload_size] + MULTIPART_ENVELOPE if file_upload?(env)+@limit || Spree::Api::Config[:max_request_body_size]end++ def chunked?(env)+ env['CONTENT_LENGTH'].nil? && env['HTTP_TRANSFER_ENCODING'].to_s.include?('chunked')+ end++ def file_upload?(env)+ env['REQUEST_METHOD'] == 'POST' && FILE_UPLOAD_PATH.match?(env['PATH_INFO'])+ endendendenddiff --git a/spree/api/lib/spree/api/openapi/schema_helper.rb b/spree/api/lib/spree/api/openapi/schema_helper.rbindex a76515bf15..ecdde3d196 100644--- a/spree/api/lib/spree/api/openapi/schema_helper.rb+++ b/spree/api/lib/spree/api/openapi/schema_helper.rb@@ -388,22 +388,6 @@ module Spree},required: %w[iso iso3 name]},- DirectUploadResponse: {- type: :object,- description: 'A presigned upload target. PUT the file to `direct_upload.url` with the given headers, then send `signed_id` as the submission\'s `file`.',- properties: {- signed_id: { type: :string, description: 'Send this as a submission\'s `file`', example: 'eyJfcmFpbHMiOnsibWVzc2FnZSI6...' },- direct_upload: {- type: :object,- properties: {- url: { type: :string, example: 'https://storage.example.com/uploads/abc123' },- headers: { type: :object, additionalProperties: { type: :string } }- },- required: %w[url headers]- }- },- required: %w[signed_id direct_upload]- },AuthProvidersResponse: {type: :object,description: 'Sign-in methods this marketplace offers sellers, for the login page',diff --git a/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rbindex b5fc9ce602..50b36273c8 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rb@@ -105,7 +105,7 @@ RSpec.describe Spree::Api::V3::Admin::CategoriesController, type: :controller doimaged = create(:category, :with_header_image)expect(imaged.reload.image).to be_attached- patch :update, params: { id: imaged.prefixed_id, image: nil }, as: :json+ patch :update, params: { id: imaged.prefixed_id, image_signed_id: nil }, as: :jsonexpect(response).to have_http_status(:ok)expect(imaged.reload.image).not_to be_attacheddiff --git a/spree/api/spec/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller_spec.rbindex efad47584a..537b467463 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/companies/tax_exemption_certificates_controller_spec.rb@@ -86,11 +86,11 @@ RSpec.describe Spree::Api::V3::Admin::Companies::TaxExemptionCertificatesControlexpect(response).to have_http_status(:unprocessable_content)end- it 'attaches a document from a direct upload' do+ it 'attaches an uploaded document' dopost :create, params: {company_id: company.prefixed_id,certificate_number: 'DE-1', reason_code: 'resale',- document: pdf_blob.signed_id+ document_signed_id: pdf_blob.signed_id}, as: :jsonexpect(response).to have_http_status(:created)@@ -98,14 +98,27 @@ RSpec.describe Spree::Api::V3::Admin::Companies::TaxExemptionCertificatesControlexpect(company.tax_exemption_certificates.sole.document).to be_attachedend- # Without the rescue this is a 500.+ it 'reports a document stored with the wrong visibility under the field it was sent as' do+ public_blob = ActiveStorage::Blob.create_and_upload!(io: StringIO.new('%PDF-1.4'), filename: 'resale.pdf',+ content_type: 'application/pdf', service_name: 'local')++ post :create, params: {+ company_id: company.prefixed_id,+ certificate_number: 'DE-1', reason_code: 'resale',+ document_signed_id: public_blob.signed_id+ }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['details']).to have_key('document_signed_id')+ end+# The URL has to be our own streaming endpoint, not a storage link — that is# what makes admin credentials apply to every read of a confidential document.it 'points the document at the download endpoint' dopost :create, params: {company_id: company.prefixed_id,certificate_number: 'DE-1', reason_code: 'resale',- document: pdf_blob.signed_id+ document_signed_id: pdf_blob.signed_id}, as: :jsoncertificate = company.tax_exemption_certificates.sole@@ -128,7 +141,7 @@ RSpec.describe Spree::Api::V3::Admin::Companies::TaxExemptionCertificatesControlpost :create, params: {company_id: company.prefixed_id,certificate_number: 'DE-1', reason_code: 'resale',- document: 'not-a-real-signed-id'+ document_signed_id: 'not-a-real-signed-id'}, as: :jsonexpect(response).to have_http_status(:unprocessable_content)diff --git a/spree/api/spec/controllers/spree/api/v3/admin/direct_uploads_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/direct_uploads_controller_spec.rbdeleted file mode 100644index ecb7eea7cc..0000000000--- a/spree/api/spec/controllers/spree/api/v3/admin/direct_uploads_controller_spec.rb+++ /dev/null@@ -1,41 +0,0 @@-require 'spec_helper'--RSpec.describe Spree::Api::V3::Admin::DirectUploadsController, type: :controller do- render_views-- include_context 'API v3 Admin authenticated'-- describe 'POST #create' do- before { request.headers.merge!(headers) }-- let(:blob_params) do- {- blob: {- filename: 'test-image.jpg',- byte_size: 1024,- checksum: 'dGVzdA==',- content_type: 'image/jpeg'- }- }- end-- it 'creates a direct upload and returns presigned URL' do- post :create, params: blob_params, as: :json-- expect(response).to have_http_status(:created)- expect(json_response['signed_id']).to be_present- expect(json_response['direct_upload']).to be_present- expect(json_response['direct_upload']['url']).to be_present- expect(json_response['direct_upload']['headers']).to be_a(Hash)- end-- context 'without API key' do- let(:headers) { {} }-- it 'returns unauthorized' do- post :create, params: blob_params, as: :json- expect(response).to have_http_status(:unauthorized)- end- end- end-enddiff --git a/spree/api/spec/controllers/spree/api/v3/admin/files_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/files_controller_spec.rbnew file mode 100644index 0000000000..4abb3fc4e8--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/admin/files_controller_spec.rb@@ -0,0 +1,103 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Admin::FilesController, type: :controller do+ render_views++ include_context 'API v3 Admin authenticated'++ before { request.headers.merge!(headers) }++ describe 'POST #create' do+ let(:presigned_params) do+ { filename: 'photo.jpg', byte_size: 1024, checksum: Digest::MD5.base64digest('photo'), content_type: 'image/jpeg' }+ end+ let(:image) { Rack::Test::UploadedFile.new(Spree::Core::Engine.root.join('spec/fixtures/thinking-cat.jpg'), 'image/jpeg') }++ def uploaded_blob+ ActiveStorage::Blob.find_signed!(json_response['signed_id'])+ end++ it 'reserves a file on public storage and returns where to send the bytes' do+ post :create, params: presigned_params, as: :json++ expect(response).to have_http_status(:created)+ expect(json_response).to include('filename' => 'photo.jpg', 'byte_size' => 1024, 'visibility' => 'public')+ expect(json_response['upload']).to include('method' => 'PUT', 'url' => be_present, 'headers' => be_a(Hash))+ expect(Time.zone.parse(json_response['expires_at'])).to be_within(1.minute).of(1.day.from_now)+ expect(uploaded_blob.store_id).to eq(store.id)+ expect(uploaded_blob.service_name).to eq(Spree.public_storage_service_name.to_s)+ end++ it 'puts a private upload on private storage, whatever its type' do+ post :create, params: presigned_params.merge(filename: 'book.epub', content_type: 'application/epub+zip', visibility: 'private'), as: :json++ expect(response).to have_http_status(:created)+ expect(uploaded_blob.service_name).to eq(Spree.private_storage_service_name.to_s)+ end++ it 'stores the bytes of a multipart upload and reads their type from the content' do+ post :create, params: { file: image, content_type: 'text/plain' }++ expect(response).to have_http_status(:created)+ expect(json_response['upload']).to be_nil+ expect(json_response).to include('filename' => 'thinking-cat.jpg', 'content_type' => 'image/jpeg')+ expect(uploaded_blob.store_id).to eq(store.id)+ expect(uploaded_blob.byte_size).to eq(File.size(image.path))+ expect(uploaded_blob.service.exist?(uploaded_blob.key)).to be(true)+ end++ it 'refuses a public upload of a type customers should not be served' do+ post :create, params: presigned_params.merge(filename: 'run.sh', content_type: 'application/x-sh'), as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['details']).to have_key('content_type')+ end++ it 'refuses a presigned upload over the size limit' do+ allow(Spree::Config).to receive(:max_upload_size).and_return(1000)++ post :create, params: presigned_params, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['details']).to have_key('byte_size')+ end++ it 'holds a multipart upload to its own, lower limit' do+ allow(Spree::Config).to receive(:max_multipart_upload_size).and_return(100)++ post :create, params: { file: image }++ expect(response).to have_http_status(:unprocessable_content)+ expect(ActiveStorage::Blob.count).to eq(0)+ end++ it 'refuses an unknown visibility' do+ post :create, params: presigned_params.merge(visibility: 'secret'), as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['details']).to have_key('visibility')+ end++ it 'treats a file that is not a file as a presigned upload missing its checksum' do+ post :create, params: { file: 'abc', filename: 'a.png', content_type: 'image/png', byte_size: 3 }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['details']).to have_key('checksum')+ end++ it 'requires a checksum for a presigned upload' do+ post :create, params: presigned_params.except(:checksum), as: :json++ expect(response).to have_http_status(:unprocessable_content)+ end++ context 'without API key' do+ let(:headers) { {} }++ it 'returns unauthorized' do+ post :create, params: presigned_params, as: :json+ expect(response).to have_http_status(:unauthorized)+ end+ end+ end+enddiff --git a/spree/api/spec/controllers/spree/api/v3/admin/imports_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/imports_controller_spec.rbindex f36779c74d..011da106ce 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/imports_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/imports_controller_spec.rb@@ -73,7 +73,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller dopost :create,params: {type: 'products',- attachment: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n")+ attachment_signed_id: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n")},as: :json}.to change(Spree::Import, :count).by(1)@@ -102,7 +102,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller doparams: {type: 'products',delimiter: ';',- attachment: csv_signed_id("slug;sku;name;price\nwidget;W-1;Widget;10.00\n")+ attachment_signed_id: csv_signed_id("slug;sku;name;price\nwidget;W-1;Widget;10.00\n")},as: :json@@ -141,7 +141,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller doit 'ignores the list on a type that has none' dopost :create,params: { type: 'products', price_list_id: price_list.prefixed_id,- attachment: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n") },+ attachment_signed_id: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n") },as: :jsonexpect(response).to have_http_status(:created)@@ -158,7 +158,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller dopost :create,params: {type: 'products',- attachment: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n"),+ attachment_signed_id: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n"),results_url: 'https://admin.example.com/store_abc/settings/imports'},as: :json@@ -172,7 +172,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller dopost :create,params: {type: 'products',- attachment: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n"),+ attachment_signed_id: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n"),results_url: 'https://evil.example.com/phish'},as: :json@@ -183,14 +183,14 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller doendit 'rejects unregistered import types' do- post :create, params: { type: 'Spree::User', attachment: csv_signed_id("slug\nx\n") }, as: :json+ post :create, params: { type: 'Spree::User', attachment_signed_id: csv_signed_id("slug\nx\n") }, as: :json# Falls back to Spree::Import which fails the `type` presence validationexpect(response).to have_http_status(:unprocessable_content)endit 'rejects an invalid attachment signed id' do- post :create, params: { type: 'products', attachment: 'not-a-signed-id' }, as: :json+ post :create, params: { type: 'products', attachment_signed_id: 'not-a-signed-id' }, as: :jsonexpect(response).to have_http_status(:unprocessable_content)end@@ -200,7 +200,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller doio: StringIO.new('{}'), filename: 'import.json', content_type: 'application/json')- post :create, params: { type: 'products', attachment: blob.signed_id }, as: :json+ post :create, params: { type: 'products', attachment_signed_id: blob.signed_id }, as: :jsonexpect(response).to have_http_status(:unprocessable_content)end@@ -209,7 +209,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller dopost :create,params: {type: 'products',- attachment: csv_signed_id("slug,\"sku\nbroken")+ attachment_signed_id: csv_signed_id("slug,\"sku\nbroken")},as: :json@@ -458,7 +458,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller dopost :create,params: {type: 'products',- attachment: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n")+ attachment_signed_id: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n")},as: :json@@ -467,7 +467,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller doendit 'rejects creating a Customers import without write_customers' do- post :create, params: { type: 'customers', attachment: csv_signed_id("email\[email protected]\n") }, as: :json+ post :create, params: { type: 'customers', attachment_signed_id: csv_signed_id("email\[email protected]\n") }, as: :jsonexpect(response).to have_http_status(:forbidden)expect(json_response['error']['details']['required_scope']).to eq('write_customers')@@ -479,7 +479,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller doprice_list = create(:price_list, store: store)post :create,- params: { type: 'price_list_prices', price_list_id: price_list.prefixed_id, attachment: csv_signed_id("sku,price\nW-1,1\n") },+ params: { type: 'price_list_prices', price_list_id: price_list.prefixed_id, attachment_signed_id: csv_signed_id("sku,price\nW-1,1\n") },as: :jsonexpect(response).to have_http_status(:created)@@ -510,7 +510,7 @@ RSpec.describe Spree::Api::V3::Admin::ImportsController, type: :controller dopost :create,params: {type: 'products',- attachment: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n")+ attachment_signed_id: csv_signed_id("slug,sku,name,price\nwidget,W-1,Widget,10.00\n")},as: :jsondiff --git a/spree/api/spec/controllers/spree/api/v3/admin/me_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/me_controller_spec.rbindex 645394c08c..9d65e4f7c3 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/me_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/me_controller_spec.rb@@ -205,7 +205,7 @@ RSpec.describe Spree::Api::V3::Admin::MeController, type: :controller docontent_type: 'image/jpeg')end- let(:params) { { avatar: blob.signed_id } }+ let(:params) { { avatar_signed_id: blob.signed_id } }it 'attaches the avatar and returns its url' dosubject@@ -223,7 +223,7 @@ RSpec.describe Spree::Api::V3::Admin::MeController, type: :controller docontent_type: 'image/svg+xml')end- let(:params) { { avatar: blob.signed_id } }+ let(:params) { { avatar_signed_id: blob.signed_id } }it 'rejects the upload with a validation error' dosubject@@ -240,7 +240,7 @@ RSpec.describe Spree::Api::V3::Admin::MeController, type: :controller docontent_type: 'image/jpeg')end- let(:params) { { avatar: nil } }+ let(:params) { { avatar_signed_id: nil } }it 'purges the avatar' dosubjectdiff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/labels_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/labels_controller_spec.rbindex 1fe6ea5178..cd1b496e9f 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/labels_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/labels_controller_spec.rb@@ -55,7 +55,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::LabelsController, type: :controlleit 'records the file, the cost and the consignment' dopost :create, params: {order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,- file: signed_file, tracking_number: '1Z879E930346834440', cost: '6.50', currency: 'USD'+ file_signed_id: signed_file, tracking_number: '1Z879E930346834440', cost: '6.50', currency: 'USD'}, as: :jsonexpect(response).to have_http_status(:created)@@ -64,9 +64,20 @@ RSpec.describe Spree::Api::V3::Admin::Orders::LabelsController, type: :controlleexpect(fulfillment.reload.tracking).to eq('1Z879E930346834440')end+ it 'refuses a file sent under its old name rather than buying a label' do+ expect(Spree.shipping_label_purchase_workflow).not_to receive(:call)++ post :create, params: {+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, file: signed_file, tracking_number: 'X'+ }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response['error']['code']).to eq('parameter_invalid')+ end+it 'refuses an upload with no tracking number' dopost :create, params: {- order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, file: signed_file+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, file_signed_id: signed_file}, as: :jsonexpect(response).to have_http_status(:unprocessable_content)@@ -170,7 +181,7 @@ RSpec.describe Spree::Api::V3::Admin::Orders::LabelsController, type: :controlleit 'records an uploaded label on the return' dopost :create, params: {order_id: return_record.order.prefixed_id, return_id: return_record.prefixed_id,- file: signed_file, tracking_number: 'RET-1'+ file_signed_id: signed_file, tracking_number: 'RET-1'}, as: :jsonexpect(response).to have_http_status(:created)diff --git a/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rbindex c89f543973..01da38e408 100644--- a/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/admin/sellers_controller_spec.rb@@ -208,14 +208,14 @@ RSpec.describe Spree::Api::V3::Admin::SellersController, type: :controller doexpect(json_response['billing_address']['city']).to eq('London')end- # The dashboard direct-uploads the file, then sends the resulting signed id.+ # The dashboard uploads the file, then sends the resulting signed id.it 'attaches branding from a signed id' doblob = ActiveStorage::Blob.create_and_upload!(io: File.open(Spree::Core::Engine.root.join('spec', 'fixtures', 'thinking-cat.jpg')),filename: 'thinking-cat.jpg', content_type: 'image/jpeg')- patch :update, params: { id: seller.prefixed_id, logo: blob.signed_id }, as: :json+ patch :update, params: { id: seller.prefixed_id, logo_signed_id: blob.signed_id }, as: :jsonexpect(response).to have_http_status(:ok)expect(seller.reload.logo).to be_attached@@ -228,7 +228,7 @@ RSpec.describe Spree::Api::V3::Admin::SellersController, type: :controller dofilename: 'cover.jpg', content_type: 'image/jpeg')- patch :update, params: { id: seller.prefixed_id, cover_photo: blob.signed_id }, as: :json+ patch :update, params: { id: seller.prefixed_id, cover_photo_signed_id: blob.signed_id }, as: :jsonexpect(seller.reload.cover_photo).to be_attachedexpect(json_response['cover_photo_url']).to be_present@@ -240,7 +240,7 @@ RSpec.describe Spree::Api::V3::Admin::SellersController, type: :controller dofilename: 'thinking-cat.jpg')- patch :update, params: { id: seller.prefixed_id, logo: nil }, as: :json+ patch :update, params: { id: seller.prefixed_id, logo_signed_id: nil }, as: :jsonexpect(response).to have_http_status(:ok)expect(seller.reload.logo).not_to be_attacheddiff --git a/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rbindex 6e55bc580c..f64e01bf9b 100644--- a/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/seller/me_controller_spec.rb@@ -129,7 +129,7 @@ RSpec.describe Spree::Api::V3::Seller::MeController, type: :controller docontext 'with an avatar signed id' dolet(:blob) { ActiveStorage::Blob.create_and_upload!(**image_attributes) }- let(:params) { { avatar: blob.signed_id } }+ let(:params) { { avatar_signed_id: blob.signed_id } }it 'attaches the avatar and returns its url' dosubject@@ -148,7 +148,7 @@ RSpec.describe Spree::Api::V3::Seller::MeController, type: :controller docontent_type: 'image/svg+xml')end- let(:params) { { avatar: blob.signed_id } }+ let(:params) { { avatar_signed_id: blob.signed_id } }it 'rejects the upload with a validation error' dosubject@@ -160,7 +160,7 @@ RSpec.describe Spree::Api::V3::Seller::MeController, type: :controller docontext 'clearing the avatar' dobefore { seller_user.avatar.attach(**image_attributes) }- let(:params) { { avatar: nil } }+ let(:params) { { avatar_signed_id: nil } }it 'purges the avatar' dosubjectdiff --git a/spree/api/spec/controllers/spree/api/v3/seller/orders/labels_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/seller/orders/labels_controller_spec.rbindex 5bb67d3050..d6d0ff6f9a 100644--- a/spree/api/spec/controllers/spree/api/v3/seller/orders/labels_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/seller/orders/labels_controller_spec.rb@@ -32,7 +32,7 @@ RSpec.describe Spree::Api::V3::Seller::Orders::LabelsController, type: :controllit 'records a label the seller bought elsewhere' dopost :create, params: {order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id,- file: signed_file, tracking_number: 'SELLER-LBL-1', cost: '4.20', currency: 'USD'+ file_signed_id: signed_file, tracking_number: 'SELLER-LBL-1', cost: '4.20', currency: 'USD'}, as: :jsonexpect(response).to have_http_status(:created)diff --git a/spree/api/spec/controllers/spree/api/v3/store/carts/po_documents_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts/po_documents_controller_spec.rbindex 361d025f82..decf3b202e 100644--- a/spree/api/spec/controllers/spree/api/v3/store/carts/po_documents_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/store/carts/po_documents_controller_spec.rb@@ -27,11 +27,13 @@ RSpec.describe Spree::Api::V3::Store::Carts::PoDocumentsController, type: :contrendit 'returns an upload target and a signed id' do- post :create, params: { cart_id: order.prefixed_id, blob: blob_params }+ post :create, params: { cart_id: order.prefixed_id, **blob_params }expect(response).to have_http_status(:created)expect(json_response['signed_id']).to be_present- expect(json_response['direct_upload']['url']).to be_present+ expect(json_response['upload']['url']).to be_present+ expect(json_response['visibility']).to eq('private')+ expect(ActiveStorage::Blob.find_signed!(json_response['signed_id']).store_id).to eq(store.id)end# A guest cart is self-service, so this endpoint is reachable anonymously.@@ -45,7 +47,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PoDocumentsController, type: :contrexpect {post :create, params: {cart_id: order.prefixed_id,- blob: blob_params.merge(byte_size: Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE + 1)+ **blob_params.merge(byte_size: Spree::Purchase::PurchaseOrder::MAX_PO_DOCUMENT_SIZE + 1)}}.not_to change(ActiveStorage::Blob, :count)@@ -56,7 +58,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PoDocumentsController, type: :contrexpect {post :create, params: {cart_id: order.prefixed_id,- blob: blob_params.merge(content_type: 'application/x-sh')+ **blob_params.merge(content_type: 'application/x-sh')}}.not_to change(ActiveStorage::Blob, :count)@@ -65,7 +67,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PoDocumentsController, type: :contrit 'refuses a byte_size that is not a positive number' doexpect {- post :create, params: { cart_id: order.prefixed_id, blob: blob_params.merge(byte_size: 0) }+ post :create, params: { cart_id: order.prefixed_id, **blob_params.merge(byte_size: 0) }}.not_to change(ActiveStorage::Blob, :count)expect(response).to have_http_status(:unprocessable_content)@@ -74,7 +76,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PoDocumentsController, type: :contr# A purchase order carries the buyer's prices and terms, and attaching a# signed id never moves a blob between services.it 'mints the blob on private storage' do- post :create, params: { cart_id: order.prefixed_id, blob: blob_params }+ post :create, params: { cart_id: order.prefixed_id, **blob_params }blob = ActiveStorage::Blob.find_signed!(json_response['signed_id'])expect(blob.service_name).to eq(Spree.private_storage_service_name.to_s)@@ -125,7 +127,7 @@ RSpec.describe Spree::Api::V3::Store::Carts::PoDocumentsController, type: :contrit 'refuses to presign against it' dopost :create, params: { cart_id: other_cart.prefixed_id,- blob: { filename: 'po.pdf', byte_size: 1, checksum: 'x', content_type: 'application/pdf' } }+ filename: 'po.pdf', byte_size: 1, checksum: 'x', content_type: 'application/pdf' }expect(response).not_to have_http_status(:created)enddiff --git a/spree/api/spec/controllers/spree/api/v3/store/carts_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/store/carts_controller_spec.rbindex 56c2410774..05f299b05c 100644--- a/spree/api/spec/controllers/spree/api/v3/store/carts_controller_spec.rb+++ b/spree/api/spec/controllers/spree/api/v3/store/carts_controller_spec.rb@@ -710,7 +710,7 @@ RSpec.describe Spree::Api::V3::Store::CartsController, type: :controller doservice_name: Spree.private_storage_service_name)- patch :update, params: { id: order.prefixed_id, po_document: blob.signed_id }+ patch :update, params: { id: order.prefixed_id, po_document_signed_id: blob.signed_id }expect(response).to have_http_status(:ok)expect(order.reload.po_document).to be_attached@@ -719,7 +719,7 @@ RSpec.describe Spree::Api::V3::Store::CartsController, type: :controller do# A tampered id must not surface as a 500.it 'refuses a tampered signed id' do- patch :update, params: { id: order.prefixed_id, po_document: 'not-a-signed-id' }+ patch :update, params: { id: order.prefixed_id, po_document_signed_id: 'not-a-signed-id' }expect(response).to have_http_status(:unprocessable_content)expect(order.reload.po_document).not_to be_attacheddiff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rbindex 00f38c45ef..4db7124a76 100644--- a/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/tax_exemption_certificates_spec.rb@@ -62,8 +62,8 @@ RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_duntil verified.`country_code` and `state_code` say where the certificate holds — omit both for one valid- everywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage- signed blob id obtained from `POST /api/v3/admin/direct_uploads`.+ everywhere, give only the country for one valid throughout it. `document_signed_id` takes the+ `signed_id` returned by `POST /api/v3/admin/files`.DESCadmin_scope :write, :customers@@ -78,9 +78,9 @@ RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_dstate_code: { type: :string, nullable: true, example: 'BE' },expires_at: { type: :string, format: 'date-time', nullable: true },issuing_authority: { type: :string, nullable: true, example: 'Finanzamt Berlin' },- document: {+ document_signed_id: {type: :string,- description: 'ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.',+ description: 'The `signed_id` returned by POST /api/v3/admin/files.',example: 'eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed'}},@@ -93,7 +93,7 @@ RSpec.describe 'Admin Tax Exemption Certificates API', type: :request, swagger_dcertificate_number: 'DE-RESALE-7',reason_code: 'resale',country_code: germany.iso,- document: pdf_blob.signed_id+ document_signed_id: pdf_blob.signed_id}enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/files_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/files_spec.rbnew file mode 100644index 0000000000..d40eb4cb82--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/files_spec.rb@@ -0,0 +1,93 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Files API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:Authorization) { "Bearer #{admin_jwt_token}" }++ path '/api/v3/admin/files' do+ post 'Upload a file' do+ tags 'Files'+ consumes 'application/json', 'multipart/form-data'+ produces 'application/json'+ security [api_key: [], bearer_auth: []]+ description <<~DESC+ Accepts a file and returns a `signed_id` to send to the endpoint that+ uses it — `signed_id` on product media, `avatar_signed_id` on a+ customer, `attachment_signed_id` on an import, and so on.++ Two ways to send the bytes, one response:++ - **Presigned** (JSON): send the file's metadata, then `PUT` the bytes+ to `upload.url` with exactly `upload.headers`. Use this for anything+ large — the bytes go straight to storage.+ - **Multipart**: send the bytes in a `file` part. The file is stored+ before the response, so `upload` is null. Limited to 10 MB by default.++ `signed_id` is opaque: pass it back unchanged and never parse it. It+ stops being attachable at `expires_at`, one day after the upload.++ `visibility` picks the storage: `public` (the default) for images and+ videos customers see, `private` for documents, imports and digital+ products. Public uploads accept web images, videos and CSV; private+ uploads accept any type. `checksum` is the file's MD5 digest,+ base64-encoded — the storage service verifies the bytes against it.+ DESC+ admin_scope :write, :products++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true,+ description: 'Bearer token for admin authentication'+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ filename: { type: :string, example: 'products.csv' },+ content_type: { type: :string, example: 'text/csv' },+ byte_size: { type: :integer, example: 48_213 },+ checksum: { type: :string, description: 'Base64-encoded MD5 digest of the file', example: 'rL0Y20zC+Fzt72VPzMSk2A==' },+ visibility: { type: :string, enum: %w[public private], default: 'public' },+ file: { type: :string, format: :binary, description: 'The bytes, for a multipart upload' }+ },+ required: %w[filename content_type]+ }++ response '201', 'presigned upload target created' do+ let(:body) do+ {+ filename: 'products.csv',+ content_type: 'text/csv',+ byte_size: 48_213,+ checksum: Digest::MD5.base64digest('products'),+ visibility: 'private'+ }+ end++ schema SwaggerSchemaHelpers.ref('FileUpload')++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['signed_id']).to be_present+ expect(data['visibility']).to eq('private')+ expect(data['upload']['method']).to eq('PUT')+ expect(data['upload']['url']).to be_present+ expect(ActiveStorage::Blob.find_signed(data['signed_id']).store_id).to eq(store.id)+ end+ end++ response '422', 'content type not allowed for a public upload' do+ let(:body) do+ { filename: 'script.sh', content_type: 'application/x-sh', byte_size: 12, checksum: Digest::MD5.base64digest('x') }+ end++ schema SwaggerSchemaHelpers.ref('ErrorResponse')++ run_test! do |response|+ expect(JSON.parse(response.body)['error']['details']).to have_key('content_type')+ end+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/imports_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/imports_spec.rbindex 3697bf8efd..cf4e6ca289 100644--- a/spree/api/spec/integration/spree/api/v3/admin/imports_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/imports_spec.rb@@ -46,8 +46,8 @@ RSpec.describe 'Admin Imports API', type: :request, swagger_doc: 'api-reference/produces 'application/json'security [api_key: [], bearer_auth: []]description <<~MD- Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`- and pass the returned `signed_id` as `attachment`. On success the import is in the+ Queues a CSV import. Upload the file first via `POST /api/v3/admin/files`+ and pass the returned `signed_id` as `attachment_signed_id`. On success the import is in the`mapping` state and the response carries the mapping payload: `schema_fields`(the canonical columns for the type), `csv_headers`, a `sample_row`, and theauto-assigned `mappings`.@@ -62,7 +62,7 @@ RSpec.describe 'Admin Imports API', type: :request, swagger_doc: 'api-reference/parameter name: :Authorization, in: :header, type: :string, required: trueparameter name: :body, in: :body, schema: {type: :object,- required: %w[type attachment],+ required: %w[type attachment_signed_id],properties: {type: {type: :string,@@ -81,9 +81,9 @@ RSpec.describe 'Admin Imports API', type: :request, swagger_doc: 'api-reference/'Must belong to the current store.',example: 'pl_86Rf07xd4z'},- attachment: {+ attachment_signed_id: {type: :string,- description: 'ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.',+ description: 'The `signed_id` returned by POST /api/v3/admin/files.',example: 'eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed'},delimiter: {@@ -107,7 +107,7 @@ RSpec.describe 'Admin Imports API', type: :request, swagger_doc: 'api-reference/let(:body) do{type: 'products',- attachment: csv_blob("slug,sku,name,price\nwidget,W-1,Widget,10.00\n").signed_id+ attachment_signed_id: csv_blob("slug,sku,name,price\nwidget,W-1,Widget,10.00\n").signed_id}end@@ -122,7 +122,7 @@ RSpec.describe 'Admin Imports API', type: :request, swagger_doc: 'api-reference/response '422', 'unknown import type' dolet(:'x-spree-api-key') { secret_api_key.plaintext_token }- let(:body) { { type: 'Spree::Unknown', attachment: csv_blob("slug\nx\n").signed_id } }+ let(:body) { { type: 'Spree::Unknown', attachment_signed_id: csv_blob("slug\nx\n").signed_id } }run_test!enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/media_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/media_spec.rbindex 99fc30c196..e59808bf2b 100644--- a/spree/api/spec/integration/spree/api/v3/admin/media_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/media_spec.rb@@ -48,7 +48,7 @@ RSpec.describe 'Admin Media Library API', type: :request, swagger_doc: 'api-refesecurity [api_key: [], bearer_auth: []]description <<~DESCAdds a file to the library without placing it on anything. Upload the- file first through the direct-upload endpoint, then send the signed id+ file first through `POST /api/v3/admin/files`, then send the signed idhere. Put the file on a product by posting to that product's media withthis record's id as `source_media_id`.DESC@@ -60,7 +60,7 @@ RSpec.describe 'Admin Media Library API', type: :request, swagger_doc: 'api-refeparameter name: :body, in: :body, schema: {type: :object,properties: {- signed_id: { type: :string, description: 'Direct-upload signed id for the file.' },+ signed_id: { type: :string, description: 'The `signed_id` returned by POST /api/v3/admin/files.' },alt: { type: :string, example: 'Folded on a table' },media_type: { type: :string, enum: %w[image video external_video], example: 'image' },external_video_url: { type: :string, description: 'YouTube or Vimeo link, for an external video.' }diff --git a/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rbindex 11f71b624a..6dc1449519 100644--- a/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/admin/sellers_spec.rb@@ -205,14 +205,14 @@ RSpec.describe 'Admin Sellers API', type: :request, swagger_doc: 'api-reference/},minimum_payout_amount: { type: :string, example: '25.0', nullable: true },holiday_mode_until: { type: :string, format: 'date-time', nullable: true },- logo: {+ logo_signed_id: {type: :string, nullable: true,- description: 'ActiveStorage signed id of a direct-uploaded file. Send `null` ' \- 'to remove the attachment, or omit the key to leave it alone. ' \- 'Same for `square_logo` and `cover_photo`.'+ description: 'The `signed_id` returned by POST /api/v3/admin/files. Send `null` ' \+ 'to remove the image, or omit the key to leave it alone. ' \+ 'Same for `square_logo_signed_id` and `cover_photo_signed_id`.'},- square_logo: { type: :string, nullable: true },- cover_photo: { type: :string, nullable: true },+ square_logo_signed_id: { type: :string, nullable: true },+ cover_photo_signed_id: { type: :string, nullable: true },billing_address: SELLER_ADDRESS_SCHEMA,returns_address: SELLER_ADDRESS_SCHEMA}diff --git a/spree/api/spec/integration/spree/api/v3/seller/direct_uploads_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/direct_uploads_spec.rbdeleted file mode 100644index d77fff0190..0000000000--- a/spree/api/spec/integration/spree/api/v3/seller/direct_uploads_spec.rb+++ /dev/null@@ -1,78 +0,0 @@-# frozen_string_literal: true--require 'swagger_helper'--RSpec.describe 'Seller Direct Uploads API', type: :request, swagger_doc: 'api-reference/seller.yaml' do- include_context 'API v3 Seller'-- # The seeded role rather than the shared context's products-only one — this- # is what a member of a seller's team actually holds on their own seller.- let(:seller_user) do- create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }- end-- path '/api/v3/seller/direct_uploads' do- post 'Create a direct upload' do- tags 'Uploads'- consumes 'application/json'- produces 'application/json'- security [bearer_auth: []]- description <<~DESC- Presigns an upload target for a file the seller is about to send.-- Three steps: post the file's metadata here, `PUT` the bytes to the- returned `direct_upload.url` with the headers it names, then send the- returned `signed_id` wherever the file belongs — as a requirement- submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the- profile.-- The blob is attached to nothing at this point. The endpoint that consumes- the `signed_id` is the one that checks ownership.-- `checksum` is the file's MD5 digest, base64-encoded — the storage service- verifies the upload against it.- DESC-- parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true- parameter name: :body, in: :body, schema: {- type: :object,- properties: {- blob: {- type: :object,- properties: {- filename: { type: :string, example: 'registration.pdf' },- byte_size: { type: :integer, example: 51_234 },- checksum: { type: :string, description: 'Base64-encoded MD5 digest of the file', example: 'rL0Y20zC+Fzt72VPzMSk2A==' },- content_type: { type: :string, example: 'application/pdf' }- },- required: %w[filename byte_size checksum content_type]- }- },- required: %w[blob]- }-- response '201', 'upload target created' do- let(:Authorization) { "Bearer #{seller_jwt_token}" }- let(:'X-Spree-Seller-Id') { seller.prefixed_id }- let(:body) do- {- blob: {- filename: 'registration.pdf',- byte_size: 51_234,- checksum: Digest::MD5.base64digest('registration'),- content_type: 'application/pdf'- }- }- end-- schema '$ref' => '#/components/schemas/DirectUploadResponse'-- run_test! do |response|- data = JSON.parse(response.body)- expect(data['signed_id']).to be_present- expect(data['direct_upload']['url']).to be_present- end- end- end- end-enddiff --git a/spree/api/spec/integration/spree/api/v3/seller/files_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/files_spec.rbnew file mode 100644index 0000000000..100f60a119--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/seller/files_spec.rb@@ -0,0 +1,75 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Seller Files API', type: :request, swagger_doc: 'api-reference/seller.yaml' do+ include_context 'API v3 Seller'++ # The seeded role rather than the shared context's products-only one — this+ # is what a member of a seller's team actually holds on their own seller.+ let(:seller_user) do+ create(:admin_user, :without_admin_role).tap { |user| seller.add_user(user) }+ end++ path '/api/v3/seller/files' do+ post 'Upload a file' do+ tags 'Files'+ consumes 'application/json', 'multipart/form-data'+ produces 'application/json'+ security [bearer_auth: []]+ description <<~DESC+ Accepts a file and returns a `signed_id` to send wherever the file+ belongs — as a requirement submission's `file_signed_id`, or as+ `logo_signed_id`, `square_logo_signed_id` or `cover_photo_signed_id` on+ the profile. The file is attached to nothing at this point; the+ endpoint that takes the `signed_id` is the one that checks ownership.++ Send the file's metadata as JSON, then `PUT` the bytes to `upload.url`+ with exactly `upload.headers`; or send small files (10 MB by default)+ as a multipart `file` part, in which case `upload` is null.++ `signed_id` is opaque and expires at `expires_at`, one day after the+ upload. `visibility` is `public` (the default, web images, videos and+ CSV only) or `private` (any type). `checksum` is the file's MD5+ digest, base64-encoded.+ DESC++ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ filename: { type: :string, example: 'registration.pdf' },+ content_type: { type: :string, example: 'application/pdf' },+ byte_size: { type: :integer, example: 51_234 },+ checksum: { type: :string, description: 'Base64-encoded MD5 digest of the file', example: 'rL0Y20zC+Fzt72VPzMSk2A==' },+ visibility: { type: :string, enum: %w[public private], default: 'public' },+ file: { type: :string, format: :binary, description: 'The bytes, for a multipart upload' }+ },+ required: %w[filename content_type]+ }++ response '201', 'upload target created' do+ let(:Authorization) { "Bearer #{seller_jwt_token}" }+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }+ let(:body) do+ {+ filename: 'registration.pdf',+ content_type: 'application/pdf',+ byte_size: 51_234,+ checksum: Digest::MD5.base64digest('registration'),+ visibility: 'private'+ }+ end++ schema SwaggerSchemaHelpers.ref('FileUpload')++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['signed_id']).to be_present+ expect(data['upload']['url']).to be_present+ expect(ActiveStorage::Blob.find_signed(data['signed_id']).store_id).to eq(store.id)+ end+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/me_spec.rbindex f5fa4bcdd4..138a56e0e4 100644--- a/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/seller/me_spec.rb@@ -62,7 +62,7 @@ RSpec.describe 'Seller Account API', type: :request, swagger_doc: 'api-reference`X-Spree-Seller-Id`, because the account is the same whichever sellerthey are acting for.- `avatar` takes an ActiveStorage direct-upload signed id to set the+ `avatar_signed_id` takes the `signed_id` from `POST /files` to set thephoto, or `null` to remove it; omit it to leave the current one alone.`email` is identity-bound and cannot be changed here.DESC@@ -73,7 +73,7 @@ RSpec.describe 'Seller Account API', type: :request, swagger_doc: 'api-referencefirst_name: { type: :string, example: 'Ada' },last_name: { type: :string, example: 'Lovelace' },selected_locale: { type: :string, example: 'de', description: 'Panel display language, as a code the panel ships.' },- avatar: { type: :string, nullable: true, description: 'Direct-upload signed id, or `null` to remove the photo.' }+ avatar_signed_id: { type: :string, nullable: true, description: 'The `signed_id` returned by POST /files, or `null` to remove the photo.' }}}@@ -100,7 +100,7 @@ RSpec.describe 'Seller Account API', type: :request, swagger_doc: 'api-referencecontent_type: 'image/svg+xml')end- let(:body) { { avatar: blob.signed_id } }+ let(:body) { { avatar_signed_id: blob.signed_id } }schema '$ref' => '#/components/schemas/ErrorResponse'diff --git a/spree/api/spec/integration/spree/api/v3/seller/profile_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/profile_spec.rbindex adaff18241..84b509840a 100644--- a/spree/api/spec/integration/spree/api/v3/seller/profile_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/seller/profile_spec.rb@@ -79,9 +79,9 @@ RSpec.describe 'Seller Profile API', type: :request, swagger_doc: 'api-referenceabout: { type: :string, nullable: true, description: 'Sanitized HTML — the seller\'s public description' },legal_name: { type: :string, nullable: true, description: 'The business a commission invoice is made out to' },registration_number: { type: :string, nullable: true },- logo: { type: :string, nullable: true, description: 'ActiveStorage signed id; `null` removes the attachment' },- square_logo: { type: :string, nullable: true },- cover_photo: { type: :string, nullable: true },+ logo_signed_id: { type: :string, nullable: true, description: 'The `signed_id` returned by POST /files; `null` removes the image' },+ square_logo_signed_id: { type: :string, nullable: true },+ cover_photo_signed_id: { type: :string, nullable: true },accept_terms: { type: :boolean, description: 'Stamps acceptance of the marketplace terms' },billing_address: { type: :object, additionalProperties: true },custom_fields: {diff --git a/spree/api/spec/integration/spree/api/v3/seller/requirement_submissions_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/requirement_submissions_spec.rbindex 02ba314b9f..40fee4cad5 100644--- a/spree/api/spec/integration/spree/api/v3/seller/requirement_submissions_spec.rb+++ b/spree/api/spec/integration/spree/api/v3/seller/requirement_submissions_spec.rb@@ -30,8 +30,8 @@ RSpec.describe 'Seller Requirement Submissions API', type: :request, swagger_docneeds to correct something submits again rather than editing, and thelatest one counts.- `file` is **not** a multipart upload — it is the `signed_id` returned by- `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage+ `file_signed_id` is the `signed_id` returned by+ `POST /api/v3/seller/files`, so the bytes are already in storageby the time this runs.An attestation is accepted on the spot; a requirement the operator@@ -44,7 +44,7 @@ RSpec.describe 'Seller Requirement Submissions API', type: :request, swagger_docproperties: {note: { type: :string, description: 'Anything the seller wants to say alongside the submission' },reference: { type: :string, description: 'A reference number or external identifier, for requirements that ask for one' },- file: { type: :string, description: 'A direct-upload `signed_id`, for requirements that ask for a document' }+ file_signed_id: { type: :string, description: 'The `signed_id` returned by POST /files, for requirements that ask for a document' }}}diff --git a/spree/api/spec/lib/spree/api/middleware/request_size_limit_spec.rb b/spree/api/spec/lib/spree/api/middleware/request_size_limit_spec.rbindex 4073669153..6113bc12e6 100644--- a/spree/api/spec/lib/spree/api/middleware/request_size_limit_spec.rb+++ b/spree/api/spec/lib/spree/api/middleware/request_size_limit_spec.rb@@ -50,6 +50,29 @@ RSpec.describe Spree::Api::Middleware::RequestSizeLimit doendend+ context 'file uploads' do+ let(:multipart_limit) { Spree::Config[:max_multipart_upload_size] + described_class::MULTIPART_ENVELOPE }++ it 'holds POST /files to the multipart upload limit instead' do+ %w[/api/v3/admin/files /api/v3/seller/files].each do |path|+ expect(middleware.call(env_for(path, content_length: multipart_limit)).first).to eq(200)+ expect(middleware.call(env_for(path, content_length: multipart_limit + 1)).first).to eq(413)+ end+ end++ it 'refuses a chunked upload, whose length cannot be checked' do+ env = { 'PATH_INFO' => '/api/v3/admin/files', 'REQUEST_METHOD' => 'POST', 'HTTP_TRANSFER_ENCODING' => 'chunked' }++ expect(middleware.call(env).first).to eq(411)+ end++ it 'keeps the general limit for the Store API' do+ status, _headers, _body = middleware.call(env_for('/api/v3/store/files', content_length: 1_000_000))++ expect(status).to eq(413)+ end+ end+context 'non-API requests' doit 'does not limit requests to other paths' dostatus, _headers, _body = middleware.call(env_for('/admin/products', content_length: 10_000_000))diff --git a/spree/api/spec/requests/spree/api/v3/seller/import_flow_spec.rb b/spree/api/spec/requests/spree/api/v3/seller/import_flow_spec.rbindex 337cc5673a..a450e2e008 100644--- a/spree/api/spec/requests/spree/api/v3/seller/import_flow_spec.rb+++ b/spree/api/spec/requests/spree/api/v3/seller/import_flow_spec.rb@@ -38,7 +38,7 @@ RSpec.describe 'Seller CSV import', type: :request doit 'imports the seller\'s own products as drafts' dopost '/api/v3/seller/imports',- params: { type: 'products', attachment: signed_id }, headers: headers+ params: { type: 'products', attachment_signed_id: signed_id }, headers: headersexpect(response).to have_http_status(:created)expect(json['status']).to eq('mapping')@@ -71,7 +71,7 @@ RSpec.describe 'Seller CSV import', type: :request doseller: seller, store: store)post '/api/v3/seller/imports',- params: { type: 'products', attachment: signed_id }, headers: headers+ params: { type: 'products', attachment_signed_id: signed_id }, headers: headersimport = Spree::Import.find_by_prefix_id(json['id'])import.update!(preferred_inline: true)patch "/api/v3/seller/imports/#{import.prefixed_id}/complete_mapping", headers: headers@@ -95,7 +95,7 @@ RSpec.describe 'Seller CSV import', type: :request do)post '/api/v3/seller/imports',- params: { type: 'products', attachment: blob.signed_id }, headers: headers+ params: { type: 'products', attachment_signed_id: blob.signed_id }, headers: headersimport = Spree::Import.find_by_prefix_id(json['id'])import.update!(preferred_inline: true)patch "/api/v3/seller/imports/#{import.prefixed_id}/complete_mapping", headers: headers@@ -107,7 +107,7 @@ RSpec.describe 'Seller CSV import', type: :request doit 'refuses an import type that is not a seller\'s to run' dopost '/api/v3/seller/imports',- params: { type: 'customers', attachment: signed_id }, headers: headers+ params: { type: 'customers', attachment_signed_id: signed_id }, headers: headersexpect(response).not_to have_http_status(:created)end@@ -118,7 +118,7 @@ RSpec.describe 'Seller CSV import', type: :request doseller: other_seller, store: store)post '/api/v3/seller/imports',- params: { type: 'products', attachment: signed_id }, headers: headers+ params: { type: 'products', attachment_signed_id: signed_id }, headers: headersimport = Spree::Import.find_by_prefix_id(json['id'])import.update!(preferred_inline: true)patch "/api/v3/seller/imports/#{import.prefixed_id}/complete_mapping", headers: headersdiff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rbindex 237b39b876..a0cf672cb2 100644--- a/spree/api/spec/swagger_helper.rb+++ b/spree/api/spec/swagger_helper.rb@@ -169,6 +169,7 @@ RSpec.configure do |config|{ name: 'Customers', description: 'Customer profiles, addresses, credit cards, and store credits' },{ name: 'Email Templates', description: 'Customer email templates, the email layout and shared partials: drafts, previews, publishing and history' },{ name: 'Exports', description: 'Async CSV exports of admin resources' },+ { name: 'Files', description: 'Uploading the files that product media, imports, logos and documents use' },{ name: 'Fulfillments', description: 'Order fulfillments — shipments, fulfill, cancel, resume, split' },{ name: 'Gift Cards', description: 'Gift cards and gift card batches' },{ name: 'Imports', description: 'Async CSV imports of admin resources, with per-row status and failed-row retry' },@@ -295,7 +296,7 @@ RSpec.configure do |config|{ name: 'Profile', description: "The seller's own record — presentation, contact details, addresses, and tax registration" },{ name: 'Stock Locations', description: 'Where the seller keeps stock, and so where their returns are sent' },{ name: 'Team', description: 'Who runs this seller, and the invitations nobody has accepted yet' },- { name: 'Uploads', description: 'Presigned direct uploads for the documents onboarding asks for' }+ { name: 'Files', description: 'Uploading the files a profile, a submission or an import uses' }],components: {securitySchemes: {diff --git a/spree/core/app/jobs/spree/uploads/purge_unattached_job.rb b/spree/core/app/jobs/spree/uploads/purge_unattached_job.rbnew file mode 100644index 0000000000..260f61e8a3--- /dev/null+++ b/spree/core/app/jobs/spree/uploads/purge_unattached_job.rb@@ -0,0 +1,49 @@+module Spree+ module Uploads+ # Deletes uploaded files that were never attached to anything, once they+ # are older than `Spree::Config.unattached_upload_retention_days`.+ #+ # Rails deletes nothing on its own, so an upload abandoned halfway (a+ # closed tab, a failed form) would otherwise stay in storage forever. The+ # retention outlasts an upload reference, which expires after a day, so no+ # file a client can still attach is deleted.+ #+ # Scheduled daily by the host app (`spree/spree-starter`'s recurring.yml+ # ships the entry). Continuable: the cursor is the last file handled, so a+ # deploy mid-run resumes rather than starting over.+ class PurgeUnattachedJob < Spree::BaseJob+ include ActiveJob::Continuable++ def perform+ step :purge+ end++ private++ def purge(step)+ # Only files that belong to a store: a host app may keep blobs of its+ # own outside attachments, and those are not Spree's to delete.+ blobs = ActiveStorage::Blob.unattached.where.not(store_id: nil).+ where(created_at: ...Spree::Config.unattached_upload_retention_days.days.ago)+ blobs = blobs.where(ActiveStorage::Blob.arel_table[:id].gt(step.cursor)) if step.cursor++ blobs.find_each(order: :asc) do |blob|+ purge_blob(blob)+ step.set!(blob.id)+ end+ end++ # A file attached between the query and the purge is kept. The check+ # covers databases that do not enforce the attachments foreign key; the+ # rescue covers the moment between the check and the delete on those+ # that do.+ def purge_blob(blob)+ return if blob.attachments.exists?++ blob.purge+ rescue ActiveRecord::InvalidForeignKey+ nil+ end+ end+ end+enddiff --git a/spree/core/app/models/concerns/spree/admin_user_methods.rb b/spree/core/app/models/concerns/spree/admin_user_methods.rbindex b214dc0c98..345fb2e3a0 100644--- a/spree/core/app/models/concerns/spree/admin_user_methods.rb+++ b/spree/core/app/models/concerns/spree/admin_user_methods.rb@@ -4,6 +4,7 @@ module Spreeinclude Spree::Actorinclude Spree::PrefixedId+ include Spree::SignedIdAttachmentsinclude Spree::UserRolesinclude Spree::RansackableAttributes@@ -66,6 +67,7 @@ module Spree# Attachmentshas_one_attached :avatar, service: Spree.public_storage_service_name+ signed_id_attachments :avatarvalidates :avatar, content_type: Rails.application.config.active_storage.web_image_content_typesdiff --git a/spree/core/app/models/concerns/spree/customer_methods.rb b/spree/core/app/models/concerns/spree/customer_methods.rbindex 21c3859152..a15a5afda2 100644--- a/spree/core/app/models/concerns/spree/customer_methods.rb+++ b/spree/core/app/models/concerns/spree/customer_methods.rb@@ -3,6 +3,7 @@ module Spreeextend ActiveSupport::Concerninclude Spree::PrefixedId+ include Spree::SignedIdAttachmentsinclude Spree::HasCustomFieldsinclude Spree::UserAddressinclude Spree::UserPaymentSource@@ -119,6 +120,7 @@ module Spree# Attachments#has_one_attached :avatar, service: Spree.public_storage_service_name+ signed_id_attachments :avatarhas_spree_rich_text :internal_notediff --git a/spree/core/app/models/concerns/spree/purchase/purchase_order.rb b/spree/core/app/models/concerns/spree/purchase/purchase_order.rbindex 26399867c7..7dd8ba4de1 100644--- a/spree/core/app/models/concerns/spree/purchase/purchase_order.rb+++ b/spree/core/app/models/concerns/spree/purchase/purchase_order.rb@@ -36,6 +36,7 @@ module Spree# internal cost codes, and is served only through an authenticated# download action.has_one_attached :po_document, service: Spree.private_storage_service_name+ signed_id_attachments :po_documentvalidates :po_document,size: { less_than_or_equal_to: MAX_PO_DOCUMENT_SIZE },diff --git a/spree/core/app/models/concerns/spree/signed_id_attachments.rb b/spree/core/app/models/concerns/spree/signed_id_attachments.rbnew file mode 100644index 0000000000..cd397a14b8--- /dev/null+++ b/spree/core/app/models/concerns/spree/signed_id_attachments.rb@@ -0,0 +1,54 @@+module Spree+ # Gives attachment slots their API write name, `<slot>_signed_id`+ # (docs/plans/6.0-uploads-and-file-ownership.md).+ #+ # signed_id_attachments :logo, :mailer_logo+ # store.update(logo_signed_id: upload.signed_id) # attaches+ # store.update(logo_signed_id: nil) # removes+ #+ # A declared slot also refuses a file stored with the other visibility:+ # attaching never moves a file between storage services, so a public upload+ # attached to a private slot would stay readable at a public URL.+ module SignedIdAttachments+ extend ActiveSupport::Concern++ included do+ class_attribute :signed_id_attachment_slots, instance_writer: false, default: []+ end++ class_methods do+ # @param slots [Array<Symbol>] `has_one_attached` slot names+ # @return [void]+ def signed_id_attachments(*slots)+ validate :signed_id_attachments_on_their_storage if signed_id_attachment_slots.empty?+ self.signed_id_attachment_slots += slots++ slots.each do |slot|+ define_method(:"#{slot}_signed_id=") { |signed_id| public_send(:"#{slot}=", signed_id) }+ end+ end++ # The name the API reports +attribute+'s errors under: `logo_signed_id`+ # for the `logo` slot, so a client reads them back under the field it sent.+ #+ # @param attribute [Symbol, String]+ # @return [String, nil] nil when +attribute+ is not a declared slot+ def signed_id_attribute_for(attribute)+ "#{attribute}_signed_id" if signed_id_attachment_slots.include?(attribute.to_sym)+ end+ end++ private++ def signed_id_attachments_on_their_storage+ signed_id_attachment_slots.each do |slot|+ blob = attachment_changes[slot.to_s].try(:blob)+ expected_service = self.class.reflect_on_attachment(slot)&.options&.dig(:service_name)+ next if blob.nil? || expected_service.nil? || blob.service_name.to_s == expected_service.to_s++ visibility = expected_service.to_s == Spree.private_storage_service_name.to_s ? 'private' : 'public'+ errors.add(slot, :wrong_visibility, message: I18n.t('spree.upload_wrong_visibility', visibility: visibility))+ end+ end+ end+enddiff --git a/spree/core/app/models/spree/base.rb b/spree/core/app/models/spree/base.rbindex 7d3dfe2ec2..8f31ca0a1b 100644--- a/spree/core/app/models/spree/base.rb+++ b/spree/core/app/models/spree/base.rb@@ -9,6 +9,7 @@ class Spree::Base < ApplicationRecordinclude Spree::HasNumberinclude Spree::HasIsoGeographyinclude Spree::TypedAssociations+ include Spree::SignedIdAttachmentsinclude Spree::ValidatesStoreUniqueness# Extra writable attributes contributed by extensions, appended to the v3diff --git a/spree/core/app/models/spree/category.rb b/spree/core/app/models/spree/category.rbindex da00d94a7a..986589c490 100644--- a/spree/core/app/models/spree/category.rb+++ b/spree/core/app/models/spree/category.rb@@ -61,6 +61,7 @@ module Spree#has_one_attached :image, service: Spree.public_storage_service_namehas_one_attached :square_image, service: Spree.public_storage_service_name+ signed_id_attachments :image, :square_image# The slots double as media-library placements, so an upload here is# visible and reusable there (Spree::HasLibraryMedia).has_library_media :image, :square_imagediff --git a/spree/core/app/models/spree/collection.rb b/spree/core/app/models/spree/collection.rbindex 0056256461..b18aa6db39 100644--- a/spree/core/app/models/spree/collection.rb+++ b/spree/core/app/models/spree/collection.rb@@ -72,6 +72,7 @@ module Spree#has_one_attached :image, service: Spree.public_storage_service_namehas_one_attached :square_image, service: Spree.public_storage_service_name+ signed_id_attachments :image, :square_image# The slots double as media-library placements, so an upload here is# visible and reusable there (Spree::HasLibraryMedia).has_library_media :image, :square_imagediff --git a/spree/core/app/models/spree/file_upload.rb b/spree/core/app/models/spree/file_upload.rbnew file mode 100644index 0000000000..772ab2e3f5--- /dev/null+++ b/spree/core/app/models/spree/file_upload.rb@@ -0,0 +1,155 @@+module Spree+ # A file sent to `POST /files` (docs/plans/6.0-uploads-and-file-ownership.md),+ # before anything uses it.+ #+ # Two ways in, one result. A presigned upload carries only the file's+ # metadata and gets back a storage target the client sends the bytes to; a+ # multipart upload carries the bytes, which are stored here. Either way the+ # result is a blob owned by +store+ and an expiring, opaque `signed_id` the+ # client passes to whichever endpoint uses the file.+ #+ # Never persisted: the blob is the record.+ class FileUpload+ include ActiveModel::Model+ include ActiveModel::Attributes++ VISIBILITIES = %w[public private].freeze++ attribute :filename, :string+ attribute :content_type, :string+ attribute :byte_size, :integer+ attribute :checksum, :string+ attribute :visibility, :string, default: 'public'+ # The bytes of a multipart upload (an uploaded file or any IO).+ attribute :file+ attribute :store+ # Narrower limits for a caller with its own rules (a buyer's purchase+ # order document); the installation-wide ones apply otherwise.+ attribute :max_byte_size, :integer+ attribute :allowed_content_types++ attr_reader :blob, :signed_id, :expires_at++ validates :store, presence: true+ validates :visibility, inclusion: { in: VISIBILITIES }+ validates :filename, :content_type, presence: true+ validates :checksum, presence: true, unless: :multipart?+ validates :byte_size, numericality: { only_integer: true, greater_than: 0 }+ validate :byte_size_within_limit+ validate :content_type_allowed++ # The content types a public upload may have. Private uploads accept any+ # type: digital products are ebooks, archives and audio, and each+ # attachment validates its own file.+ #+ # @return [Array<String>]+ def self.public_content_types+ Rails.application.config.active_storage.web_image_content_types ++ Spree::Config.video_content_types ++ %w[text/csv]+ end++ # @return [Boolean] whether the bytes travel in the request+ def multipart?+ file.respond_to?(:read)+ end++ # @return [Boolean] whether the file lands on private storage+ def private?+ visibility == 'private'+ end++ # Validates and creates the blob. A multipart upload is stored here; a+ # presigned one waits for the client to send its bytes to {#upload_target}.+ #+ # @return [Boolean]+ def save+ read_file_facts if multipart?+ return false unless valid?++ @blob = multipart? ? store_bytes : reserve_blob+ @expires_at = Spree::Uploads::SIGNED_ID_EXPIRY.from_now+ @signed_id = Spree::Uploads.signed_id_for(@blob)+ true+ end++ # Where a presigned upload's bytes go, or nil once the file is stored.+ #+ # @return [Spree::FileUpload::Target, nil]+ def upload_target+ return if multipart? || blob.nil?++ Target.new(+ http_method: 'PUT',+ url: blob.service_url_for_direct_upload,+ headers: blob.service_headers_for_direct_upload+ )+ end++ # The storage target a presigned upload sends its bytes to.+ class Target+ include ActiveModel::Model+ include ActiveModel::Attributes++ # Not `method`, which every Ruby object already answers.+ attribute :http_method, :string+ attribute :url, :string+ attribute :headers+ end++ private++ # The size of a multipart upload comes from the bytes, and so does its type+ # wherever the bytes carry a recognisable signature: Marcel reads the+ # content first, so a renamed executable is not accepted as an image. Only+ # bytes it cannot place fall back to the declared type and the file name.+ def read_file_facts+ self.filename = filename.presence || file.try(:original_filename)+ self.byte_size = io.size+ self.content_type = Marcel::MimeType.for(io, name: filename, declared_type: content_type.presence || file.try(:content_type))+ io.rewind+ end++ def reserve_blob+ ActiveStorage::Blob.create!(+ filename: filename, byte_size: byte_size, checksum: checksum, content_type: content_type,+ service_name: service_name, store_id: store.id+ )+ end++ def store_bytes+ ActiveStorage::Blob.build_after_unfurling(+ io: io, filename: filename, content_type: content_type, service_name: service_name, identify: false+ ).tap do |blob|+ blob.store_id = store.id+ blob.save!+ blob.upload_without_unfurling(io)+ end+ end++ def io+ @io ||= file.respond_to?(:to_io) ? file.to_io : file+ end++ def service_name+ private? ? Spree.private_storage_service_name : Spree.public_storage_service_name+ end++ def size_limit+ max_byte_size || (multipart? ? Spree::Config.max_multipart_upload_size : Spree::Config.max_upload_size)+ end++ def byte_size_within_limit+ return if byte_size.nil? || byte_size <= size_limit++ errors.add(:byte_size, :less_than_or_equal_to, count: ActiveSupport::NumberHelper.number_to_human_size(size_limit))+ end++ def content_type_allowed+ allowed = allowed_content_types || (self.class.public_content_types unless private?)+ return if allowed.nil? || content_type.blank? || allowed.include?(content_type)++ errors.add(:content_type, :inclusion, value: content_type)+ end+ end+enddiff --git a/spree/core/app/models/spree/import.rb b/spree/core/app/models/spree/import.rbindex 592525a130..37a34da086 100644--- a/spree/core/app/models/spree/import.rb+++ b/spree/core/app/models/spree/import.rb@@ -73,6 +73,7 @@ module Spree# Attachments#has_one_attached :attachment, service: Spree.private_storage_service_name+ signed_id_attachments :attachment## Statusdiff --git a/spree/core/app/models/spree/option_value.rb b/spree/core/app/models/spree/option_value.rbindex 460d027c11..0242b474a1 100644--- a/spree/core/app/models/spree/option_value.rb+++ b/spree/core/app/models/spree/option_value.rb@@ -18,7 +18,8 @@ module Spree## Attachments#- has_one_attached :image+ has_one_attached :image, service: Spree.public_storage_service_name+ signed_id_attachments :image## Associationsdiff --git a/spree/core/app/models/spree/seller.rb b/spree/core/app/models/spree/seller.rbindex dbcb4078bc..073587cc80 100644--- a/spree/core/app/models/spree/seller.rb+++ b/spree/core/app/models/spree/seller.rb@@ -202,6 +202,7 @@ module Spreehas_one_attached :logo, service: Spree.public_storage_service_namehas_one_attached :square_logo, service: Spree.public_storage_service_namehas_one_attached :cover_photo, service: Spree.public_storage_service_name+ signed_id_attachments :logo, :square_logo, :cover_photo## Validationsdiff --git a/spree/core/app/models/spree/seller_requirement_submission.rb b/spree/core/app/models/spree/seller_requirement_submission.rbindex 2d12b9b17e..c599fdd9e2 100644--- a/spree/core/app/models/spree/seller_requirement_submission.rb+++ b/spree/core/app/models/spree/seller_requirement_submission.rb@@ -38,6 +38,7 @@ module Spree# Private, and served only through the admin and seller branches: these# are business registrations and identity documents.has_one_attached :file, service: Spree.private_storage_service_name+ signed_id_attachments :file## Validationsdiff --git a/spree/core/app/models/spree/shipping_label.rb b/spree/core/app/models/spree/shipping_label.rbindex a1060ba7be..2e39fc2cba 100644--- a/spree/core/app/models/spree/shipping_label.rb+++ b/spree/core/app/models/spree/shipping_label.rb@@ -39,6 +39,7 @@ module Spree# merchant's account details, and is served only through an# authenticated, streamed download.has_one_attached :file, service: Spree.private_storage_service_name+ signed_id_attachments :filevalidates :source, inclusion: { in: SOURCES }validates :owner_type, inclusion: { in: OWNER_TYPES }diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rbindex 0bb8cea2b8..900a8876cd 100644--- a/spree/core/app/models/spree/store.rb+++ b/spree/core/app/models/spree/store.rb@@ -387,6 +387,7 @@ module Spree#has_one_attached :logo, service: Spree.public_storage_service_namehas_one_attached :mailer_logo, service: Spree.public_storage_service_name+ signed_id_attachments :logo, :mailer_logo# First-run setup credential (docs/plans/6.0-store-context-and-first-run-setup.md):# printed by the installer, only consulted by the setup endpoint while nodiff --git a/spree/core/app/models/spree/tax_exemption_certificate.rb b/spree/core/app/models/spree/tax_exemption_certificate.rbindex 7b42187563..8f8b794fba 100644--- a/spree/core/app/models/spree/tax_exemption_certificate.rb+++ b/spree/core/app/models/spree/tax_exemption_certificate.rb@@ -27,6 +27,7 @@ module Spree# Confidential, so the private service rather than the public one that# serves product images.has_one_attached :document, service: Spree.private_storage_service_name+ signed_id_attachments :documentvalidates :certificate_number, :reason_code, presence: true# Certificates exist only on legal-entity nodes — a division's purchasesdiff --git a/spree/core/app/services/spree/carts/update.rb b/spree/core/app/services/spree/carts/update.rbindex e86653c225..3647bec383 100644--- a/spree/core/app/services/spree/carts/update.rb+++ b/spree/core/app/services/spree/carts/update.rb@@ -89,7 +89,7 @@ module Spreecart.use_shipping = params[:use_shipping] if params.key?(:use_shipping)assign_preferred_stock_location if params.key?(:preferred_stock_location_id)assign_company if params.key?(:company_id)- assign_po_document if params.key?(:po_document)+ assign_po_document if params.key?(:po_document_signed_id)end# The buyer's purchase order as an ActiveStorage signed blob id — the@@ -97,12 +97,12 @@ module Spree# value detaches, so a buyer can withdraw a document they attached in# error.#- # An abandoned direct upload leaves the blob row behind without its+ # An abandoned presigned upload leaves the blob row behind without its# bytes, and the buyer's client may still send back the signed id it was# handed. ActiveStorage raises a message-less FileNotFoundError for that,# which would otherwise reach the storefront as a bare class name.def assign_po_document- value = params[:po_document]+ value = params[:po_document_signed_id]if value.blank?cart.po_document.detachdiff --git a/spree/core/app/services/spree/orders/create.rb b/spree/core/app/services/spree/orders/create.rbindex 7f52e3819e..f73cc3f18f 100644--- a/spree/core/app/services/spree/orders/create.rb+++ b/spree/core/app/services/spree/orders/create.rb@@ -45,7 +45,7 @@ module Spreerescue ActiveRecord::RecordInvalid => efailure(e.record, e.record.errors.full_messages.to_sentence)rescue ActiveStorage::FileNotFoundError- # An abandoned direct upload leaves the blob row without its bytes.+ # An abandoned presigned upload leaves the blob row without its bytes.# ActiveStorage raises a message-less error for that, which would# otherwise be an unhandled 500 on the Admin API.order ||= @store.orders.new@@ -71,8 +71,8 @@ module Spree}# The buyer's purchase order, when it arrived with the paperwork. A- # signed blob id, so it assigns like any other attribute.- attrs[:po_document] = @params[:po_document] if @params[:po_document].present?+ # signed id, so it assigns like any other attribute.+ attrs[:po_document_signed_id] = @params[:po_document_signed_id] if @params[:po_document_signed_id].present?attrs[:market] = resolve_market if @params[:market_id].present?attrs[:channel] = resolve_channel if @params[:channel_id].present?diff --git a/spree/core/app/services/spree/uploads/assign_stores.rb b/spree/core/app/services/spree/uploads/assign_stores.rbnew file mode 100644index 0000000000..dcfaf52a1e--- /dev/null+++ b/spree/core/app/services/spree/uploads/assign_stores.rb@@ -0,0 +1,92 @@+module Spree+ module Uploads+ # Gives every attached file that has no store the store of the record it+ # is attached to (the 6.0 upgrade, `spree:uploads:assign_stores`).+ #+ # Owners with a `store_id` column are handled with one set-based update per+ # attachment type; the rest (a variant's digital file, a seller's+ # submission) ask {Spree::Uploads.store_id_for} record by record. Files+ # attached nowhere keep no store, and the daily purge leaves them alone.+ #+ # Safe to re-run: only files without a store are touched.+ class AssignStores+ prepend Spree::ServiceModule::Base++ BATCH_SIZE = 1_000++ # @return [Spree::ServiceModule::Result] a hash with `assigned`, the+ # number of files given a store, and `conflicts`, the ids of files+ # attached to records of more than one store, which are reported and+ # left for a person to resolve+ def call+ assigned = record_types.sum do |record_type|+ owner_class = record_type.safe_constantize+ next 0 if owner_class.nil?++ # Renditions and previews are blobs themselves: a set-based update+ # would join the table it updates, which MySQL refuses.+ if owner_class.column_names.include?('store_id') && !record_type.start_with?('ActiveStorage::')+ assign_from_store_column(record_type, owner_class)+ else+ assign_record_by_record(record_type)+ end+ end++ success(assigned: assigned, conflicts: conflicting_blob_ids)+ end++ private++ # Renditions and previews take their store from their original file, so+ # they go last, once the originals have one.+ def record_types+ ActiveStorage::Attachment.distinct.pluck(:record_type).+ sort_by { |record_type| [record_type.start_with?('ActiveStorage::') ? 1 : 0, record_type] }+ end++ # Correlated subqueries rather than UPDATE … FROM, which MySQL and SQLite+ # spell differently. Several attachments of one file in different stores+ # pick one; {#conflicting_blob_ids} reports them.+ def assign_from_store_column(record_type, owner_class)+ attachments_table = ActiveStorage::Attachment.table_name+ owners_table = owner_class.table_name+ owner_store = ActiveStorage::Attachment.+ joins("INNER JOIN #{owners_table} ON #{owners_table}.id = #{attachments_table}.record_id").+ where(record_type: record_type).+ where("#{attachments_table}.blob_id = #{ActiveStorage::Blob.table_name}.id").+ where.not(owners_table => { store_id: nil })++ ActiveStorage::Blob.where(store_id: nil).+ where(id: ActiveStorage::Attachment.where(record_type: record_type).select(:blob_id)).+ where(owner_store.arel.exists).+ update_all(["store_id = (#{owner_store.select("#{owners_table}.store_id").limit(1).to_sql})"])+ end++ # One update per store and batch rather than per file.+ def assign_record_by_record(record_type)+ unassigned = ActiveStorage::Attachment.joins(:blob).+ where(record_type: record_type, ActiveStorage::Blob.table_name => { store_id: nil })++ unassigned.preload(:record).in_batches(of: BATCH_SIZE).sum do |batch|+ batch.select(&:record).group_by { |attachment| Spree::Uploads.store_id_for(attachment.record) }.sum do |store_id, owned|+ next 0 if store_id.nil?++ ActiveStorage::Blob.where(id: owned.map(&:blob_id), store_id: nil).update_all(store_id: store_id)+ end+ end+ end++ def conflicting_blob_ids+ resolvable_types = record_types.select(&:safe_constantize)+ shared_blob_ids = ActiveStorage::Attachment.where(record_type: resolvable_types).group(:blob_id).having('COUNT(*) > 1').pluck(:blob_id)++ shared_blob_ids.each_slice(BATCH_SIZE).flat_map do |blob_ids|+ ActiveStorage::Attachment.where(blob_id: blob_ids, record_type: resolvable_types).includes(:record).group_by(&:blob_id).filter_map do |blob_id, blob_attachments|+ store_ids = blob_attachments.filter_map { |attachment| attachment.record && Spree::Uploads.store_id_for(attachment.record) }+ blob_id if store_ids.map(&:to_s).uniq.size > 1+ end+ end+ end+ end+ end+enddiff --git a/spree/core/app/workflows/spree/shipping_labels/record.rb b/spree/core/app/workflows/spree/shipping_labels/record.rbindex a1666764d6..a1e9581a16 100644--- a/spree/core/app/workflows/spree/shipping_labels/record.rb+++ b/spree/core/app/workflows/spree/shipping_labels/record.rb@@ -13,7 +13,7 @@ module Spreeattr_reader :shipping_label# @param owner [Spree::Fulfillment, Spree::Return]- # @param file [ActionDispatch::Http::UploadedFile, String] the file, or a signed blob id from a direct upload+ # @param file [ActionDispatch::Http::UploadedFile, String] the file, or a signed id from POST /files# @param tracking_number [String] the number printed on the label# @param carrier [String, nil] free text; detected from the number when omitted# @param service [String, nil]@@ -69,7 +69,7 @@ module Spreefailure(@shipping_label) unless @shipping_label.saveend- # A direct-upload blob carries the type the client declared, which the+ # An uploaded blob carries the type the client declared, which the# attachment validator re-decides from the bytes; either way the# extension is the merchant-visible answer, so it wins when it names a# format Spree knows.diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 4106b26001..c92dcb10ac 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -1143,7 +1143,6 @@ en:pickup:store_pickup: Store Pickuppo_document_invalid: A purchase order document must be a PDF, image or Word file of %{size} or less.- po_document_invalid_signed_id: The purchase order document reference is not valid.po_document_missing: This order has no attached purchase order document.po_document_too_large: is larger than %{size}.po_document_upload_incomplete: The purchase order document was not uploaded completely. Please try attaching it again.@@ -1676,6 +1675,7 @@ en:errors:already_purchased: This parcel already has an active shipping labelfile_fetch_failed: The label file could not be fetched from the carrier (HTTP %{status})+ file_renamed: Send the uploaded label's signed id as file_signed_idfile_required: An uploaded label needs a fileno_file_url: The carrier did not provide a file for this labelnot_refund_requested: Only a label awaiting the carrier's refund decision can be confirmed refunded@@ -1795,6 +1795,8 @@ en:type: Typeunable_to_connect_to_gateway: Unable to connect to gateway.updated_at: Updated at+ upload_reference_invalid: A signed reference in this request is invalid or has expired. For a file, upload it again.+ upload_wrong_visibility: must be uploaded with %{visibility} visibilityurl: URLuser: Uservalidation:diff --git a/spree/core/db/migrate/20261010000001_add_store_id_to_active_storage_blobs.rb b/spree/core/db/migrate/20261010000001_add_store_id_to_active_storage_blobs.rbnew file mode 100644index 0000000000..caef16e653--- /dev/null+++ b/spree/core/db/migrate/20261010000001_add_store_id_to_active_storage_blobs.rb@@ -0,0 +1,12 @@+# Records which store owns every uploaded file, so a file from one store cannot+# be attached in another and storage can be measured and cleaned up per store.+# Active Storage ignores columns it does not define. Existing rows are filled+# in by `spree:uploads:assign_stores` in the 6.0 upgrade.+class AddStoreIdToActiveStorageBlobs < ActiveRecord::Migration[8.1]+ def change+ return unless table_exists?(:active_storage_blobs)+ return if column_exists?(:active_storage_blobs, :store_id)++ add_reference :active_storage_blobs, :store, null: true, index: true+ end+enddiff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rbindex 2a3d457588..8da823a81c 100644--- a/spree/core/lib/spree/core.rb+++ b/spree/core/lib/spree/core.rb@@ -636,6 +636,7 @@ require 'spree/workflow'require 'spree/reporting'require 'spree/events'require 'spree/store_scope_guard'+require 'spree/uploads'# Not autoloaded from app/: the registry keeps registered steps in# class-level state, which a reload would discard.diff --git a/spree/core/lib/spree/core/configuration.rb b/spree/core/lib/spree/core/configuration.rbindex 2bdd6cb7ce..f39c2c465e 100644--- a/spree/core/lib/spree/core/configuration.rb+++ b/spree/core/lib/spree/core/configuration.rb@@ -119,6 +119,19 @@ module Spree# requirement, in bytes. Small on purpose: these are certificates and# registrations, and an unbounded upload is a way to fill a disk.preference :max_seller_document_upload_size, :integer, default: 20_971_520, env: 'SPREE_MAX_SELLER_DOCUMENT_UPLOAD_SIZE' # 20 MB++ # Largest file the Admin and Seller APIs accept for upload straight to+ # storage, in bytes. Digital products (courses, archives) can be large.+ preference :max_upload_size, :integer, default: 5_368_709_120, env: 'SPREE_MAX_UPLOAD_SIZE' # 5 GB++ # Largest file accepted as bytes in the upload request itself, in bytes.+ # Lower, because those bytes pass through the application.+ preference :max_multipart_upload_size, :integer, default: 10_485_760, env: 'SPREE_MAX_MULTIPART_UPLOAD_SIZE' # 10 MB++ # Days an uploaded file that was never attached to anything is kept+ # before the daily purge deletes it. Longer than an upload reference+ # stays valid (one day), so nothing a client can still attach is lost.+ preference :unattached_upload_retention_days, :integer, default: 2, env: 'SPREE_UNATTACHED_UPLOAD_RETENTION_DAYS'preference :non_expiring_credit_types, :array, default: [], deprecated: 'Nothing reads this in Spree 6 — store credits no longer carry a category, and expiry lives on Spree::GiftCard'preference :products_per_page, :integer, default: 12, deprecated: 'Nothing reads this in Spree 6 — pass per_page to the API instead'preference :restock_inventory, :boolean, default: true, deprecated: 'Restocking is decided per line item by Spree::ReturnLineItem#resellable'diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rbindex e82c951b2c..bb1f6aae8d 100644--- a/spree/core/lib/spree/core/engine.rb+++ b/spree/core/lib/spree/core/engine.rb@@ -591,6 +591,13 @@ module Spree]end+ # Records which store owns every uploaded file, and reports attaching a+ # file to another store's record (docs/plans/6.0-uploads-and-file-ownership.md).+ initializer 'spree.active_storage.store_ownership' do+ ActiveSupport.on_load(:active_storage_blob) { include Spree::Uploads::BlobStoreOwnership }+ ActiveSupport.on_load(:active_storage_attachment) { include Spree::Uploads::AttachmentStoreCheck }+ end+initializer 'spree.core.checking_migrations' do |app|app.config.after_initialize doMigrations.new(config, engine_name).check unless Rails.env.test? || Spree::Config.disable_migration_checkdiff --git a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.ymlindex ed1d181c85..a3f4c42fa9 100644--- a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml+++ b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml@@ -760,3 +760,22 @@ steps:this step again.Idempotent.++ - id: assign_upload_stores+ name: "Record which store owns every uploaded file"+ task: "spree:uploads:assign_stores"+ notes: |+ Spree 6.0 records the store that owns every uploaded file, so a file from+ one store cannot be attached in another and storage can be measured and+ cleaned up per store. New files get their store when they are uploaded;+ this gives existing files the store of the record they are attached to.++ Files attached in more than one store are listed and left unchanged for+ you to resolve. Files attached to nothing keep no store and are left+ alone: the daily purge of never-attached uploads+ (Spree::Uploads::PurgeUnattachedJob, see the upgrade guide) only+ deletes files that belong to a store.++ Run AFTER the steps that create or move attachments (media, categories,+ returns), so their files are covered. Idempotent — files that already+ have a store are skipped.diff --git a/spree/core/lib/spree/uploads.rb b/spree/core/lib/spree/uploads.rbnew file mode 100644index 0000000000..aede465dfe--- /dev/null+++ b/spree/core/lib/spree/uploads.rb@@ -0,0 +1,101 @@+module Spree+ # Store ownership of uploaded files (docs/plans/6.0-uploads-and-file-ownership.md).+ #+ # Every `ActiveStorage::Blob` records the store that owns it, and attaching a+ # blob to a record of another store is reported. Spree 6.0 only logs; 6.1+ # refuses, so one release of logs finds every path that still creates blobs+ # without a store.+ module Uploads+ # How long an upload reference (`signed_id`) stays attachable.+ SIGNED_ID_EXPIRY = 1.day++ # Mints an expiring upload reference for +blob+.+ #+ # @param blob [ActiveStorage::Blob]+ # @return [String] an opaque reference clients pass back unchanged+ def self.signed_id_for(blob)+ blob.signed_id(expires_in: SIGNED_ID_EXPIRY)+ end++ # The store owning +record+, or nil for records that belong to no store+ # (admin users, customers).+ #+ # @param record [ActiveRecord::Base]+ # @return [Integer, String, nil]+ def self.store_id_for(record)+ return record.id if record.is_a?(Spree::Store)+ # A processed rendition belongs to whoever owns its original.+ return record.blob&.store_id if record.is_a?(ActiveStorage::VariantRecord)+ return record.store_id if record.has_attribute?(:store_id)++ record.try(:store)&.id+ rescue Module::DelegationError+ # An owner whose parent is gone (a digital asset on a deleted variant)+ # has no store to compare against.+ nil+ end++ module BlobStoreOwnership+ extend ActiveSupport::Concern++ included do+ before_create :assign_current_store+ end++ private++ # Reads the store a request or job declared, never the default-store+ # fallback: guessing the default would hide exactly the creation paths+ # the 6.0 logs are meant to find.+ def assign_current_store+ return unless has_attribute?(:store_id)++ self.store_id ||= Spree::Current.attributes[:store]&.id+ end+ end++ module AttachmentStoreCheck+ extend ActiveSupport::Concern++ included do+ before_validation :adopt_owner_store, on: :create+ after_create :check_blob_store+ end++ private++ # A file Spree just made from bytes it holds (an export, a purchased+ # label) is created in the same call that attaches it, so it simply+ # takes its owner's store, written with the file itself.+ def adopt_owner_store+ return unless blob&.new_record? && blob.has_attribute?(:store_id) && record++ blob.store_id ||= owner_store_id+ end++ def check_blob_store+ return unless blob&.has_attribute?(:store_id) && record+ return if owner_store_id.nil?++ if blob.store_id.nil?+ report_store_mismatch('has no store')+ elsif blob.store_id.to_s != owner_store_id.to_s+ report_store_mismatch("belongs to store #{blob.store_id}")+ end+ end++ def owner_store_id+ return @owner_store_id if defined?(@owner_store_id)++ @owner_store_id = Spree::Uploads.store_id_for(record)+ end++ def report_store_mismatch(reason)+ Rails.logger.warn(+ "[Spree] Attached file #{blob.id} #{reason}, but #{record_type}##{record_id} (#{name}) " \+ "belongs to store #{owner_store_id}. Spree 6.1 refuses this attachment."+ )+ end+ end+ end+enddiff --git a/spree/core/lib/tasks/uploads.rake b/spree/core/lib/tasks/uploads.rakenew file mode 100644index 0000000000..10c4afbb79--- /dev/null+++ b/spree/core/lib/tasks/uploads.rake@@ -0,0 +1,19 @@+namespace :spree do+ namespace :uploads do+ desc <<~DESC+ Gives every attached file the store of the record it is attached to+ (Spree 6.0). Idempotent — files that already have a store are skipped.+ Files attached in more than one store are listed, not changed.+ DESC+ task assign_stores: :environment do+ result = Spree::Uploads::AssignStores.call+ puts " Assigned a store to #{result.value[:assigned]} file(s)."++ conflicts = result.value[:conflicts]+ next if conflicts.empty?++ puts " #{conflicts.size} file(s) are attached to records of more than one store and were left as they are:"+ conflicts.each { |blob_id| puts " active_storage_blobs.id = #{blob_id}" }+ end+ end+enddiff --git a/spree/core/spec/jobs/spree/uploads/purge_unattached_job_spec.rb b/spree/core/spec/jobs/spree/uploads/purge_unattached_job_spec.rbnew file mode 100644index 0000000000..f47a3e789d--- /dev/null+++ b/spree/core/spec/jobs/spree/uploads/purge_unattached_job_spec.rb@@ -0,0 +1,37 @@+require 'spec_helper'++RSpec.describe Spree::Uploads::PurgeUnattachedJob do+ def create_blob(created_at:, store_id: @default_store.id)+ ActiveStorage::Blob.create_and_upload!(io: StringIO.new('bytes'), filename: 'file.png', content_type: 'image/png').tap do |blob|+ blob.update_columns(created_at: created_at, store_id: store_id)+ end+ end++ it 'deletes files never attached once they are past the retention period' do+ stale = create_blob(created_at: 3.days.ago)+ fresh = create_blob(created_at: 1.day.ago)+ attached = create_blob(created_at: 3.days.ago)+ ActiveStorage::Attachment.create!(name: 'image', record: create(:category), blob: attached)++ described_class.perform_now++ expect(ActiveStorage::Blob.where(id: [stale.id, fresh.id, attached.id])).to contain_exactly(fresh, attached)+ end++ it 'leaves files that belong to no store, which are not Spree uploads' do+ blob = create_blob(created_at: 3.days.ago, store_id: nil)++ described_class.perform_now++ expect(ActiveStorage::Blob.exists?(blob.id)).to be(true)+ end++ it 'reads the retention period from configuration' do+ allow(Spree::Config).to receive(:unattached_upload_retention_days).and_return(7)+ blob = create_blob(created_at: 3.days.ago)++ described_class.perform_now++ expect(ActiveStorage::Blob.exists?(blob.id)).to be(true)+ end+enddiff --git a/spree/core/spec/lib/spree/uploads_spec.rb b/spree/core/spec/lib/spree/uploads_spec.rbnew file mode 100644index 0000000000..528a453ab2--- /dev/null+++ b/spree/core/spec/lib/spree/uploads_spec.rb@@ -0,0 +1,76 @@+require 'spec_helper'++RSpec.describe Spree::Uploads do+ let(:store) { @default_store }+ let(:other_store) { create(:store) }+ let(:category) { create(:category, store: store) }++ def create_blob(store_id: nil)+ ActiveStorage::Blob.create_and_upload!(io: StringIO.new('bytes'), filename: 'file.png', content_type: 'image/png').tap do |blob|+ blob.update_column(:store_id, store_id)+ end+ end++ describe 'store assignment on creation' do+ it 'takes the store a request or job declared' do+ Spree::Current.store = other_store++ expect(create_blob_without_override.store_id).to eq(other_store.id)+ end++ it 'leaves the store empty rather than guessing the default' do+ expect(create_blob_without_override.store_id).to be_nil+ end++ def create_blob_without_override+ ActiveStorage::Blob.create_and_upload!(io: StringIO.new('bytes'), filename: 'file.png', content_type: 'image/png')+ end+ end++ describe 'store check on attachment' do+ it 'gives a file created for the attachment its owner store' do+ seller = create(:seller, store: store)+ seller.logo.attach(io: File.open(Spree::Core::Engine.root.join('spec/fixtures/thinking-cat.jpg')),+ filename: 'logo.jpg', content_type: 'image/jpeg')++ expect(seller.reload.logo.blob.store_id).to eq(store.id)+ end++ it 'attaches a file of the same store quietly' do+ expect(Rails.logger).not_to receive(:warn)++ category.update!(image_signed_id: create_blob(store_id: store.id).signed_id)+ end++ it 'logs, without refusing, a file of another store' do+ # Category images also become media library placements, which report too.+ expect(Rails.logger).to receive(:warn).with(/belongs to store #{other_store.id}.*Spree 6.1 refuses/).at_least(:once)++ category.update!(image_signed_id: create_blob(store_id: other_store.id).signed_id)++ expect(category.reload.image).to be_attached+ end++ it 'logs an existing file without a store' do+ expect(Rails.logger).to receive(:warn).with(/has no store/).at_least(:once)++ category.update!(image_signed_id: create_blob.signed_id)+ end++ it 'does not check records that belong to no store' do+ expect(Rails.logger).not_to receive(:warn)++ create(:admin_user).update!(avatar_signed_id: create_blob(store_id: other_store.id).signed_id)+ end+ end++ describe '.signed_id_for' do+ it 'mints a reference that stops resolving after a day' do+ signed_id = described_class.signed_id_for(create_blob)++ Timecop.travel(25.hours.from_now) do+ expect(ActiveStorage::Blob.find_signed(signed_id)).to be_nil+ end+ end+ end+enddiff --git a/spree/core/spec/models/concerns/spree/signed_id_attachments_spec.rb b/spree/core/spec/models/concerns/spree/signed_id_attachments_spec.rbnew file mode 100644index 0000000000..7153994590--- /dev/null+++ b/spree/core/spec/models/concerns/spree/signed_id_attachments_spec.rb@@ -0,0 +1,30 @@+require 'spec_helper'++RSpec.describe Spree::SignedIdAttachments do+ let(:certificate) { create(:tax_exemption_certificate) }++ def pdf_blob(service_name: Spree.private_storage_service_name)+ ActiveStorage::Blob.create_and_upload!(io: StringIO.new('%PDF-1.4 certificate'), filename: 'certificate.pdf',+ content_type: 'application/pdf', service_name: service_name)+ end++ it 'attaches a file through <slot>_signed_id and removes it with nil' do+ certificate.update!(document_signed_id: pdf_blob.signed_id)+ expect(certificate.reload.document).to be_attached++ certificate.update!(document_signed_id: nil)+ expect(certificate.reload.document).not_to be_attached+ end++ it 'refuses a file stored with the other visibility' do+ certificate.document_signed_id = pdf_blob(service_name: 'local').signed_id++ expect(certificate).not_to be_valid+ expect(certificate.errors[:document]).to include('must be uploaded with private visibility')+ end++ it 'names the API field a slot is written with' do+ expect(Spree::TaxExemptionCertificate.signed_id_attribute_for(:document)).to eq('document_signed_id')+ expect(Spree::TaxExemptionCertificate.signed_id_attribute_for(:certificate_number)).to be_nil+ end+enddiff --git a/spree/core/spec/services/spree/carts/update_spec.rb b/spree/core/spec/services/spree/carts/update_spec.rbindex 510ab549cd..3ed0dff199 100644--- a/spree/core/spec/services/spree/carts/update_spec.rb+++ b/spree/core/spec/services/spree/carts/update_spec.rb@@ -1008,7 +1008,7 @@ module Spreeendend- # An abandoned direct upload leaves the blob row behind without its bytes,+ # An abandoned presigned upload leaves the blob row behind without its bytes,# and the buyer's client may still send back the signed id it was handed.describe 'a purchase order document whose upload never completed' dolet(:orphan_blob) do@@ -1019,7 +1019,7 @@ module Spreeendit 'reports a readable message instead of an exception class name' do- result = described_class.call(cart: cart, params: { po_document: orphan_blob.signed_id })+ result = described_class.call(cart: cart, params: { po_document_signed_id: orphan_blob.signed_id })expect(result).to be_failureexpect(result.error.to_s).to include(I18n.t('spree.po_document_upload_incomplete'))diff --git a/spree/core/spec/services/spree/orders/create_spec.rb b/spree/core/spec/services/spree/orders/create_spec.rbindex 967b8f4545..5e54d6e8c6 100644--- a/spree/core/spec/services/spree/orders/create_spec.rb+++ b/spree/core/spec/services/spree/orders/create_spec.rb@@ -280,7 +280,7 @@ module Spreeresult = nilexpect {result = described_class.call(- store: store, params: { email: '[email protected]', po_document: orphan_blob.signed_id }+ store: store, params: { email: '[email protected]', po_document_signed_id: orphan_blob.signed_id })}.not_to raise_errordiff --git a/spree/core/spec/services/spree/uploads/assign_stores_spec.rb b/spree/core/spec/services/spree/uploads/assign_stores_spec.rbnew file mode 100644index 0000000000..5bd29c3ff0--- /dev/null+++ b/spree/core/spec/services/spree/uploads/assign_stores_spec.rb@@ -0,0 +1,68 @@+require 'spec_helper'++RSpec.describe Spree::Uploads::AssignStores do+ let(:store) { @default_store }+ let(:other_store) { create(:store) }++ def storeless_blob+ ActiveStorage::Blob.create_and_upload!(io: StringIO.new('bytes'), filename: 'file.png', content_type: 'image/png').tap do |blob|+ blob.update_column(:store_id, nil)+ end+ end++ def attach_without_check(record, slot, blob)+ ActiveStorage::Attachment.insert_all!([{ name: slot, record_type: record.class.base_class.name, record_id: record.id,+ blob_id: blob.id, created_at: Time.current }])+ end++ it 'gives attached files the store of their owner' do+ category_blob = storeless_blob+ attach_without_check(create(:category, store: other_store), 'image', category_blob)+ seller_blob = storeless_blob+ attach_without_check(create(:seller, store: other_store), 'logo', seller_blob)+ unattached = storeless_blob++ result = described_class.call++ expect(result.value[:assigned]).to eq(2)+ expect(category_blob.reload.store_id).to eq(other_store.id)+ expect(seller_blob.reload.store_id).to eq(other_store.id)+ expect(unattached.reload.store_id).to be_nil+ end++ it 'asks owners without a store column record by record' do+ blob = storeless_blob+ attach_without_check(other_store, 'logo', blob)++ described_class.call++ expect(blob.reload.store_id).to eq(other_store.id)+ end++ it 'gives a preview the store of its original once the original has one' do+ original = storeless_blob+ attach_without_check(create(:category, store: other_store), 'image', original)+ preview = storeless_blob+ attach_without_check(original, 'preview_image', preview)++ described_class.call++ expect(preview.reload.store_id).to eq(other_store.id)+ end++ it 'reports a file attached in two stores' do+ blob = storeless_blob+ attach_without_check(create(:category, store: store), 'image', blob)+ attach_without_check(create(:category, store: other_store), 'image', blob)++ expect(described_class.call.value[:conflicts]).to eq([blob.id])+ end++ it 'leaves files that already have a store alone' do+ blob = storeless_blob+ blob.update_column(:store_id, store.id)+ attach_without_check(create(:category, store: other_store), 'image', blob)++ expect { described_class.call }.not_to(change { blob.reload.store_id })+ end+end