Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Documented and typed every filterable list endpoint

Damian Legawieca90a9ccc68ca
diff --git a/.changeset/typed-filters-every-list.md b/.changeset/typed-filters-every-list.md
new file mode 100644
index 0000000000..de71626c54
--- /dev/null
+++ b/.changeset/typed-filters-every-list.md
@@ -0,0 +1,8 @@
+---
+"@spree/sdk": minor
+"@spree/admin-sdk": minor
+"@spree/seller-sdk": minor
+"@spree/dashboard": patch
+---
+
+Every filterable list method now takes typed filter and sort parameters, including returns, claims, exchanges, custom fields, digital links, payouts, imports and the rest that still accepted any key. The building block for custom field value filters is now `CustomFieldValueFilters`, so it no longer hides the generated filters for custom field lists. The product digital files list now pages by 25 as intended.
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 50e0e7de56..c719dbde64 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -3950,6 +3950,115 @@ paths:
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -5865,6 +5974,115 @@ paths:
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -6036,6 +6254,230 @@ paths:
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `accepted` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `purpose` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `recorded_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `source` | One of `checkout`, `registration`, `account`, `admin`, `newsletter`, `anonymization`, `unknown`, `import`, `storefront` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: consent_UkLWZg9DAJ
+ purpose: terms_of_service
+ source: registration
+ accepted: true
+ ip_address:
+ created_at: '2026-01-15T12:00:00.000Z'
+ recorded_at: '2026-01-15T12:00:00Z'
+ documents: []
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `kind` | One of `access`, `erasure` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `requested_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: dsr_UkLWZg9DAJ
+ number: DSR1001
+ kind: access
+ status: pending
+ requested_at: '2026-01-15T12:00:00Z'
+ completed_at:
+ expires_at:
+ error_message:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ customer_id: cust_UkLWZg9DAJ
+ requested_by_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -6154,7 +6596,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 5 Lovely Street
+ address1: 11 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6373,7 +6815,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 7 Lovely Street
+ address1: 13 Lovely Street
address2: Northwest
postal_code: '10118'
city: Manhattan
@@ -7091,6 +7533,105 @@ paths:
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: txi_UkLWZg9DAJ
+ kind: eu_vat
+ value: DE100000016
+ validation_status:
+ validation_evidence:
+ source:
+ validated_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ validatable: false
+ customer_id: cust_UkLWZg9DAJ
+ cart_id:
+ order_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -13960,6 +14501,115 @@ paths:
error:
code: validation_error
message: Market cannot be deleted
+ "/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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -14082,7 +14732,7 @@ paths:
example:
data:
- id: opt_UkLWZg9DAJ
- name: foo-size-1
+ name: foo-size-6
label: Size
position: 1
kind: dropdown
@@ -14306,7 +14956,7 @@ paths:
application/json:
example:
id: opt_UkLWZg9DAJ
- name: foo-size-5
+ name: foo-size-10
label: Size
position: 1
kind: dropdown
@@ -14380,7 +15030,7 @@ paths:
application/json:
example:
id: opt_UkLWZg9DAJ
- name: foo-size-7
+ name: foo-size-12
label: Updated Label
position: 1
kind: dropdown
@@ -14486,33 +15136,161 @@ paths:
responses:
'204':
description: option type deleted
- "/api/v3/admin/orders/{order_id}/tax_lines":
+ "/api/v3/admin/claims":
get:
- summary: List tax lines
+ summary: List claims
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Typed tax rows on the order. Read-only — written exclusively by the tax provider.
+ Every damage or missing-item claim in the store, across all orders.
**Required scope:** `read_orders` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ 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
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Filter 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).
- const { data: taxLines } = await client.orders.taxLines.list('or_abc123')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/tax_lines
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: open
+ resolution:
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.00'
+ approved_at:
+ resolved_at:
+ denied_at:
+ canceled_at:
+ memo: Arrived with a cracked screen
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_by_id:
+ created_by_type:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **Required scope:** `read_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -14530,6 +15308,24 @@ paths:
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
@@ -14544,60 +15340,72 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `included` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `provider_id` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `taxability_reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `country_code`, `created_at`, `id`, `included`, `provider_id`, `state_code`, `taxability_reason`, `updated_at`. Prefix a field with `-` to sort descending.
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
+
+ </Accordion>
+
+ **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: TaxLine
+ table: Claim
sortable:
- - country_code
- created_at
- id
- - included
- - provider_id
- - state_code
- - taxability_reason
+ - number
+ - status
- updated_at
responses:
'200':
- description: tax lines found
+ description: claims listed
content:
application/json:
example:
data:
- - id: tl_UkLWZg9DAJ
- label: VAT 15%
- included: false
- credit: false
- rate: '0.15'
- tax_rate_id:
- line_item_id: li_UkLWZg9DAJ
- fulfillment_id:
- fee_id:
- return_line_item_id:
- claim_line_item_id:
- exchange_line_item_id:
- amount: '1.50'
- provider_id: internal
+ - id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: open
+ resolution:
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.00'
+ approved_at:
+ resolved_at:
+ denied_at:
+ canceled_at:
+ memo: Arrived with a cracked screen
metadata: {}
- taxability_reason:
- country_code:
- state_code:
- data: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- original_tax_line_id:
+ created_by_id:
+ created_by_type:
meta:
page: 1
limit: 25
@@ -14608,33 +15416,30 @@ paths:
in: 1
previous:
next:
- "/api/v3/admin/orders/{order_id}/discounts":
+ 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 discounts
+ summary: List order custom fields
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Typed discount rows (promotion-sourced and manual) on the order.
+ Returns the order's custom field values.
**Required scope:** `read_orders` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: discounts } = await client.orders.discounts.list('or_abc123')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/discounts
parameters:
- name: x-spree-api-key
in: header
@@ -14649,7 +15454,20 @@ paths:
- name: order_id
in: path
required: true
- description: Order prefixed ID
+ 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
@@ -14676,31 +15494,27 @@ paths:
**Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: Discount
+ table: CustomField
sortable:
- created_at
- id
- updated_at
responses:
'200':
- description: discounts found
+ description: custom fields found
content:
application/json:
example:
data:
- - id: disc_UkLWZg9DAJ
- label: Loyalty
- kind: manual
- code:
- value_type:
- value:
- promotion_id:
- line_item_id: li_UkLWZg9DAJ
- fulfillment_id:
- amount: "-2.00"
- metadata: {}
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
@@ -14711,39 +15525,30 @@ paths:
in: 1
previous:
next:
- post:
- summary: Create manual discount
+ 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: |-
- 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.
-
- **Required scope:** `write_orders` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Returns the download links issued for digital products bought in this store, newest first.
- // Line-item discount; omit line_item_id to distribute across the order.
- const { data: discounts } = await client.orders.discounts.create('or_abc123', {
- label: 'Customer appeasement',
- value: '10',
- value_type: 'flat',
- line_item_id: 'item_abc123',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/discounts -d '{"label":"Customer
- appeasement","value":"10","value_type":"flat","line_item_id":"item_abc123"}'
+ **Required scope:** `read_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -14753,343 +15558,102 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
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:
- example:
- data:
- - id: disc_UkLWZg9DAJ
- label: Appeasement
- kind: manual
- code:
- value_type: flat
- value: '3.00'
- promotion_id:
- line_item_id: li_UkLWZg9DAJ
- fulfillment_id:
- amount: "-3.00"
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- '422':
- description: invalid discount
- content:
- application/json:
- example:
- error:
- code: invalid_money_format
- message: value must be a decimal string like "19.99"
- details:
- value:
- - must be a decimal string like "19.99"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- label:
- type: string
- example: Customer appeasement
- value:
- type: string
- example: '10.00'
- value_type:
- type: string
- enum:
- - flat
- - percent
- example: flat
- line_item_id:
- type: string
- nullable: true
- example: item_abc123
- description: Target line item; omit to distribute order-level
- required:
- - label
- - value
- "/api/v3/admin/orders/{order_id}/fees":
- 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.
-
- **Required scope:** `write_orders` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const fee = await client.orders.fees.create('or_abc123', {
- label: 'Gift wrap',
- amount: '4.00',
- kind: 'gift_wrap',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":"4.00","kind":"gift_wrap"}'
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ - name: page
+ in: query
+ required: false
+ description: Page number
schema:
- type: string
- - name: Authorization
- in: header
- required: true
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: Number of records per page
schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order prefixed ID
+ type: integer
+ - name: q
+ in: query
+ required: false
+ style: deepObject
+ explode: true
schema:
- type: string
- responses:
- '201':
- description: fee created
- content:
- application/json:
- example:
- id: fee_UkLWZg9DAJ
- label: Gift wrap
- kind: gift_wrap
- line_item_id:
- fulfillment_id:
- amount: '4.00'
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- '422':
- description: invalid fee
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Kind is not included in the list
- details:
- kind:
- - value: nonsense
- code: inclusion
- message: is not included in the list
- specific: false
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- label:
- type: string
- example: Gift wrap
- amount:
- type: string
- example: '4.00'
- kind:
- type: string
- enum:
- - surcharge
- - handling
- - gift_wrap
- - cod
- - payment
- - duty
- - exchange
- example: gift_wrap
- description: Defaults to 'surcharge'
- line_item_id:
- type: string
- nullable: true
- fulfillment_id:
- type: string
- nullable: true
- required:
- - label
- - amount
- "/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.
+ type: object
+ additionalProperties: true
+ description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
+ Filters above for the list.
+ x-mint:
+ content: |-
+ ## Filters
- **Required scope:** `write_gift_cards` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Filter 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).
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- await client.orders.giftCards.apply('or_UkLWZg9DAJ', {
- code: 'GIFT-XXXX-YYYY',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'
- parameters:
- - name: x-spree-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
+ **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:
- '201':
- description: gift card applied
+ '200':
+ description: digital links found
content:
application/json:
example:
- id: gc_UkLWZg9DAJ
- code: "************2F41"
- status: active
- currency: USD
- amount: '10.00'
- amount_used: '10.00'
- amount_authorized: '0.00'
- amount_remaining: '0.00'
- expires_at:
- redeemed_at:
- expired: false
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- customer_id:
- created_by_id:
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - code
- properties:
- code:
- type: string
- description: Gift card code
- example: GIFT-XXXX-YYYY
- "/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.
-
- **Required scope:** `write_gift_cards` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /orders/{order_id}/gift_cards/{id}
- parameters:
- - name: x-spree-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":
+ data:
+ - id: dl_UkLWZg9DAJ
+ access_counter: 0
+ filename: thinking-cat.jpg
+ content_type: image/jpeg
+ download_url: "/api/v3/store/digital_links/Sh7B5YVQvB8N7t2mhgUnL9Lv"
+ expires_at: '2026-01-22T12:00:00Z'
+ authorizable: true
+ expired: false
+ access_limit_exceeded: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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 order items
+ summary: List exchanges
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns all line items for an order.
+ Every exchange in the store, across all orders.
**Required scope:** `read_orders` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/items
parameters:
- name: x-spree-api-key
in: header
@@ -15099,29 +15663,26 @@ paths:
- 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
+ - name: q[search]
+ in: query
+ required: false
schema:
type: string
- - name: expand
+ description: Matches any of number (partial, case-insensitive).
+ - name: page
in: query
required: false
- description: Comma-separated associations to expand (e.g., variant, variant.product).
- Use dot notation for nested expand (max 4 levels).
+ description: Page number
schema:
- type: string
- - name: fields
+ type: integer
+ - name: limit
in: query
required: false
- description: Comma-separated list of fields to include (e.g., quantity,price,total).
- id is always included.
+ description: Number of records per page
schema:
- type: string
+ type: integer
- name: q
in: query
required: false
@@ -15136,26 +15697,15 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `additional_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `discount_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `included_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `non_taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `pre_tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
<Accordion title="Filters through associations">
@@ -15168,6 +15718,7 @@ paths:
| `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
| `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
| `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
| `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
@@ -15175,88 +15726,43 @@ paths:
| `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
| `order_store_` | `created_at`, `id`, `name`, `updated_at` |
| `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
- | `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
- | `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` |
- | `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
- | `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
- | `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
- | `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+ | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
- **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.
+ **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: LineItem
+ table: Exchange
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
+ - number
+ - status
- updated_at
- - variant_id
responses:
'200':
- description: items found
+ description: exchanges listed
content:
application/json:
example:
data:
- - id: li_UkLWZg9DAJ
- variant_id: variant_gbHJdmfrXB
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 2
- currency: USD
- name: Product 479180
- slug: product-479180
- options_text: 'Size: S'
- price: '10.00'
- total: '20.00'
- adjustment_total: '0.00'
- additional_tax_total: '0.00'
- included_tax_total: '0.00'
- discount_total: '0.00'
- pre_tax_amount: '20.00'
- discounted_amount: '20.00'
- compare_at_amount:
- thumbnail_url:
- option_values:
- - id: optval_UkLWZg9DAJ
- option_type_id: opt_UkLWZg9DAJ
- name: size-1
- label: S
- position: 1
- color_code:
- option_type_name: foo-size-10
- option_type_label: Size
- image_url:
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- digital_links: []
+ - id: exch_UkLWZg9DAJ
+ number: EX1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ price_difference: '9.99'
+ approved_at:
+ received_at:
+ fulfilled_at:
+ canceled_at:
+ memo: Wrong size
metadata: {}
- price_source:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- catalog_price: '19.99'
- price_list_id:
- price_list_name:
- catalog_id:
- catalog_name:
- cost_price: '17.00'
- tax_category_id: taxcat_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ created_by_id:
+ created_by_type:
meta:
page: 1
limit: 25
@@ -15267,35 +15773,30 @@ paths:
in: 1
previous:
next:
- post:
- summary: Add an item
+ 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: |-
- Adds a new line item to the order.
-
- **Required scope:** `write_orders` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ The exchanges opened on one order.
- const item = await client.orders.items.create('or_UkLWZg9DAJ', {
- variant_id: 'variant_k5nR8xLq',
- quantity: 2,
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'
+ **Required scope:** `read_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -15305,90 +15806,144 @@ paths:
- 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
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `requested`, `approved`, `received`, `fulfilled`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
+
+ </Accordion>
+
+ **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:
- '201':
- description: item added
+ '200':
+ description: exchanges listed
content:
application/json:
example:
- id: li_gbHJdmfrXB
- variant_id: variant_VqXmZF31wY
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 3
- currency: USD
- name: Product 4999
- slug: product-4999
- options_text: 'Size: S'
- price: '19.99'
- total: '59.97'
- adjustment_total: '0.00'
- additional_tax_total: '0.00'
- included_tax_total: '0.00'
- discount_total: '0.00'
- pre_tax_amount: '59.97'
- discounted_amount: '59.97'
- compare_at_amount:
- thumbnail_url:
- option_values:
- - id: optval_gbHJdmfrXB
- option_type_id: opt_gbHJdmfrXB
- name: size-3
- label: S
- position: 1
- color_code:
- option_type_name: foo-size-12
- option_type_label: Size
- image_url:
+ data:
+ - id: exch_UkLWZg9DAJ
+ number: EX1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ price_difference: '9.99'
+ approved_at:
+ received_at:
+ fulfilled_at:
+ canceled_at:
+ memo: Wrong size
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- digital_links: []
- metadata: {}
- price_source:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- catalog_price: '19.99'
- price_list_id:
- price_list_name:
- catalog_id:
- catalog_name:
- cost_price: '17.00'
- tax_category_id: taxcat_UkLWZg9DAJ
- 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}":
+ stock_location_id: sloc_UkLWZg9DAJ
+ created_by_id:
+ created_by_type:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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: Show an item
+ summary: List tax lines
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns details of a specific line item.
+ Typed tax rows on the order. Read-only — written exclusively by the tax provider.
**Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
@@ -15402,10 +15957,10 @@ paths:
secretKey: 'sk_xxx',
})
- const item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
+ const { data: taxLines } = await client.orders.taxLines.list('or_abc123')
- lang: bash
label: Spree CLI
- source: spree api get /orders/{order_id}/items/{id}
+ source: spree api get /orders/{order_id}/tax_lines
parameters:
- name: x-spree-api-key
in: header
@@ -15415,97 +15970,104 @@ paths:
- 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).
+ description: Order prefixed ID
schema:
type: string
- - name: fields
+ - name: q
in: query
required: false
- description: Comma-separated list of fields to include (e.g., quantity,price,total).
- id is always included.
+ style: deepObject
+ explode: true
schema:
- type: string
+ type: object
+ additionalProperties: true
+ description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
+ Filters above for the list.
+ x-mint:
+ content: |-
+ ## Filters
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `included` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `provider_id` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `taxability_reason` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: item found
+ description: tax lines found
content:
application/json:
example:
- id: li_UkLWZg9DAJ
- variant_id: variant_gbHJdmfrXB
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 2
- currency: USD
- name: Product 502714
- slug: product-502714
- options_text: 'Size: S'
- price: '10.00'
- total: '20.00'
- adjustment_total: '0.00'
- additional_tax_total: '0.00'
- included_tax_total: '0.00'
- discount_total: '0.00'
- pre_tax_amount: '20.00'
- discounted_amount: '20.00'
- compare_at_amount:
- thumbnail_url:
- option_values:
- - id: optval_UkLWZg9DAJ
- option_type_id: opt_UkLWZg9DAJ
- name: size-4
- label: S
- position: 1
- color_code:
- option_type_name: foo-size-13
- option_type_label: Size
- image_url:
+ data:
+ - id: tl_UkLWZg9DAJ
+ label: VAT 15%
+ included: false
+ credit: false
+ rate: '0.15'
+ tax_rate_id:
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ fee_id:
+ return_line_item_id:
+ claim_line_item_id:
+ exchange_line_item_id:
+ amount: '1.50'
+ provider_id: internal
metadata: {}
+ taxability_reason:
+ country_code:
+ state_code:
+ data: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- digital_links: []
- metadata: {}
- price_source:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- catalog_price: '19.99'
- price_list_id:
- price_list_name:
- catalog_id:
- catalog_name:
- cost_price: '17.00'
- tax_category_id: taxcat_UkLWZg9DAJ
- patch:
- summary: Update an item
+ original_tax_line_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/admin/orders/{order_id}/discounts":
+ get:
+ summary: List discounts
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Updates an order item quantity or metadata.
+ Typed discount rows (promotion-sourced and manual) on the order.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15517,12 +16079,10 @@ paths:
secretKey: 'sk_xxx',
})
- const item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {
- quantity: 5,
- })
+ const { data: discounts } = await client.orders.discounts.list('or_abc123')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/items/{id} -d '{"quantity":5}'
+ source: spree api get /orders/{order_id}/discounts
parameters:
- name: x-spree-api-key
in: header
@@ -15532,89 +16092,82 @@ paths:
- 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
+ description: Order prefixed ID
schema:
type: string
- - name: id
- in: path
- required: true
- description: Item ID
+ - name: q
+ in: query
+ required: false
+ style: deepObject
+ explode: true
schema:
- type: string
+ type: object
+ additionalProperties: true
+ description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
+ Filters above for the list.
+ x-mint:
+ content: |-
+ ## Filters
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: item updated
+ description: discounts found
content:
application/json:
example:
- id: li_UkLWZg9DAJ
- variant_id: variant_gbHJdmfrXB
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 5
- currency: USD
- name: Product 519758
- slug: product-519758
- options_text: 'Size: S'
- price: '19.99'
- total: '99.95'
- adjustment_total: '0.00'
- additional_tax_total: '0.00'
- included_tax_total: '0.00'
- discount_total: '0.00'
- pre_tax_amount: '99.95'
- discounted_amount: '99.95'
- compare_at_amount:
- thumbnail_url:
- option_values:
- - id: optval_UkLWZg9DAJ
- option_type_id: opt_UkLWZg9DAJ
- name: size-5
- label: S
- position: 1
- color_code:
- option_type_name: foo-size-14
- option_type_label: Size
- image_url:
+ data:
+ - id: disc_UkLWZg9DAJ
+ label: Loyalty
+ kind: manual
+ code:
+ value_type:
+ value:
+ promotion_id:
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ amount: "-2.00"
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- digital_links: []
- metadata: {}
- price_source:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- catalog_price: '19.99'
- price_list_id:
- price_list_name:
- catalog_id:
- catalog_name:
- cost_price: '17.00'
- tax_category_id: taxcat_UkLWZg9DAJ
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- quantity:
- type: integer
- delete:
- summary: Remove an item
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create manual discount
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Removes an item from the order.
+ 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.
**Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
@@ -15628,10 +16181,17 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
+ // Line-item discount; omit line_item_id to distribute across the order.
+ const { data: discounts } = await client.orders.discounts.create('or_abc123', {
+ label: 'Customer appeasement',
+ value: '10',
+ value_type: 'flat',
+ line_item_id: 'item_abc123',
+ })
- lang: bash
label: Spree CLI
- source: spree api delete /orders/{order_id}/items/{id}
+ source: spree api post /orders/{order_id}/discounts -d '{"label":"Customer
+ appeasement","value":"10","value_type":"flat","line_item_id":"item_abc123"}'
parameters:
- name: x-spree-api-key
in: header
@@ -15641,53 +16201,83 @@ paths:
- 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
+ description: Order prefixed 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
+ '201':
+ description: discount created
+ content:
+ application/json:
+ example:
+ data:
+ - id: disc_UkLWZg9DAJ
+ label: Appeasement
+ kind: manual
+ code:
+ value_type: flat
+ value: '3.00'
+ promotion_id:
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ amount: "-3.00"
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ '422':
+ description: invalid discount
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_money_format
+ message: value must be a decimal string like "19.99"
+ details:
+ value:
+ - must be a decimal string like "19.99"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ label:
+ type: string
+ example: Customer appeasement
+ value:
+ type: string
+ example: '10.00'
+ value_type:
+ type: string
+ enum:
+ - flat
+ - percent
+ example: flat
+ line_item_id:
+ type: string
+ nullable: true
+ example: item_abc123
+ 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: |-
- Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.
-
- **Required scope:** `write_store_credits` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Returns the order's fees, such as surcharges, handling and gift wrap, on the whole order or on one item or delivery.
- const order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {
- amount: '25.00',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'
+ **Required scope:** `read_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -15697,126 +16287,92 @@ paths:
- 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
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
- '201':
- description: store credit applied
+ '200':
+ description: fees found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: false
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- coupon_code:
- fulfillment_status:
- payment_status:
- completed_at:
- item_total: '10.00'
- adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
- additional_tax_total: '0.00'
- total: '110.00'
- gift_card_total: '0.00'
- amount_due: '60.00'
- delivery_total: '100.00'
- fee_total: '0.00'
- store_credit_total: '50.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
+ data:
+ - id: fee_UkLWZg9DAJ
+ label: Gift wrap
+ kind: gift_wrap
+ line_item_id:
+ fulfillment_id:
+ amount: '4.00'
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '0.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- 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: cust_UkLWZg9DAJ
- freight_summary:
- 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
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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: |-
- Removes any applied store credit from the order.
+ Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.
- **Required scope:** `write_store_credits` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15828,10 +16384,14 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.storeCredits.remove('or_UkLWZg9DAJ')
+ const fee = await client.orders.fees.create('or_abc123', {
+ label: 'Gift wrap',
+ amount: '4.00',
+ kind: 'gift_wrap',
+ })
- lang: bash
label: Spree CLI
- source: spree api delete /orders/{order_id}/store_credits
+ source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":"4.00","kind":"gift_wrap"}'
parameters:
- name: x-spree-api-key
in: header
@@ -15841,50 +16401,88 @@ paths:
- 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
+ description: Order prefixed ID
schema:
type: string
responses:
- '204':
- description: store credit removed
- "/api/v3/admin/orders":
+ '201':
+ description: fee created
+ content:
+ application/json:
+ example:
+ id: fee_UkLWZg9DAJ
+ label: Gift wrap
+ kind: gift_wrap
+ line_item_id:
+ fulfillment_id:
+ amount: '4.00'
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ '422':
+ description: invalid fee
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Kind is not included in the list
+ details:
+ kind:
+ - value: nonsense
+ code: inclusion
+ message: is not included in the list
+ specific: false
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ label:
+ type: string
+ example: Gift wrap
+ amount:
+ type: string
+ example: '4.00'
+ kind:
+ type: string
+ enum:
+ - surcharge
+ - handling
+ - gift_wrap
+ - cod
+ - payment
+ - duty
+ - exchange
+ example: gift_wrap
+ 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 orders
+ summary: List order groups
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a paginated list of orders for the current store.
+ Returns checkouts split into one order per seller, grouping the orders placed together.
**Required scope:** `read_orders` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: orders, meta } = await client.orders.list({
- status_eq: 'complete',
- completed_at_gt: '2026-01-01',
- sort: '-completed_at',
- limit: 25,
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /orders -d '{"status_eq":"complete","completed_at_gt":"2026-01-01","sort":"-completed_at","limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -15894,56 +16492,6 @@ paths:
- 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
@@ -15956,21 +16504,6 @@ paths:
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
@@ -15979,177 +16512,80 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
- | `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `considered_risky` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `coupon_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `delivery_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `fulfillment_status` | One of `backorder`, `canceled`, `partial`, `unfulfilled`, `fulfilled`, `delivered`, `pending`, `ready`, `shipped` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `item_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `order_group_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `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` |
- | `po_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `status` | One of `draft`, `placed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `total_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
- Prefix an associated record's attribute with the association, as in `q[bill_address_id_eq]`. The same predicates apply.
+ Prefix an associated record's attribute with the association, as in `q[customer_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
- | `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
- | `channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
| `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
| `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
+ | `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` |
| `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
| `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
| `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |
- | `fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
- | `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` |
- | `line_items_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
- | `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` |
- | `order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
- | `order_group_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
- | `promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
- | `promotions_coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |
- | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
- | `shipments_` | `created_at`, `id`, `number`, `updated_at` |
- | `store_` | `created_at`, `id`, `name`, `updated_at` |
- | `tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `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` |
+ | `orders_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `orders_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `orders_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `orders_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `orders_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `orders_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `orders_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `orders_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `orders_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `orders_tags_` | `created_at`, `id`, `name`, `updated_at` |
</Accordion>
- **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.
+ **Sort by:** `created_at`, `currency`, `email`, `id`, `number`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: Order
+ table: OrderGroup
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
+ description: order groups found
content:
application/json:
example:
data:
- - id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: false
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
+ - id: ogrp_UkLWZg9DAJ
number: R1001
- customer_note:
- po_number:
currency: USD
- locale: en
- total_quantity: 0
- coupon_code:
+ total: '0.00'
+ item_total: '0.00'
fulfillment_status:
payment_status:
- completed_at:
- item_total: '0.00'
- adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
- additional_tax_total: '0.00'
- total: '0.00'
- gift_card_total: '0.00'
- amount_due: '0.00'
- delivery_total: '0.00'
- fee_total:
- store_credit_total: '0.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
+ completed_at: '2026-01-15T12:00:00.000Z'
+ billing_address:
+ shipping_address:
+ orders: []
+ customer_id: cust_UkLWZg9DAJ
+ cart_id:
+ seller_count: 0
+ includes_first_party: false
confirmation_delivered: false
- store_owner_notification_delivered:
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
+ store_owner_notification_delivered: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '0.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- 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: cust_UkLWZg9DAJ
- freight_summary:
+ payments: []
meta:
page: 1
limit: 25
@@ -16160,23 +16596,30 @@ paths:
in: 1
previous:
next:
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: authentication_required
- message: Authentication required
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ 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: Create a draft order
+ 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.
+
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16188,93 +16631,12 @@ paths:
secretKey: 'sk_xxx',
})
- // One-shot order create: customer, items, addresses, market, channel,
- // notes, metadata, and a coupon code in a single call. Everything
- // except `email` is optional.
- const order = await client.orders.create({
- email: '[email protected]',
- customer_id: 'cus_UkLWZg9DAJ', // Existing customer; omit for guest orders
- use_customer_default_address: false, // true to copy the customer's saved addresses
-
- currency: 'USD',
- market_id: 'mkt_UkLWZg9DAJ',
- channel_id: 'ch_UkLWZg9DAJ', // Optional — defaults to the store's primary channel
- locale: 'en-US',
-
- // Pin the order's preferred fulfillment location. Order Routing's
- // built-in PreferredLocation rule ranks this location first when
- // it stocks the cart's items; if it doesn't, routing falls back
- // to the next rule (Minimize Splits → Default Location).
- preferred_stock_location_id: 'sloc_UkLWZg9DAJ',
-
- customer_note: 'Please leave at the front desk.',
- // Rich text: send HTML. Reads return this as plain text, plus
- // `internal_note_html` with the markup.
- internal_note: '<p>VIP customer — handle with care.</p>',
- metadata: {
- external_reference: 'subscription_invoice_2026_04',
- source: 'recurring-engine',
- },
-
- // Items: each variant_id + quantity. Optional metadata per line.
- items: [
- { variant_id: 'variant_k5nR8xLq', quantity: 2 },
- { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },
- ],
-
- // Provide addresses inline OR by ID (existing customer addresses).
- shipping_address: {
- first_name: 'Jane',
- last_name: 'Doe',
- address1: '350 Fifth Avenue',
- address2: 'Floor 42',
- city: 'New York',
- postal_code: '10118',
- country_code: 'US',
- state_code: 'NY',
- phone: '+1 212 555 1234',
- company: 'Acme Inc.',
- },
- // shipping_address_id: 'addr_UkLWZg9DAJ', // alternative to inline
-
- billing_address: {
- first_name: 'Jane',
- last_name: 'Doe',
- address1: '350 Fifth Avenue',
- city: 'New York',
- postal_code: '10118',
- country_code: 'US',
- state_code: 'NY',
- phone: '+1 212 555 1234',
- },
- // billing_address_id: 'addr_UkLWZg9DAJ',
-
- // Optional. Invalid codes are non-fatal — the order is created either way.
- coupon_code: 'WELCOME10',
+ await client.orders.giftCards.apply('or_UkLWZg9DAJ', {
+ code: 'GIFT-XXXX-YYYY',
})
- lang: bash
label: Spree CLI
- source: spree api post /orders -d '{"email":"[email protected]","customer_id":"cus_UkLWZg9DAJ","use_customer_default_address":false,"currency":"USD","market_id":"mkt_UkLWZg9DAJ","channel_id":"ch_UkLWZg9DAJ","locale":"en-US","preferred_stock_location_id":"sloc_UkLWZg9DAJ","customer_note":"Please
- leave at the front desk.","internal_note":"<p>VIP customer — handle with
- care.</p>","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350
- Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
- 212 555 1234","company":"Acme Inc."},"billing_address":{"first_name":"Jane","last_name":"Doe","address1":"350
- Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
- 212 555 1234"},"coupon_code":"WELCOME10"}'
- description: |-
- Creates a new draft order in one shot. Customer, items, addresses, currency,
- market, channel, locale, notes, metadata, and a coupon code can all be
- provided inline.
-
- Setting `preferred_stock_location_id` pins the order's preferred fulfillment
- location — Order Routing's built-in `PreferredLocation` rule consumes it
- when picking which stock location ships each shipment.
-
- Invalid coupon codes are non-fatal — the order is created and the failure
- is reported on the service result (not in the API response body for now).
-
-
- **Required scope:** `write_orders` (for API-key authentication).
+ source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'
parameters:
- name: x-spree-api-key
in: header
@@ -16287,216 +16649,58 @@ paths:
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: order created with preferred_stock_location_id
+ description: gift card applied
content:
application/json:
example:
- id: or_gbHJdmfrXB
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: false
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1002
- customer_note:
- po_number:
+ id: gc_UkLWZg9DAJ
+ code: "************2F41"
+ status: active
currency: USD
- locale: en
- total_quantity: 0
- coupon_code:
- fulfillment_status:
- payment_status:
- completed_at:
- item_total: '0.00'
- adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
- additional_tax_total: '0.00'
- total: '0.00'
- gift_card_total: '0.00'
- amount_due: '0.00'
- delivery_total: '0.00'
- fee_total: '0.00'
- store_credit_total: '0.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
+ amount: '10.00'
+ amount_used: '10.00'
+ amount_authorized: '0.00'
+ amount_remaining: '0.00'
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '0.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- preferred_stock_location_id: sloc_UkLWZg9DAJ
- 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: adm_UkLWZg9DAJ
- created_by_type: admin_user
- cancel_reason_id:
- cancel_reason_name:
customer_id:
- freight_summary:
+ created_by_id:
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - code
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
- example: USD
- 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
- example: en-US
- 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
- example: 1
- metadata:
- type: object
- coupon_code:
+ code:
type: string
- description: Optional. Applied non-fatally; invalid codes do not
- block creation.
- "/api/v3/admin/orders/{id}":
- get:
- summary: Show an order
+ description: Gift card code
+ example: GIFT-XXXX-YYYY
+ "/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: |-
- Returns full order details including admin-only fields.
+ Removes the gift card from the order.
- **Required scope:** `read_orders` (for API-key authentication).
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16508,12 +16712,10 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.get('or_UkLWZg9DAJ', {
- expand: ['items', 'fulfillments', 'payments', 'customer'],
- })
+ await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'
+ source: spree api delete /orders/{order_id}/gift_cards/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -16526,138 +16728,33 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - name: order_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).
+ description: Order ID
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.
+ - name: id
+ in: path
+ required: true
+ description: Gift card ID
schema:
type: string
responses:
- '200':
- description: order found
- content:
- application/json:
- example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: false
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 0
- coupon_code:
- fulfillment_status:
- payment_status:
- completed_at:
- item_total: '0.00'
- adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
- additional_tax_total: '0.00'
- total: '0.00'
- gift_card_total: '0.00'
- amount_due: '0.00'
- delivery_total: '0.00'
- fee_total:
- store_credit_total: '0.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '0.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- 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: cust_UkLWZg9DAJ
- freight_summary:
- '404':
- description: order not found
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update an order
+ '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: |-
- Updates an order. Supports updating email, addresses, special instructions, and line items.
+ Returns all line items for an order.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16669,14 +16766,10 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.update('or_UkLWZg9DAJ', {
- email: '[email protected]',
- internal_note: '<p>VIP — gift wrap on next order</p>',
- })
+ const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"<p>VIP
- — gift wrap on next order</p>"}'
+ source: spree api get /orders/{order_id}/items
parameters:
- name: x-spree-api-key
in: header
@@ -16689,186 +16782,295 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `additional_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `discount_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `included_tax_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `non_taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `pre_tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `taxable_adjustment_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+ | `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` |
+ | `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
+ | `variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
+ | `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
+ | `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+
+ </Accordion>
+
+ **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: order updated
+ description: items found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: false
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
+ data:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_gbHJdmfrXB
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 2
+ currency: USD
+ name: Product 569180
+ slug: product-569180
+ options_text: 'Size: S'
+ price: '10.00'
+ total: '20.00'
+ adjustment_total: '0.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ discount_total: '0.00'
+ pre_tax_amount: '20.00'
+ discounted_amount: '20.00'
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-5
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-15
+ option_type_label: Size
+ image_url:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ digital_links: []
+ metadata: {}
+ price_source:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
+ cost_price: '17.00'
+ tax_category_id: taxcat_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Add an item
+ tags:
+ - Orders
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Adds a new line item to the order.
+
+ **Required scope:** `write_orders` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const item = await client.orders.items.create('or_UkLWZg9DAJ', {
+ variant_id: 'variant_k5nR8xLq',
+ quantity: 2,
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'
+ parameters:
+ - name: x-spree-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:
+ example:
+ id: li_gbHJdmfrXB
+ variant_id: variant_VqXmZF31wY
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 3
currency: USD
- locale: en
- total_quantity: 0
- coupon_code:
- fulfillment_status:
- payment_status: none
- completed_at:
- item_total: '0.00'
+ name: Product 5899
+ slug: product-5899
+ options_text: 'Size: S'
+ price: '19.99'
+ total: '59.97'
adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
additional_tax_total: '0.00'
- total: '0.00'
- gift_card_total: '0.00'
- amount_due: '0.00'
- delivery_total: '0.00'
- fee_total: '0.00'
- store_credit_total: '0.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
+ included_tax_total: '0.00'
+ discount_total: '0.00'
+ pre_tax_amount: '59.97'
+ discounted_amount: '59.97'
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_gbHJdmfrXB
+ option_type_id: opt_gbHJdmfrXB
+ name: size-7
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-17
+ option_type_label: Size
+ image_url:
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
+ digital_links: []
metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
+ price_source:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '0.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- 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: cust_UkLWZg9DAJ
- freight_summary:
+ catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
+ cost_price: '17.00'
+ tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - variant_id
properties:
- email:
- type: string
- customer_note:
- type: string
- internal_note:
- type: string
- channel_id:
- type: string
- description: Channel ID
- preferred_stock_location_id:
+ variant_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
- example: 1
- metadata:
- type: object
- delete:
- summary: Delete a draft order
+ 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: |-
- Deletes a draft order. Completed orders cannot be deleted.
+ Returns details of a specific line item.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16880,10 +17082,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.delete('or_UkLWZg9DAJ')
+ const item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /orders/{id}
+ source: spree api get /orders/{order_id}/items/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -16896,32 +17098,92 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - 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:
- '204':
- description: order deleted
- "/api/v3/admin/orders/{id}/complete":
+ '200':
+ description: item found
+ content:
+ application/json:
+ example:
+ id: li_UkLWZg9DAJ
+ variant_id: variant_gbHJdmfrXB
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 2
+ currency: USD
+ name: Product 592714
+ slug: product-592714
+ options_text: 'Size: S'
+ price: '10.00'
+ total: '20.00'
+ adjustment_total: '0.00'
+ additional_tax_total: '0.00'
+ included_tax_total: '0.00'
+ discount_total: '0.00'
+ pre_tax_amount: '20.00'
+ discounted_amount: '20.00'
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-8
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-18
+ option_type_label: Size
+ image_url:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ digital_links: []
+ metadata: {}
+ price_source:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
+ cost_price: '17.00'
+ tax_category_id: taxcat_UkLWZg9DAJ
patch:
- summary: Complete an order
+ summary: Update an item
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Completes an order in the `confirm` state, marking it as placed.
-
- Set `notify_customer: true` to send the order confirmation email.
-
- On a marketplace, an order holding several sellers' goods becomes one
- order per seller, and the response is the order group they belong to
- with those orders nested inside it.
-
+ Updates an order item quantity or metadata.
**Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
@@ -16935,15 +17197,12 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.orders.complete('or_UkLWZg9DAJ', {
- notify_customer: true,
+ const item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {
+ quantity: 5,
})
-
- // An order holding several sellers' goods becomes one order per seller.
- const orders = isOrderGroup(result) ? result.orders : [result]
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{id}/complete -d '{"notify_customer":true}'
+ source: spree api patch /orders/{order_id}/items/{id} -d '{"quantity":5}'
parameters:
- name: x-spree-api-key
in: header
@@ -16956,152 +17215,86 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - 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: order completed
+ description: item updated
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: true
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
+ id: li_UkLWZg9DAJ
+ variant_id: variant_gbHJdmfrXB
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 5
currency: USD
- locale: en
- total_quantity: 1
- coupon_code:
- fulfillment_status: unfulfilled
- payment_status: paid
- completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.00'
+ name: Product 609758
+ slug: product-609758
+ options_text: 'Size: S'
+ price: '19.99'
+ total: '99.95'
adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
additional_tax_total: '0.00'
- total: '110.00'
- gift_card_total: '0.00'
- amount_due: '0.00'
- delivery_total: '100.00'
- fee_total: '0.00'
- store_credit_total: '0.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
+ included_tax_total: '0.00'
+ discount_total: '0.00'
+ pre_tax_amount: '99.95'
+ discounted_amount: '99.95'
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-9
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-19
+ option_type_label: Size
+ image_url:
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: placed
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
+ digital_links: []
metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
+ price_source:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '110.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- 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: cust_UkLWZg9DAJ
- freight_summary:
- '422':
- description: order cannot be completed
- content:
- application/json:
- example:
- error:
- code: order_cannot_complete
- message: No payment found
- details:
- base:
- - code:
- message: No payment found
- specific: false
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
+ cost_price: '17.00'
+ tax_category_id: taxcat_UkLWZg9DAJ
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
+ quantity:
+ type: integer
+ delete:
+ summary: Remove an item
tags:
- Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Cancels a completed order.
-
- `cancel_reason_id` records why, from the store's own cancellation-reason
- vocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a
- staff-facing note; both are shown on the order afterwards.
-
- Stock is always released — the goods are not going out either way — and
- every payment is settled at the gateway, which releases an
- authorization it never drew on and refunds a charge it cannot release.
-
- `refund_payments` and `refund_amount` govern the shared payment of a
- split checkout, where one payment covers several orders: they decide
- whether this order's share comes back, and how much of it. A
- `refund_amount` on an ordinary order is refused with a 422.
-
- Set `notify_customer: true` to send the order cancellation email.
-
+ Removes an item from the order.
**Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
@@ -17115,18 +17308,10 @@ paths:
secretKey: 'sk_xxx',
})
- // A split checkout: the payment is shared, so what comes back is this order's
- // own share. refund_amount names part of that share, keeping the rest back.
- const order = await client.orders.cancel('or_UkLWZg9DAJ', {
- cancel_reason_id: 'ocr_UkLWZg9DAJ',
- cancel_note: 'Supplier could not deliver in time',
- refund_payments: true,
- refund_amount: '25.00',
- })
+ await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{id}/cancel -d '{"cancel_reason_id":"ocr_UkLWZg9DAJ","cancel_note":"Supplier
- could not deliver in time","refund_payments":true,"refund_amount":"25.00"}'
+ source: spree api delete /orders/{order_id}/items/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -17139,140 +17324,33 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - 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: order canceled
- content:
- application/json:
- example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: false
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- coupon_code:
- fulfillment_status: canceled
- payment_status: none
- completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.00'
- adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
- additional_tax_total: '0.00'
- total: '110.00'
- gift_card_total: '0.00'
- amount_due: '0.00'
- delivery_total: '100.00'
- fee_total: '0.00'
- store_credit_total: '0.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: canceled
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- metadata: {}
- cancel_note:
- canceled_at: '2026-01-15T12:00:00.000Z'
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '0.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- approver_type:
- canceler_id: adm_UkLWZg9DAJ
- canceler_type: admin_user
- created_by_id:
- created_by_type:
- cancel_reason_id:
- cancel_reason_name:
- customer_id: cust_UkLWZg9DAJ
- freight_summary:
- 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
+ '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: |-
- Approves an order (e.g., for fraud review).
+ Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `write_store_credits` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17284,10 +17362,12 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.approve('or_UkLWZg9DAJ')
+ const order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {
+ amount: '25.00',
+ })
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{id}/approve -d '{ ... }'
+ source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'
parameters:
- name: x-spree-api-key
in: header
@@ -17300,22 +17380,22 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - name: order_id
in: path
required: true
description: Order ID
schema:
type: string
responses:
- '200':
- description: order approved
+ '201':
+ description: store credit applied
content:
application/json:
example:
id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
withdrawal_period_ends_at:
- within_withdrawal_period: true
+ within_withdrawal_period: false
cart_id:
channel_id: ch_UkLWZg9DAJ
company_id:
@@ -17323,7 +17403,7 @@ paths:
po_document_filename:
po_document_byte_size:
number: R1001
customer_note:
po_number:
currency: USD
@@ -17332,7 +17412,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
+ completed_at:
item_total: '10.00'
adjustment_total: '0.00'
discount_total: '0.00'
@@ -17341,10 +17421,10 @@ paths:
additional_tax_total: '0.00'
total: '110.00'
gift_card_total: '0.00'
- amount_due: '110.00'
+ amount_due: '60.00'
delivery_total: '100.00'
fee_total: '0.00'
- store_credit_total: '0.00'
+ store_credit_total: '50.00'
covered_by_store_credit: false
gift_card:
market:
@@ -17364,7 +17444,7 @@ paths:
updated_at: '2026-01-15T12:00:00.000Z'
tax_provider:
external_references: {}
- status: placed
+ status: draft
last_ip_address:
considered_risky: false
confirmation_delivered: false
@@ -17372,7 +17452,7 @@ paths:
metadata: {}
cancel_note:
canceled_at:
- approved_at: '2026-01-15T12:00:00.000Z'
+ approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
payment_total: '0.00'
@@ -17386,8 +17466,8 @@ paths:
tags: []
internal_note:
internal_note_html:
- approver_id: adm_UkLWZg9DAJ
- approver_type: admin_user
+ approver_id:
+ approver_type:
canceler_id:
canceler_type:
created_by_id:
@@ -17396,18 +17476,27 @@ paths:
cancel_reason_name:
customer_id: cust_UkLWZg9DAJ
freight_summary:
- "/api/v3/admin/orders/{id}/resend_confirmation":
- post:
- summary: Resend confirmation email
+ 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: |-
- Publishes the order.completed event to trigger confirmation email delivery.
+ Removes any applied store credit from the order.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `write_store_credits` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17419,10 +17508,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.resendConfirmation('or_UkLWZg9DAJ')
+ await client.orders.storeCredits.remove('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api post /orders/{id}/resend_confirmation -d '{ ... }'
+ source: spree api delete /orders/{order_id}/store_credits
parameters:
- name: x-spree-api-key
in: header
@@ -17435,114 +17524,27 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
+ - name: order_id
in: path
required: true
description: Order ID
schema:
type: string
responses:
- '200':
- description: confirmation resent
- content:
- application/json:
- example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- withdrawal_period_ends_at:
- within_withdrawal_period: true
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- coupon_code:
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.00'
- adjustment_total: '0.00'
- discount_total: '0.00'
- tax_total: '0.00'
- included_tax_total: '0.00'
- additional_tax_total: '0.00'
- total: '110.00'
- gift_card_total: '0.00'
- amount_due: '110.00'
- delivery_total: '100.00'
- fee_total: '0.00'
- store_credit_total: '0.00'
- covered_by_store_credit: false
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- country_isos:
- - US
- supported_locales:
- - en
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- tax_provider:
- external_references: {}
- status: placed
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- payment_total: '0.00'
- commission_amount_total: '0.00'
- commission_tax_total: '0.00'
- commission_total: '0.00'
- 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: cust_UkLWZg9DAJ
- freight_summary:
- "/api/v3/admin/payment_methods":
+ '204':
+ description: store credit removed
+ "/api/v3/admin/orders":
get:
- summary: List payment methods
+ summary: List orders
tags:
- - Payment Methods
+ - Orders
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.
+ Returns a paginated list of orders for the current store.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17554,10 +17556,15 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: paymentMethods } = await client.paymentMethods.list()
+ const { data: orders, meta } = await client.orders.list({
+ status_eq: 'complete',
+ completed_at_gt: '2026-01-01',
+ sort: '-completed_at',
+ limit: 25,
+ })
- lang: bash
label: Spree CLI
- source: spree api get /payment_methods
+ source: spree api get /orders -d '{"status_eq":"complete","completed_at_gt":"2026-01-01","sort":"-completed_at","limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -17567,6 +17574,7 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- name: q[search]
@@ -17574,19 +17582,48 @@ paths:
required: false
schema:
type: string
- description: Matches any of name (partial, case-insensitive).
- - name: expand
+ 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
- description: Comma-separated associations to expand. Use dot notation for
- nested expand (max 4 levels).
schema:
- type: string
- - name: fields
+ type: boolean
+ description: Set to `true` to apply `complete`.
+ - name: q[incomplete]
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,type,active).
- id is always included.
+ 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
@@ -17599,412 +17636,200 @@ paths:
additionalProperties: true
description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
Filters above for the list.
- x-mint:
- content: |-
- ## Filters
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- **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:
- example:
- data:
- - id: pm_UkLWZg9DAJ
- name: Check 2
- description:
- type: check
- session_required: false
- source_required: false
- metadata: {}
- active: true
- auto_capture:
- capture_method:
- resolved_capture_method: checkout
- storefront_visible: true
- position: 1
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- preferences: {}
- logo_url:
- docs_url:
- third_party: false
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- "/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.
-
- **Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: types } = await client.paymentMethods.types()
- - lang: bash
- label: Spree CLI
- source: spree api get /payment_methods/types
- 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:
- example:
- data:
- - type: bogus
- label: Bogus
- description:
- schema:
- type: object
- properties:
- dummy_key:
- type: string
- default: PUBLICKEY123
- dummy_secret_key:
- type:
- - string
- - 'null'
- x-spree-secret: true
- additionalProperties: false
- logo_url:
- docs_url:
- third_party: true
- installed: false
- - type: check
- label: Check
- description:
- schema:
- type: object
- properties: {}
- additionalProperties: false
- logo_url:
- docs_url:
- third_party: false
- installed: true
- - type: custom_payment_source_method
- label: Custom Payment Source Method
- description:
- schema:
- type: object
- properties: {}
- additionalProperties: false
- logo_url:
- docs_url:
- third_party: false
- installed: false
- - type: store_credit
- label: Store Credit
- description:
- schema:
- type: object
- properties: {}
- additionalProperties: false
- logo_url:
- docs_url:
- third_party: false
- installed: true
- "/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.
-
- **Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /payment_methods/{id}
- 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:
- example:
- id: pm_UkLWZg9DAJ
- name: Check 4
- description:
- type: check
- session_required: false
- source_required: false
- metadata: {}
- active: true
- auto_capture:
- capture_method:
- resolved_capture_method: checkout
- storefront_visible: true
- position: 1
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- preferences: {}
- logo_url:
- docs_url:
- third_party: false
- "/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.
-
- **Required scope:** `read_payments` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/payments
- parameters:
- - name: x-spree-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).
+ 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., amount,status,number,response_code).
+ description: Comma-separated list of fields to include (e.g., number,total,status,completed_at).
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
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `avs_response` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `channel_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `completed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `considered_risky` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `coupon_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `cvv_response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `cvv_response_message` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `customer_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `delivery_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `fulfillment_status` | One of `backorder`, `canceled`, `partial`, `unfulfilled`, `fulfilled`, `delivered`, `pending`, `ready`, `shipped` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `state` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `status` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `item_total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `order_group_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `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` |
+ | `po_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `status` | One of `draft`, `placed`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `total_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
- Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
+ Prefix an associated record's attribute with the association, as in `q[bill_address_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
- | `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` |
- | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
- | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
- | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
- | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
- | `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` |
- | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
- | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
- | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
- | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
- | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
- | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
- | `payment_method_` | `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at` |
+ | `bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `customer_addresses_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `customer_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `customer_customer_groups_` | `created_at`, `id`, `name`, `updated_at` |
+ | `customer_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `customer_spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
+ | `customer_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `line_items_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+ | `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` |
+ | `order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_group_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `promotions_coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `tags_` | `created_at`, `id`, `name`, `updated_at` |
</Accordion>
- **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.
+ **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: Payment
+ table: Order
sortable:
- - amount
- - avs_response
+ - channel_id
+ - completed_at
+ - considered_risky
+ - coupon_code
- created_at
- - cvv_response_code
- - cvv_response_message
+ - currency
+ - customer_id
+ - delivery_total
+ - email
+ - fulfillment_status
- id
- - response_code
- - state
+ - 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: payments found
+ description: orders found
content:
application/json:
example:
data:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-343039b69b86
- number: R1001-P1
- status: completed
- amount: '110.00'
- source_type: credit_card
- source_id: card_UkLWZg9DAJ
- source:
- id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- customer_id:
- payment_method_id: pm_gbHJdmfrXB
- metadata: {}
+ - id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: false
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ item_total: '0.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '0.00'
+ gift_card_total: '0.00'
+ amount_due: '0.00'
+ delivery_total: '0.00'
+ fee_total:
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ tax_provider:
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
metadata: {}
- avs_response:
- cvv_response_code:
- cvv_response_message:
+ cancel_note:
+ canceled_at:
+ approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.00'
- order_id: or_UkLWZg9DAJ
+ payment_total: '0.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ 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: cust_UkLWZg9DAJ
+ freight_summary:
meta:
page: 1
limit: 25
@@ -18015,17 +17840,23 @@ paths:
in: 1
previous:
next:
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a payment
+ summary: Create a draft order
tags:
- - Payments
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: |-
- Creates a new payment for the order.
-
- **Required scope:** `write_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18037,14 +17868,93 @@ paths:
secretKey: 'sk_xxx',
})
- const payment = await client.orders.payments.create('or_UkLWZg9DAJ', {
- payment_method_id: 'pm_UkLWZg9DAJ',
- amount: '99.99',
- source_id: 'cc_UkLWZg9DAJ',
+ // One-shot order create: customer, items, addresses, market, channel,
+ // notes, metadata, and a coupon code in a single call. Everything
+ // except `email` is optional.
+ const order = await client.orders.create({
+ email: '[email protected]',
+ customer_id: 'cus_UkLWZg9DAJ', // Existing customer; omit for guest orders
+ use_customer_default_address: false, // true to copy the customer's saved addresses
+
+ currency: 'USD',
+ market_id: 'mkt_UkLWZg9DAJ',
+ channel_id: 'ch_UkLWZg9DAJ', // Optional — defaults to the store's primary channel
+ locale: 'en-US',
+
+ // Pin the order's preferred fulfillment location. Order Routing's
+ // built-in PreferredLocation rule ranks this location first when
+ // it stocks the cart's items; if it doesn't, routing falls back
+ // to the next rule (Minimize Splits → Default Location).
+ preferred_stock_location_id: 'sloc_UkLWZg9DAJ',
+
+ customer_note: 'Please leave at the front desk.',
+ // Rich text: send HTML. Reads return this as plain text, plus
+ // `internal_note_html` with the markup.
+ internal_note: '<p>VIP customer — handle with care.</p>',
+ metadata: {
+ external_reference: 'subscription_invoice_2026_04',
+ source: 'recurring-engine',
+ },
+
+ // Items: each variant_id + quantity. Optional metadata per line.
+ items: [
+ { variant_id: 'variant_k5nR8xLq', quantity: 2 },
+ { variant_id: 'variant_QXyZ12abCD', quantity: 1, metadata: { gift: true } },
+ ],
+
+ // Provide addresses inline OR by ID (existing customer addresses).
+ shipping_address: {
+ first_name: 'Jane',
+ last_name: 'Doe',
+ address1: '350 Fifth Avenue',
+ address2: 'Floor 42',
+ city: 'New York',
+ postal_code: '10118',
+ country_code: 'US',
+ state_code: 'NY',
+ phone: '+1 212 555 1234',
+ company: 'Acme Inc.',
+ },
+ // shipping_address_id: 'addr_UkLWZg9DAJ', // alternative to inline
+
+ billing_address: {
+ first_name: 'Jane',
+ last_name: 'Doe',
+ address1: '350 Fifth Avenue',
+ city: 'New York',
+ postal_code: '10118',
+ country_code: 'US',
+ state_code: 'NY',
+ phone: '+1 212 555 1234',
+ },
+ // billing_address_id: 'addr_UkLWZg9DAJ',
+
+ // Optional. Invalid codes are non-fatal — the order is created either way.
+ coupon_code: 'WELCOME10',
})
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/payments -d '{"payment_method_id":"pm_UkLWZg9DAJ","amount":"99.99","source_id":"cc_UkLWZg9DAJ"}'
+ source: spree api post /orders -d '{"email":"[email protected]","customer_id":"cus_UkLWZg9DAJ","use_customer_default_address":false,"currency":"USD","market_id":"mkt_UkLWZg9DAJ","channel_id":"ch_UkLWZg9DAJ","locale":"en-US","preferred_stock_location_id":"sloc_UkLWZg9DAJ","customer_note":"Please
+ leave at the front desk.","internal_note":"<p>VIP customer — handle with
+ care.</p>","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350
+ Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
+ 212 555 1234","company":"Acme Inc."},"billing_address":{"first_name":"Jane","last_name":"Doe","address1":"350
+ Fifth Avenue","city":"New York","postal_code":"10118","country_code":"US","state_code":"NY","phone":"+1
+ 212 555 1234"},"coupon_code":"WELCOME10"}'
+ description: |-
+ Creates a new draft order in one shot. Customer, items, addresses, currency,
+ market, channel, locale, notes, metadata, and a coupon code can all be
+ provided inline.
+
+ Setting `preferred_stock_location_id` pins the order's preferred fulfillment
+ location — Order Routing's built-in `PreferredLocation` rule consumes it
+ when picking which stock location ships each shipment.
+
+ Invalid coupon codes are non-fatal — the order is created and the failure
+ is reported on the service result (not in the API response body for now).
+
+
+ **Required scope:** `write_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -18057,64 +17967,216 @@ paths:
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
+ description: order created with preferred_stock_location_id
content:
application/json:
example:
- id: py_gbHJdmfrXB
- payment_method_id: pm_EfhxLZ9ck8
- response_code:
- number: R1002-P1
- status: checkout
- amount: '110.00'
- source_type:
- source_id:
- source:
+ id: or_gbHJdmfrXB
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: false
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1002
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ item_total: '0.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '0.00'
+ gift_card_total: '0.00'
+ amount_due: '0.00'
+ delivery_total: '0.00'
+ fee_total: '0.00'
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ tax_provider:
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
metadata: {}
- avs_response:
- cvv_response_code:
- cvv_response_message:
+ cancel_note:
+ canceled_at:
+ approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.00'
- order_id: or_gbHJdmfrXB
+ payment_total: '0.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ preferred_stock_location_id: sloc_UkLWZg9DAJ
+ 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: adm_UkLWZg9DAJ
+ created_by_type: admin_user
+ cancel_reason_id:
+ cancel_reason_name:
+ customer_id:
+ freight_summary:
requestBody:
content:
application/json:
schema:
type: object
- required:
- - payment_method_id
properties:
- payment_method_id:
+ email:
type: string
- description: Payment method ID
- amount:
+ customer_id:
type: string
- example: '99.99'
- source_id:
+ 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
- description: Payment source ID
- "/api/v3/admin/orders/{order_id}/payments/{id}":
+ example: USD
+ 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
+ example: en-US
+ 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
+ example: 1
+ 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 a payment
+ summary: Show an order
tags:
- - Payments
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns details of a specific payment.
+ Returns full order details including admin-only fields.
- **Required scope:** `read_payments` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18126,10 +18188,12 @@ paths:
secretKey: 'sk_xxx',
})
- const payment = await client.orders.payments.get('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
+ const order = await client.orders.get('or_UkLWZg9DAJ', {
+ expand: ['items', 'fulfillments', 'payments', 'customer'],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /orders/{order_id}/payments/{id}
+ source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -18142,80 +18206,138 @@ paths:
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
+ description: Order ID (e.g., or_xxx)
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).
+ 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., amount,status,number,response_code).
+ 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: payment found
+ description: order found
content:
application/json:
example:
- id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-4a236d40ef07
- number: R1001-P1
- status: completed
- amount: '110.00'
- source_type: credit_card
- source_id: card_UkLWZg9DAJ
- source:
- id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- customer_id:
- payment_method_id: pm_gbHJdmfrXB
- metadata: {}
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: false
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at:
+ item_total: '0.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '0.00'
+ gift_card_total: '0.00'
+ amount_due: '0.00'
+ delivery_total: '0.00'
+ fee_total:
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ tax_provider:
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
metadata: {}
- avs_response:
- cvv_response_code:
- cvv_response_message:
+ cancel_note:
+ canceled_at:
+ approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.00'
- order_id: or_UkLWZg9DAJ
- "/api/v3/admin/orders/{order_id}/payments/{id}/capture":
+ payment_total: '0.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ 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: cust_UkLWZg9DAJ
+ freight_summary:
+ '404':
+ description: order not found
+ content:
+ application/json:
+ example:
+ error:
+ code: order_not_found
+ message: Order not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Capture a payment
+ summary: Update an order
tags:
- - Payments
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Captures a pending payment.
+ Updates an order. Supports updating email, addresses, special instructions, and line items.
- **Required scope:** `write_payments` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18227,11 +18349,14 @@ paths:
secretKey: 'sk_xxx',
})
- const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
+ const order = await client.orders.update('or_UkLWZg9DAJ', {
+ email: '[email protected]',
+ internal_note: '<p>VIP — gift wrap on next order</p>',
+ })
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/payments/{id}/capture -d '{ ...
- }'
+ source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"<p>VIP
+ — gift wrap on next order</p>"}'
parameters:
- name: x-spree-api-key
in: header
@@ -18244,76 +18369,186 @@ paths:
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
+ description: Order ID
schema:
type: string
responses:
'200':
- description: payment captured
- content:
- application/json:
- example:
- id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-ccc19f06b194
- number: R1001-P1
- status: completed
- amount: '110.00'
- source_type: credit_card
- source_id: card_UkLWZg9DAJ
- source:
- id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- customer_id:
- payment_method_id: pm_gbHJdmfrXB
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- metadata: {}
- avs_response:
- cvv_response_code:
- cvv_response_message:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '110.00'
- order_id: or_UkLWZg9DAJ
- '422':
- description: capture failed
+ description: order updated
content:
application/json:
example:
- error:
- code: processing_error
- message: 'Bogus Gateway: Forced failure'
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/orders/{order_id}/payments/{id}/void":
- patch:
- summary: Void a payment
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: false
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ coupon_code:
+ fulfillment_status:
+ payment_status: none
+ completed_at:
+ item_total: '0.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '0.00'
+ gift_card_total: '0.00'
+ amount_due: '0.00'
+ delivery_total: '0.00'
+ fee_total: '0.00'
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ tax_provider:
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '0.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ 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: cust_UkLWZg9DAJ
+ freight_summary:
+ 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
+ example: 1
+ metadata:
+ type: object
+ delete:
+ summary: Delete a draft order
tags:
- - Payments
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Voids a payment.
+ Deletes a draft order. Completed orders cannot be deleted.
- **Required scope:** `write_payments` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18325,10 +18560,10 @@ paths:
secretKey: 'sk_xxx',
})
- const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
+ await client.orders.delete('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/payments/{id}/void -d '{ ... }'
+ source: spree api delete /orders/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -18341,66 +18576,34 @@ paths:
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
+ description: Order ID
schema:
type: string
responses:
- '200':
- description: payment voided
- content:
- application/json:
- example:
- id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-11f2e975ba0c
- number: R1001-P1
- status: void
- amount: '110.00'
- source_type: credit_card
- source_id: card_UkLWZg9DAJ
- source:
- id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- customer_id:
- payment_method_id: pm_gbHJdmfrXB
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- metadata: {}
- avs_response:
- cvv_response_code:
- cvv_response_message:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- captured_amount: '0.00'
- order_id: or_UkLWZg9DAJ
- "/api/v3/admin/price_lists":
- get:
- summary: List price lists
+ '204':
+ description: order deleted
+ "/api/v3/admin/orders/{id}/complete":
+ patch:
+ summary: Complete an order
tags:
- - Pricing
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the price lists configured for the current store.
+ Completes an order in the `confirm` state, marking it as placed.
- **Required scope:** `read_products` (for API-key authentication).
+ Set `notify_customer: true` to send the order confirmation email.
+
+ On a marketplace, an order holding several sellers' goods becomes one
+ order per seller, and the response is the order group they belong to
+ with those orders nested inside it.
+
+
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18412,10 +18615,15 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: priceLists } = await client.priceLists.list()
+ const result = await client.orders.complete('or_UkLWZg9DAJ', {
+ notify_customer: true,
+ })
+
+ // An order holding several sellers' goods becomes one order per seller.
+ const orders = isOrderGroup(result) ? result.orders : [result]
- lang: bash
label: Spree CLI
- source: spree api get /price_lists
+ source: spree api patch /orders/{id}/complete -d '{"notify_customer":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -18425,154 +18633,157 @@ paths:
- 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
- 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`.'
+ - name: id
+ in: path
+ required: true
+ description: Order ID
schema:
type: string
- x-mint:
- content: |-
- ## Filters
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `catalog_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `ends_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `match_policy` | One of `all`, `any` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `status` | One of `draft`, `active`, `inactive`, `scheduled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- **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
+ description: order completed
content:
application/json:
example:
- data:
- - id: pl_UkLWZg9DAJ
- name: Wholesale
- description:
- status: draft
- position: 1
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- price_adjustment_percentage:
- automatic_pricing: false
- currently_active: false
- products_count: 0
- prices_count: 0
- price_adjustment_tiers: []
- - id: pl_gbHJdmfrXB
- name: Holiday
- description:
- status: draft
- position: 2
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: true
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ coupon_code:
+ fulfillment_status: unfulfilled
+ payment_status: paid
+ completed_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '110.00'
+ gift_card_total: '0.00'
+ amount_due: '0.00'
+ delivery_total: '100.00'
+ fee_total: '0.00'
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- price_adjustment_percentage:
- automatic_pricing: false
- currently_active: false
- products_count: 0
- prices_count: 0
- price_adjustment_tiers: []
- meta:
- page: 1
- limit: 25
- count: 2
- pages: 1
- from: 1
- to: 2
- in: 2
- previous:
- next:
+ tax_provider:
+ external_references: {}
+ status: placed
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ payment_total: '110.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ 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: cust_UkLWZg9DAJ
+ freight_summary:
+ '422':
+ description: order cannot be completed
+ content:
+ application/json:
+ example:
+ error:
+ code: order_cannot_complete
+ message: No payment found
+ details:
+ base:
+ - code:
+ message: No payment found
+ specific: false
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
+ "$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:
- - Pricing
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new draft price list.
+ Cancels a completed order.
- **Required scope:** `write_products` (for API-key authentication).
+ `cancel_reason_id` records why, from the store's own cancellation-reason
+ vocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a
+ staff-facing note; both are shown on the order afterwards.
+
+ Stock is always released — the goods are not going out either way — and
+ every payment is settled at the gateway, which releases an
+ authorization it never drew on and refunds a charge it cannot release.
+
+ `refund_payments` and `refund_amount` govern the shared payment of a
+ split checkout, where one payment covers several orders: they decide
+ whether this order's share comes back, and how much of it. A
+ `refund_amount` on an ordinary order is refused with a 422.
+
+ Set `notify_customer: true` to send the order cancellation email.
+
+
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18584,45 +18795,18 @@ paths:
secretKey: 'sk_xxx',
})
- // Server-to-server one-shot create. Ship the rules that gate the list
- // and the exact per-variant prices in a single request — variants in
- // `prices` implicitly become part of the list (upserted on the unique
- // key `(variant_id, currency, price_list_id)`). Curating whole products
- // goes through `client.priceLists.products` instead.
- const priceList = await client.priceLists.create({
- name: 'EU wholesale',
- description: 'Tiered pricing for verified B2B customers',
- match_policy: 'all',
- starts_at: '2026-06-01T00:00:00Z',
- ends_at: '2026-09-01T00:00:00Z',
- rules: [
- {
- type: 'customer_group_rule',
- preferences: { customer_group_ids: ['cg_aBc123'] },
- },
- {
- type: 'volume_rule',
- preferences: { min_quantity: 10 },
- },
- ],
- prices: [
- {
- variant_id: 'variant_xY9',
- currency: 'USD',
- amount: '19.99',
- compare_at_amount: '24.99',
- },
- {
- variant_id: 'variant_aB7',
- currency: 'USD',
- amount: '21.99',
- },
- ],
+ // A split checkout: the payment is shared, so what comes back is this order's
+ // own share. refund_amount names part of that share, keeping the rest back.
+ const order = await client.orders.cancel('or_UkLWZg9DAJ', {
+ cancel_reason_id: 'ocr_UkLWZg9DAJ',
+ cancel_note: 'Supplier could not deliver in time',
+ refund_payments: true,
+ refund_amount: '25.00',
})
- lang: bash
label: Spree CLI
- source: spree api post /price_lists -d '{"name":"EU wholesale","description":"Tiered
- pricing for verified B2B customers","match_policy":"all","starts_at":"2026-06-01T00:00:00Z","ends_at":"2026-09-01T00:00:00Z","rules":[{"type":"customer_group_rule","preferences":{"customer_group_ids":["cg_aBc123"]}},{"type":"volume_rule","preferences":{"min_quantity":10}}],"prices":[{"variant_id":"variant_xY9","currency":"USD","amount":"19.99","compare_at_amount":"24.99"},{"variant_id":"variant_aB7","currency":"USD","amount":"21.99"}]}'
+ source: spree api patch /orders/{id}/cancel -d '{"cancel_reason_id":"ocr_UkLWZg9DAJ","cancel_note":"Supplier
+ could not deliver in time","refund_payments":true,"refund_amount":"25.00"}'
parameters:
- name: x-spree-api-key
in: header
@@ -18632,138 +18816,143 @@ paths:
- 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:
- '201':
- description: price list created (server-to-server — rules + prices)
+ '200':
+ description: order canceled
content:
application/json:
example:
- id: pl_EfhxLZ9ck8
- name: EU wholesale
- description:
- status: draft
- position: 3
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: false
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ coupon_code:
+ fulfillment_status: canceled
+ payment_status: none
+ completed_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '110.00'
+ gift_card_total: '0.00'
+ amount_due: '0.00'
+ delivery_total: '100.00'
+ fee_total: '0.00'
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ tax_provider:
+ external_references: {}
+ status: canceled
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ metadata: {}
+ cancel_note:
+ canceled_at: '2026-01-15T12:00:00.000Z'
+ approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- price_adjustment_percentage:
- automatic_pricing: false
- currently_active: false
- products_count: 1
- prices_count: 2
- price_adjustment_tiers: []
- schema:
- "$ref": "#/components/schemas/PriceList"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ payment_total: '0.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ approver_type:
+ canceler_id: adm_UkLWZg9DAJ
+ canceler_type: admin_user
+ created_by_id:
+ created_by_type:
+ cancel_reason_id:
+ cancel_reason_name:
+ customer_id: cust_UkLWZg9DAJ
+ freight_summary:
requestBody:
content:
application/json:
schema:
type: object
- required:
- - name
properties:
- name:
- type: string
- example: EU wholesale
- description:
- type: string
- nullable: true
- starts_at:
+ cancel_reason_id:
type: string
- nullable: true
- example: '2026-06-01T00:00:00Z'
- ends_at:
+ description: Why the order was canceled — the id of one of the store's
+ cancellation reasons.
+ cancel_note:
type: string
- nullable: true
- example: '2026-09-01T00:00:00Z'
- match_policy:
+ 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
- enum:
- - all
- - any
- example: all
- position:
- type: integer
- example: 1
- 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
- example: volume_rule
- 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
- example: variant_xY9
- currency:
- type: string
- example: USD
- amount:
- type: string
- nullable: true
- example: '19.99'
- compare_at_amount:
- type: string
- nullable: true
- example: '24.99'
- "/api/v3/admin/price_lists/{id}":
- parameters:
- - name: id
- in: path
- required: true
- schema:
- type: string
- get:
- summary: Get a price list
+ 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:
- - Pricing
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_products` (for API-key authentication)."
+ description: |-
+ Approves an order (e.g., for fraud review).
+
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18775,10 +18964,10 @@ paths:
secretKey: 'sk_xxx',
})
- const priceList = await client.priceLists.get('pl_xxx')
+ const order = await client.orders.approve('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /price_lists/{id}
+ source: spree api patch /orders/{id}/approve -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -18788,64 +18977,117 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: expand
- in: query
- required: false
+ - name: id
+ in: path
+ required: true
+ description: Order ID
schema:
type: string
responses:
'200':
- description: price list found
+ description: order approved
content:
application/json:
example:
- id: pl_UkLWZg9DAJ
- name: Wholesale
- description:
- status: draft
- position: 1
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: true
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '110.00'
+ gift_card_total: '0.00'
+ amount_due: '110.00'
+ delivery_total: '100.00'
+ fee_total: '0.00'
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ tax_provider:
+ external_references: {}
+ status: placed
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- price_adjustment_percentage:
- automatic_pricing: false
- currently_active: false
- products_count: 0
- prices_count: 0
- price_adjustment_tiers: []
- schema:
- "$ref": "#/components/schemas/PriceList"
- '404':
- description: price list not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Price list not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a price list
+ payment_total: '0.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id: adm_UkLWZg9DAJ
+ approver_type: admin_user
+ canceler_id:
+ canceler_type:
+ created_by_id:
+ created_by_type:
+ cancel_reason_id:
+ cancel_reason_name:
+ customer_id: cust_UkLWZg9DAJ
+ freight_summary:
+ "/api/v3/admin/orders/{id}/resend_confirmation":
+ post:
+ summary: Resend confirmation email
tags:
- - Pricing
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a price list. The optional `rules:` array reconciles nested
- STI-typed price rules in a single round-trip — existing rules update
- by `id`, new rules build, missing rules destroy. Mirrors the
- promotion editor's "save the whole thing on Save" pattern.
-
+ Publishes the order.completed event to trigger confirmation email delivery.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18857,12 +19099,10 @@ paths:
secretKey: 'sk_xxx',
})
- const priceList = await client.priceLists.update('pl_xxx', {
- name: 'Wholesale (Q3)',
- })
+ await client.orders.resendConfirmation('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /price_lists/{id} -d '{"name":"Wholesale (Q3)"}'
+ source: spree api post /orders/{id}/resend_confirmation -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -18872,131 +19112,117 @@ paths:
- 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: price list updated with nested rules
+ description: confirmation resent
content:
application/json:
example:
- id: pl_UkLWZg9DAJ
- name: Wholesale (Q3)
- description:
- status: draft
- position: 1
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ withdrawal_period_ends_at:
+ within_withdrawal_period: true
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id:
+ company_name:
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.00'
+ adjustment_total: '0.00'
+ discount_total: '0.00'
+ tax_total: '0.00'
+ included_tax_total: '0.00'
+ additional_tax_total: '0.00'
+ total: '110.00'
+ gift_card_total: '0.00'
+ amount_due: '110.00'
+ delivery_total: '100.00'
+ fee_total: '0.00'
+ store_credit_total: '0.00'
+ covered_by_store_credit: false
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ country_isos:
+ - US
+ supported_locales:
+ - en
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ tax_provider:
+ external_references: {}
+ status: placed
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- price_adjustment_percentage:
- automatic_pricing: false
- currently_active: false
- products_count: 0
- prices_count: 0
- price_adjustment_tiers: []
- 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
- example: volume_rule
- 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
- example: price_aBc123
- variant_id:
- type: string
- example: variant_xY9
- currency:
- type: string
- example: USD
- amount:
- type: string
- nullable: true
- example: '12.50'
- compare_at_amount:
- type: string
- nullable: true
- example: '15.00'
- delete:
- summary: Delete a price list
+ payment_total: '0.00'
+ commission_amount_total: '0.00'
+ commission_tax_total: '0.00'
+ commission_total: '0.00'
+ 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: cust_UkLWZg9DAJ
+ freight_summary:
+ "/api/v3/admin/returns":
+ get:
+ summary: List returns
tags:
- - Pricing
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes the price list. Associated prices are removed asynchronously.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Every return in the store, across all orders.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- await client.priceLists.delete('pl_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api delete /price_lists/{id}
+ **Required scope:** `read_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -19008,186 +19234,144 @@ paths:
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
- in the future the list is marked `scheduled` instead, matching the
- legacy admin behaviour.
+ - 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
+ Filter 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).
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ <Accordion title="Filters through associations">
- const priceList = await client.priceLists.activate('pl_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api patch /price_lists/{id}/activate -d '{ ... }'
- 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:
- example:
- id: pl_UkLWZg9DAJ
- name: Wholesale
- description:
- status: active
- position: 1
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- price_adjustment_percentage:
- automatic_pricing: false
- currently_active: true
- products_count: 0
- prices_count: 0
- price_adjustment_tiers: []
- 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)."
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ | Prefix | Attributes |
+ |---|---|
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
- const priceList = await client.priceLists.deactivate('pl_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api patch /price_lists/{id}/deactivate -d '{ ... }'
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
+ </Accordion>
+
+ **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: price list deactivated
+ description: returns listed
content:
application/json:
example:
- id: pl_UkLWZg9DAJ
- name: Price List 2
- description:
- status: inactive
- position: 1
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- price_adjustment_percentage:
- automatic_pricing: false
- currently_active: false
- products_count: 0
- prices_count: 0
- price_adjustment_tiers: []
+ data:
+ - id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.00'
+ refund_tax_total: '0.00'
+ approved_at:
+ received_at:
+ refunded_at:
+ canceled_at:
+ memo: Item did not fit
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ stock_location_id: sloc_UkLWZg9DAJ
+ created_by_id:
+ created_by_type:
+ refunded_total: '0.00'
+ refundable_total: '10.00'
+ documents: []
+ labels: []
+ deliveries: []
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/PriceList"
- "/api/v3/admin/prices":
+ 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 prices
+ summary: List order returns
tags:
- - Pricing
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Generic prices endpoint covering both base prices and price-list
- overrides. Filter with Ransack: `q[price_list_id_eq]=…`,
- `q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).
-
- The admin spreadsheet uses this with server-side pagination so it
- scales past the metadata-PATCH path on `/price_lists/:id`.
-
-
- **Required scope:** `read_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ The returns opened on one order.
- const { data: prices } = await client.prices.list({
- price_list_id_eq: 'pl_xxx',
- currency_eq: 'USD',
- expand: ['variant'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /prices -d '{"price_list_id_eq":"pl_xxx","currency_eq":"USD","expand":["variant"]}'
+ **Required scope:** `read_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -19199,21 +19383,28 @@ paths:
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 the variant's SKU, option value or product name, as variant
- search does.
+ 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
@@ -19226,106 +19417,90 @@ paths:
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
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `compare_at_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `min_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `price_list_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
<Accordion title="Filters through associations">
- Prefix an associated record's attribute with the association, as in `q[price_list_id_eq]`. The same predicates apply.
+ Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
- | `price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |
- | `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` |
- | `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
- | `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
- | `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `reason_` | `active`, `created_at`, `id`, `name`, `updated_at` |
</Accordion>
- **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.
+ **Sort by:** `created_at`, `id`, `number`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: Price
+ table: Return
sortable:
- - amount
- - compare_at_amount
- created_at
- - currency
- id
- - min_quantity
- - price_list_id
+ - number
+ - status
- updated_at
- - variant_id
responses:
'200':
- description: prices found
+ description: returns listed
content:
application/json:
example:
data:
- - id: price_UkLWZg9DAJ
- currency: USD
- amount: '19.99'
- compare_at_amount:
- price_list_id:
- min_quantity: 1
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- - id: price_gbHJdmfrXB
- currency: USD
- amount: '19.99'
- compare_at_amount:
- price_list_id:
- min_quantity: 1
- variant_id: variant_gbHJdmfrXB
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- - id: price_EfhxLZ9ck8
- currency: USD
- amount: '5.00'
- compare_at_amount:
- price_list_id: pl_UkLWZg9DAJ
- min_quantity: 1
- variant_id: variant_gbHJdmfrXB
+ - id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.00'
+ refund_tax_total: '0.00'
+ approved_at:
+ received_at:
+ refunded_at:
+ canceled_at:
+ memo: Item did not fit
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ stock_location_id: sloc_UkLWZg9DAJ
+ created_by_id:
+ created_by_type:
+ refunded_total: '0.00'
+ refundable_total: '10.00'
+ documents: []
+ labels: []
+ deliveries: []
meta:
page: 1
limit: 25
- count: 3
+ count: 1
pages: 1
from: 1
- to: 3
- in: 3
+ to: 1
+ in: 1
previous:
next:
schema:
@@ -19334,44 +19509,24 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/Price"
+ "$ref": "#/components/schemas/Return"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
- post:
- summary: Create a price
+ "/api/v3/admin/orders/{order_id}/returns/{return_id}/labels":
+ get:
+ summary: List return labels
tags:
- - Pricing
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a single price. Omit `price_list_id` to create a base price.
- For more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.
-
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ The shipping labels issued for sending one return back to the store.
- const price = await client.prices.create({
- variant_id: 'variant_xxx',
- currency: 'USD',
- amount: '19.99',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /prices -d '{"variant_id":"variant_xxx","currency":"USD","amount":"19.99"}'
+ **Required scope:** `read_orders` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -19383,65 +19538,128 @@ paths:
required: true
schema:
type: string
- responses:
- '201':
- description: price created
- content:
- application/json:
- example:
- id: price_uw2YK1rnl0
- currency: EUR
- amount: '9.99'
- compare_at_amount:
- price_list_id:
- min_quantity: 1
- variant_id: variant_EfhxLZ9ck8
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
+ - 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: purchased
+ carrier: ups
+ carrier_name: UPS
+ service: Ground
+ tracking_number: 1Z879E930346830006
+ currency: USD
+ format: pdf
+ external_id: shp_3
+ metadata: {}
+ refunded_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ owner_id: ret_UkLWZg9DAJ
+ owner_type: return
+ cost: '7.25'
+ integration_id:
+ file_pending: false
+ download_url:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Price"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - variant_id
- - currency
- properties:
- variant_id:
- type: string
- example: variant_xY9
- currency:
- type: string
- example: USD
- amount:
- type: string
- nullable: true
- example: '19.99'
- compare_at_amount:
- type: string
- nullable: true
- example: '24.99'
- price_list_id:
- type: string
- nullable: true
- example: pl_aBc123
- "/api/v3/admin/prices/{id}":
- parameters:
- - name: id
- in: path
- required: true
- schema:
- type: string
+ 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: Get a price
+ summary: List payment methods
tags:
- - Pricing
+ - Payment Methods
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_products` (for API-key authentication)."
+ description: |-
+ Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19453,10 +19671,10 @@ paths:
secretKey: 'sk_xxx',
})
- const price = await client.prices.get('price_xxx')
+ const { data: paymentMethods } = await client.paymentMethods.list()
- lang: bash
label: Spree CLI
- source: spree api get /prices/{id}
+ source: spree api get /payment_methods
parameters:
- name: x-spree-api-key
in: header
@@ -19468,41 +19686,113 @@ paths:
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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: price found
- content:
- application/json:
- example:
- id: price_EfhxLZ9ck8
- currency: USD
- amount: '5.00'
- compare_at_amount:
- price_list_id: pl_UkLWZg9DAJ
- min_quantity: 1
- variant_id: variant_gbHJdmfrXB
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/Price"
- '404':
- description: price not found
+ description: payment methods found
content:
application/json:
example:
- error:
- code: record_not_found
- message: Price not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a price
+ data:
+ - id: pm_UkLWZg9DAJ
+ name: Check 2
+ description:
+ type: check
+ session_required: false
+ source_required: false
+ metadata: {}
+ active: true
+ auto_capture:
+ capture_method:
+ resolved_capture_method: checkout
+ storefront_visible: true
+ position: 1
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferences: {}
+ logo_url:
+ docs_url:
+ third_party: false
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/admin/payment_methods/types":
+ get:
+ summary: List available payment provider types
tags:
- - Pricing
+ - Payment Methods
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_products` (for API-key authentication)."
+ 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.
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19514,12 +19804,10 @@ paths:
secretKey: 'sk_xxx',
})
- const price = await client.prices.update('price_xxx', {
- amount: '12.34',
- })
+ const { data: types } = await client.paymentMethods.types()
- lang: bash
label: Spree CLI
- source: spree api patch /prices/{id} -d '{"amount":"12.34"}'
+ source: spree api get /payment_methods/types
parameters:
- name: x-spree-api-key
in: header
@@ -19533,44 +19821,75 @@ paths:
type: string
responses:
'200':
- description: price updated
+ description: provider types found
content:
application/json:
example:
- id: price_EfhxLZ9ck8
- currency: USD
- amount: '12.34'
- compare_at_amount:
- price_list_id: pl_UkLWZg9DAJ
- min_quantity: 1
- variant_id: variant_gbHJdmfrXB
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- 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
+ data:
+ - type: bogus
+ label: Bogus
+ description:
+ schema:
+ type: object
+ properties:
+ dummy_key:
+ type: string
+ default: PUBLICKEY123
+ dummy_secret_key:
+ type:
+ - string
+ - 'null'
+ x-spree-secret: true
+ additionalProperties: false
+ logo_url:
+ docs_url:
+ third_party: true
+ installed: false
+ - type: check
+ label: Check
+ description:
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ logo_url:
+ docs_url:
+ third_party: false
+ installed: true
+ - type: custom_payment_source_method
+ label: Custom Payment Source Method
+ description:
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ logo_url:
+ docs_url:
+ third_party: false
+ installed: false
+ - type: store_credit
+ label: Store Credit
+ description:
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ logo_url:
+ docs_url:
+ third_party: false
+ installed: true
+ "/api/v3/admin/payment_methods/{id}":
+ get:
+ summary: Show a payment method
tags:
- - Pricing
+ - Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes the price (acts_as_paranoid).
+ Returns a payment method by ID.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19582,10 +19901,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.prices.delete('price_xxx')
+ const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /prices/{id}
+ source: spree api get /payment_methods/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -19597,31 +19916,62 @@ paths:
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:
- '204':
- description: price deleted
- "/api/v3/admin/prices/bulk_upsert":
- post:
- summary: Bulk-upsert prices
+ '200':
+ description: payment method found
+ content:
+ application/json:
+ example:
+ id: pm_UkLWZg9DAJ
+ name: Check 4
+ description:
+ type: check
+ session_required: false
+ source_required: false
+ metadata: {}
+ active: true
+ auto_capture:
+ capture_method:
+ resolved_capture_method: checkout
+ storefront_visible: true
+ position: 1
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferences: {}
+ logo_url:
+ docs_url:
+ third_party: false
+ "/api/v3/admin/orders/{order_id}/payments":
+ get:
+ summary: List payments
tags:
- - Pricing
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Upserts a batch of prices in a single SQL round trip.
-
- Each row either:
- * targets an existing price by `id`, OR
- * matches on the unique key `(variant_id, currency, price_list_id)` —
- updating the existing row if one exists, creating one otherwise.
-
- Model callbacks (e.g. PriceHistory) are bypassed; this is a
- bulk-write fast path for the admin spreadsheet. The response
- carries `price_count` — the number of rows touched.
-
+ Returns all payments for an order.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `read_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19633,25 +19983,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { price_count } = await client.prices.bulkUpsert({
- prices: [
- {
- variant_id: 'variant_xxx',
- currency: 'USD',
- price_list_id: 'pl_xxx',
- amount: '11.11',
- },
- {
- variant_id: 'variant_yyy',
- currency: 'USD',
- price_list_id: 'pl_xxx',
- amount: '22.22',
- },
- ],
- })
+ const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api post /prices/bulk_upsert -d '{"prices":[{"variant_id":"variant_xxx","currency":"USD","price_list_id":"pl_xxx","amount":"11.11"},{"variant_id":"variant_yyy","currency":"USD","price_list_id":"pl_xxx","amount":"22.22"}]}'
+ source: spree api get /orders/{order_id}/payments
parameters:
- name: x-spree-api-key
in: header
@@ -19661,186 +19996,26 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- responses:
- '200':
- description: prices upserted
- content:
- application/json:
- example:
- price_count: 2
- schema:
- type: object
- properties:
- price_count:
- type: integer
- '422':
- description: missing prices key
- content:
- application/json:
- example:
- error:
- code: missing_prices
- message: prices is required (send an empty array to no-op).
- 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
- example: price_aBc123
- variant_id:
- type: string
- example: variant_xY9
- currency:
- type: string
- example: USD
- price_list_id:
- type: string
- nullable: true
- example: pl_aBc123
- amount:
- type: string
- nullable: true
- example: '19.99'
- compare_at_amount:
- type: string
- nullable: true
- example: '24.99'
- "/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.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { price_count } = await client.prices.bulkDestroy({
- ids: ['price_xxx', 'price_yyy'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api delete /prices/bulk_destroy -d '{"ids":["price_xxx","price_yyy"]}'
- 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:
- example:
- price_count: 1
- 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.
-
- **Required scope:** `read_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /products/{product_id}/custom_fields
- 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
+ - 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., custom_field_definition).
- Use dot notation for nested expand (max 4 levels).
+ 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., key,value,namespace).
+ description: Comma-separated list of fields to include (e.g., amount,status,number,response_code).
id is always included.
schema:
type: string
@@ -19858,37 +20033,95 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
+ | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `avs_response` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `cvv_response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `cvv_response_message` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `response_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `state` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `status` | One of `checkout`, `processing`, `pending`, `completed`, `failed`, `void`, `invalid` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[order_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `payment_method_` | `active`, `created_at`, `id`, `name`, `position`, `storefront_visible`, `type`, `updated_at` |
+
+ </Accordion>
+
+ **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: CustomField
+ table: Payment
sortable:
+ - amount
+ - avs_response
- created_at
+ - cvv_response_code
+ - cvv_response_message
- id
+ - response_code
+ - state
+ - status
- updated_at
responses:
'200':
- description: custom fields found
+ description: payments found
content:
application/json:
example:
data:
- - id: cf_UkLWZg9DAJ
- label: Title
- field_type: short_text
- key: custom.title
- value: wool
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: BGS-343039b69b86
+ number: R1001-P1
+ status: completed
+ amount: '110.00'
+ source_type: credit_card
+ source_id: card_UkLWZg9DAJ
+ source:
+ id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ metadata: {}
+ avs_response:
+ cvv_response_code:
+ cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- storefront_visible: true
- custom_field_definition_id: cfdef_UkLWZg9DAJ
+ captured_amount: '0.00'
+ order_id: or_UkLWZg9DAJ
meta:
page: 1
limit: 25
@@ -19900,16 +20133,16 @@ paths:
previous:
next:
post:
- summary: Create a product custom field
+ summary: Create a payment
tags:
- - Products
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.
+ Creates a new payment for the order.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19921,13 +20154,14 @@ paths:
secretKey: 'sk_xxx',
})
- const customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {
- custom_field_definition_id: 'cfdef_AbC123XyZ',
- value: 'wool',
+ const payment = await client.orders.payments.create('or_UkLWZg9DAJ', {
+ payment_method_id: 'pm_UkLWZg9DAJ',
+ amount: '99.99',
+ source_id: 'cc_UkLWZg9DAJ',
})
- lang: bash
label: Spree CLI
- source: spree api post /products/{product_id}/custom_fields -d '{"custom_field_definition_id":"cfdef_AbC123XyZ","value":"wool"}'
+ source: spree api post /orders/{order_id}/payments -d '{"payment_method_id":"pm_UkLWZg9DAJ","amount":"99.99","source_id":"cc_UkLWZg9DAJ"}'
parameters:
- name: x-spree-api-key
in: header
@@ -19937,65 +20171,67 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: product_id
+ - name: order_id
in: path
required: true
+ description: Order ID
schema:
type: string
responses:
'201':
- description: custom field created
+ description: payment created
content:
application/json:
example:
- id: cf_gbHJdmfrXB
- label: Description
- field_type: long_text
- key: custom.description
- value: A longer description
+ id: py_gbHJdmfrXB
+ payment_method_id: pm_EfhxLZ9ck8
+ response_code:
+ number: R1002-P1
+ status: checkout
+ amount: '110.00'
+ source_type:
+ source_id:
+ source:
+ metadata: {}
+ avs_response:
+ cvv_response_code:
+ cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- storefront_visible: true
- custom_field_definition_id: cfdef_gbHJdmfrXB
- '422':
- description: duplicate definition for the same product
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Custom field definition has already been taken
- details:
- custom_field_definition_id:
- - value: 1
- code: taken
- message: has already been taken
- specific: false
+ captured_amount: '0.00'
+ order_id: or_gbHJdmfrXB
requestBody:
content:
application/json:
schema:
type: object
required:
- - custom_field_definition_id
- - value
+ - payment_method_id
properties:
- custom_field_definition_id:
+ payment_method_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}":
+ description: Payment method ID
+ amount:
+ type: string
+ example: '99.99'
+ source_id:
+ type: string
+ description: Payment source ID
+ "/api/v3/admin/orders/{order_id}/payments/{id}":
get:
- summary: Show a product custom field
+ summary: Show a payment
tags:
- - Products
+ - Payments
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_products` (for API-key authentication)."
+ description: |-
+ Returns details of a specific payment.
+
+ **Required scope:** `read_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20007,10 +20243,10 @@ paths:
secretKey: 'sk_xxx',
})
- const customField = await client.products.customFields.get('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
+ const payment = await client.orders.payments.get('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /products/{product_id}/custom_fields/{id}
+ source: spree api get /orders/{order_id}/payments/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -20020,58 +20256,83 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: product_id
+ - 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., custom_field_definition).
- Use dot notation for nested expand (max 4 levels).
+ 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., key,value,namespace).
+ 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: custom field found
+ description: payment found
content:
application/json:
example:
- id: cf_UkLWZg9DAJ
- label: Title
- field_type: short_text
- key: custom.title
- value: wool
+ id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: BGS-4a236d40ef07
+ number: R1001-P1
+ status: completed
+ amount: '110.00'
+ source_type: credit_card
+ source_id: card_UkLWZg9DAJ
+ source:
+ id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ metadata: {}
+ avs_response:
+ cvv_response_code:
+ cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- storefront_visible: true
- custom_field_definition_id: cfdef_UkLWZg9DAJ
+ captured_amount: '0.00'
+ order_id: or_UkLWZg9DAJ
+ "/api/v3/admin/orders/{order_id}/payments/{id}/capture":
patch:
- summary: Update a product custom field
+ summary: Capture a payment
tags:
- - Products
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.
+ Captures a pending payment.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20083,12 +20344,11 @@ paths:
secretKey: 'sk_xxx',
})
- const customField = await client.products.customFields.update('prod_UkLWZg9DAJ', 'cf_AbC123XyZ', {
- value: 'cotton',
- })
+ const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /products/{product_id}/custom_fields/{id} -d '{"value":"cotton"}'
+ source: spree api patch /orders/{order_id}/payments/{id}/capture -d '{ ...
+ }'
parameters:
- name: x-spree-api-key
in: header
@@ -20098,51 +20358,79 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: product_id
+ - 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: custom field updated
+ description: payment captured
content:
application/json:
example:
- id: cf_UkLWZg9DAJ
- label: Title
- field_type: short_text
- key: custom.title
- value: cotton
+ id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: BGS-ccc19f06b194
+ number: R1001-P1
+ status: completed
+ amount: '110.00'
+ source_type: credit_card
+ source_id: card_UkLWZg9DAJ
+ source:
+ id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ metadata: {}
+ avs_response:
+ cvv_response_code:
+ cvv_response_message:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- storefront_visible: true
- custom_field_definition_id: cfdef_UkLWZg9DAJ
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - value
- properties:
- value:
- description: New value
- delete:
- summary: Delete a product custom field
+ captured_amount: '110.00'
+ order_id: or_UkLWZg9DAJ
+ '422':
+ description: capture failed
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: 'Bogus Gateway: Forced failure'
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/orders/{order_id}/payments/{id}/void":
+ patch:
+ summary: Void a payment
tags:
- - Products
+ - Payments
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_products` (for API-key authentication)."
+ description: |-
+ Voids a payment.
+
+ **Required scope:** `write_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20154,10 +20442,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.products.customFields.delete('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
+ const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /products/{product_id}/custom_fields/{id}
+ source: spree api patch /orders/{order_id}/payments/{id}/void -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -20167,33 +20455,84 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: product_id
+ - 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:
- '204':
- description: custom field deleted
- "/api/v3/admin/products/{product_id}/translations":
+ '200':
+ description: payment voided
+ content:
+ application/json:
+ example:
+ id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: void-BGS-11f2e975ba0c
+ number: R1001-P1
+ status: void
+ amount: '110.00'
+ source_type: credit_card
+ source_id: card_UkLWZg9DAJ
+ source:
+ id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ customer_id:
+ payment_method_id: pm_gbHJdmfrXB
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ metadata: {}
+ avs_response:
+ cvv_response_code:
+ cvv_response_message:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ captured_amount: '0.00'
+ order_id: or_UkLWZg9DAJ
+ "/api/v3/admin/price_lists":
get:
- summary: List product translations
+ summary: List price lists
tags:
- - Products
+ - Pricing
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.
+ Returns the price lists configured for the current store.
**Required scope:** `read_products` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: priceLists } = await client.priceLists.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /price_lists
parameters:
- name: x-spree-api-key
in: header
@@ -20205,245 +20544,43 @@ paths:
required: true
schema:
type: string
- - name: product_id
- in: path
- required: true
+ - name: q[search]
+ in: query
+ required: false
schema:
type: string
- responses:
- '200':
- description: translations found
- content:
- application/json:
- example:
- data:
- resource_id: prod_UkLWZg9DAJ
- resource_type: product
- translations:
- de:
- name: Espressomaschine
- description:
- slug: espressomaschine
- meta_description:
- meta_title:
- translated_field_count: 2
- fr:
- name:
- description:
- slug:
- meta_description:
- meta_title:
- translated_field_count: 0
- fields:
- - key: name
- type: string
- source: Espresso Machine
- - key: description
- type: html
- source: |-
- Atque esse occaecati recusandae quam sit blanditiis accusamus. Et temporibus optio quos est esse nobis odit nihil. Magnam quo illum voluptas dolorum quidem. Modi rerum labore praesentium laborum veritatis iusto.
- Tempora exercitationem sed vero itaque nihil odio distinctio explicabo. Corporis nesciunt minus veritatis beatae quaerat facilis similique eius. Esse dolores suscipit iusto totam velit ipsa.
- Aut saepe quibusdam mollitia amet. Eius beatae facilis asperiores maiores. Fuga doloremque provident perspiciatis natus a quaerat reprehenderit occaecati. Eius deserunt commodi placeat delectus.
- Consequatur quas ipsum voluptas quis. Vel cumque molestiae magnam optio. Recusandae eum cum sequi autem fugiat animi tenetur.
- - key: slug
- type: string
- source: espresso-machine
- - key: meta_description
- type: string
- source:
- - key: meta_title
- type: string
- source:
- default_locale: en
- supported_locales:
- - de
- - en
- - fr
- "/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.
-
- **Required scope:** `read_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: products } = await client.products.list({
- search: 'shirt',
- status_eq: 'active',
- sort: '-created_at',
- limit: 25,
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /products -d '{"search":"shirt","status_eq":"active","sort":"-created_at","limit":25}'
- parameters:
- - name: x-spree-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.
+ 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: sort
+ - name: q
in: query
required: false
- description: Sort field (e.g., name, -name, price, -price, best_selling)
+ style: deepObject
+ explode: true
schema:
- type: string
- - name: expand
+ 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 associations to expand (e.g., variants, media,
- option_types, categories). Use dot notation for nested expand (max 4 levels).
schema:
type: string
- - name: fields
+ - name: expand
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price,status).
- id is always included.
+ description: 'Comma-separated associations to embed. Supported: `price_rules`.'
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
@@ -20452,130 +20589,82 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
- | `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `catalog_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `ends_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `match_policy` | One of `all`, `any` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `status` | One of `draft`, `active`, `inactive`, `scheduled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
- | `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
- | `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
- | `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
- | `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` |
- | `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
- | `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
- | `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
- | `labels_` | `created_at`, `id`, `name`, `updated_at` |
- | `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
- | `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
- | `product_type_` | `created_at`, `id`, `name`, `updated_at` |
- | `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
- | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `store_` | `created_at`, `id`, `name`, `updated_at` |
- | `tags_` | `created_at`, `id`, `name`, `updated_at` |
- | `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` |
- | `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
- | `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
- | `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
-
- </Accordion>
-
- Also filters and sorts on the store's searchable custom fields, as `q[cf_<namespace>_<key>_<predicate>]` and `sort=cf_<namespace>_<key>`.
-
- **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.
+ **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: Product
+ table: PriceList
sortable:
- - available_on
- - best_selling
+ - catalog_id
- created_at
- - description
- - discontinue_on
+ - ends_at
- id
- - manual
+ - match_policy
- name
- - price
- - seller_id
- - slug
+ - position
+ - starts_at
- status
- updated_at
- custom_fields: true
responses:
'200':
- description: products found
+ description: price lists found
content:
application/json:
example:
data:
- - id: prod_UkLWZg9DAJ
- name: Product 966550
- slug: product-966550
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 1
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: Saepe quas nemo facilis nam. Voluptatem facere nam
- impedit sunt minus possimus totam ullam. Pariatur ullam sed tenetur
- quibusdam deleniti.
- description_html: Saepe quas nemo facilis nam. Voluptatem facere
- nam impedit sunt minus possimus totam ullam. Pariatur ullam sed
- tenetur quibusdam deleniti.
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- currency: USD
- amount: '19.99'
- compare_at_amount:
- price_list_id:
- min_quantity: 1
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- original_price:
- seller_id:
- external_references: {}
- status: active
- metadata: {}
+ - id: pl_UkLWZg9DAJ
+ name: Wholesale
+ description:
+ status: draft
+ position: 1
+ match_policy: all
+ adjust_compare_at: false
+ starts_at:
+ ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- delivery_profile_id: fp_UkLWZg9DAJ
- seller_name:
- product_type_id:
- tax_category_id: taxcat_UkLWZg9DAJ
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: false
+ products_count: 0
+ prices_count: 0
+ price_adjustment_tiers: []
+ - id: pl_gbHJdmfrXB
+ name: Holiday
+ description:
+ status: draft
+ position: 2
+ match_policy: all
+ adjust_compare_at: false
+ starts_at:
+ ends_at:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: false
+ products_count: 0
+ prices_count: 0
+ price_adjustment_tiers: []
meta:
page: 1
limit: 25
- count: 1
+ count: 2
pages: 1
from: 1
- to: 1
- in: 1
+ to: 2
+ in: 2
previous:
next:
schema:
@@ -20584,35 +20673,21 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/Product"
+ "$ref": "#/components/schemas/PriceList"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: authentication_required
- message: Authentication required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a product
+ summary: Create a price list
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new product. Supports nested variants with prices and option types.
-
- Option types and values are auto-created if they don't exist.
- Prices are upserted by currency. Stock items are upserted by stock location.
-
+ Creates a new draft price list.
**Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
@@ -20626,40 +20701,45 @@ paths:
secretKey: 'sk_xxx',
})
- const product = await client.products.create({
- name: 'Premium T-Shirt',
- // Rich text: send HTML. Reads return this as plain text, plus
- // `description_html` with the markup.
- description: '<p>Soft, organic cotton.</p>',
- status: 'active',
- variants: [
+ // Server-to-server one-shot create. Ship the rules that gate the list
+ // and the exact per-variant prices in a single request — variants in
+ // `prices` implicitly become part of the list (upserted on the unique
+ // key `(variant_id, currency, price_list_id)`). Curating whole products
+ // goes through `client.priceLists.products` instead.
+ const priceList = await client.priceLists.create({
+ name: 'EU wholesale',
+ description: 'Tiered pricing for verified B2B customers',
+ match_policy: 'all',
+ starts_at: '2026-06-01T00:00:00Z',
+ ends_at: '2026-09-01T00:00:00Z',
+ rules: [
{
- sku: 'TSHIRT-S-NAVY',
- options: [
- { name: 'size', value: 'Small' },
- { name: 'color', value: 'navy' },
- ],
- prices: [
- { currency: 'USD', amount: '29.99' },
- { currency: 'EUR', amount: '27.99' },
- ],
- stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 50 }],
+ type: 'customer_group_rule',
+ preferences: { customer_group_ids: ['cg_aBc123'] },
},
{
- sku: 'TSHIRT-M-NAVY',
- options: [
- { name: 'size', value: 'Medium' },
- { name: 'color', value: 'navy' },
- ],
- prices: [{ currency: 'USD', amount: '29.99' }],
- stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 30 }],
+ type: 'volume_rule',
+ preferences: { min_quantity: 10 },
+ },
+ ],
+ prices: [
+ {
+ variant_id: 'variant_xY9',
+ currency: 'USD',
+ amount: '19.99',
+ compare_at_amount: '24.99',
+ },
+ {
+ variant_id: 'variant_aB7',
+ currency: 'USD',
+ amount: '21.99',
},
],
})
- lang: bash
label: Spree CLI
- source: spree api post /products -d '{"name":"Premium T-Shirt","description":"<p>Soft,
- organic cotton.</p>","status":"active","variants":[{"sku":"TSHIRT-S-NAVY","options":[{"name":"size","value":"Small"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99"},{"currency":"EUR","amount":"27.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":50}]},{"sku":"TSHIRT-M-NAVY","options":[{"name":"size","value":"Medium"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":30}]}]}'
+ source: spree api post /price_lists -d '{"name":"EU wholesale","description":"Tiered
+ pricing for verified B2B customers","match_policy":"all","starts_at":"2026-06-01T00:00:00Z","ends_at":"2026-09-01T00:00:00Z","rules":[{"type":"customer_group_rule","preferences":{"customer_group_ids":["cg_aBc123"]}},{"type":"volume_rule","preferences":{"min_quantity":10}}],"prices":[{"variant_id":"variant_xY9","currency":"USD","amount":"19.99","compare_at_amount":"24.99"},{"variant_id":"variant_aB7","currency":"USD","amount":"21.99"}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -20669,50 +20749,34 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: product created
+ description: price list created (server-to-server — rules + prices)
content:
application/json:
example:
- id: prod_gbHJdmfrXB
- name: New Product
- slug: new-product
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on:
- preorder_ships_at:
- purchasable: false
- preorder: false
- in_stock: false
- backorderable: false
- available: false
+ id: pl_EfhxLZ9ck8
+ name: EU wholesale
description:
- description_html:
- default_variant_id: variant_gbHJdmfrXB
- buy_box_variant_id: variant_gbHJdmfrXB
- thumbnail_url:
- tags: []
- price:
- original_price:
- seller_id:
- external_references: {}
status: draft
- metadata: {}
+ position: 3
+ match_policy: all
+ adjust_compare_at: false
+ starts_at:
+ ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- delivery_profile_id: fp_UkLWZg9DAJ
- seller_name:
- product_type_id:
- tax_category_id:
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: false
+ products_count: 1
+ prices_count: 2
+ price_adjustment_tiers: []
schema:
- "$ref": "#/components/schemas/Product"
+ "$ref": "#/components/schemas/PriceList"
'422':
description: validation error
content:
@@ -20733,133 +20797,90 @@ paths:
application/json:
schema:
type: object
+ required:
+ - name
properties:
name:
type: string
- example: Premium T-Shirt
+ example: EU wholesale
description:
type: string
- slug:
+ nullable: true
+ starts_at:
type: string
- status:
+ nullable: true
+ example: '2026-06-01T00:00:00Z'
+ ends_at:
type: string
- enum:
- - draft
- - active
- - archived
- tax_category_id:
+ nullable: true
+ example: '2026-09-01T00:00:00Z'
+ match_policy:
type: string
- description: Tax category ID
- category_ids:
- type: array
- items:
- type: string
- description: Array of category IDs
- tags:
+ enum:
+ - all
+ - any
+ example: all
+ position:
+ type: integer
+ example: 1
+ 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: string
- example:
- - eco
- - sale
+ type: object
+ required:
+ - type
+ properties:
+ type:
+ type: string
+ example: volume_rule
+ preferences:
+ type: object
+ additionalProperties: true
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.'
+ 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
- - amount
properties:
+ variant_id:
+ type: string
+ example: variant_xY9
currency:
type: string
example: USD
amount:
type: string
- example: '29.99'
+ nullable: true
+ example: '19.99'
compare_at_amount:
type: string
nullable: true
- example: '39.99'
- 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
- example: size
- value:
- type: string
- example: Small
- prices:
- type: array
- description: Per-currency prices. Upserted by currency.
- items:
- type: object
- required:
- - currency
- - amount
- properties:
- currency:
- type: string
- example: USD
- amount:
- type: string
- example: '29.99'
- compare_at_amount:
- type: string
- nullable: true
- example: '39.99'
- 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
- example: 50
- backorderable:
- type: boolean
- required:
- - name
- "/api/v3/admin/products/{id}":
+ example: '24.99'
+ "/api/v3/admin/price_lists/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
get:
- summary: Get a product
+ summary: Get a price list
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
- description: |-
- Returns a single product by ID.
-
- **Required scope:** `read_products` (for API-key authentication).
+ description: "**Required scope:** `read_products` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20871,12 +20892,10 @@ paths:
secretKey: 'sk_xxx',
})
- const product = await client.products.get('prod_86Rf07xd4z', {
- expand: ['variants', 'option_types'],
- })
+ const priceList = await client.priceLists.get('pl_xxx')
- lang: bash
label: Spree CLI
- source: spree api get /products/{id} -d '{"expand":["variants","option_types"]}'
+ source: spree api get /price_lists/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -20886,100 +20905,62 @@ paths:
- 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
+ description: price list found
content:
application/json:
example:
- id: prod_UkLWZg9DAJ
- name: Product 1002061
- slug: product-1002061
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 1
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: Illo error explicabo cupiditate consequatur. Et expedita
- velit laborum iure. Harum sit eaque nam ipsam maiores.
- description_html: Illo error explicabo cupiditate consequatur. Et
- expedita velit laborum iure. Harum sit eaque nam ipsam maiores.
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- currency: USD
- amount: '19.99'
- compare_at_amount:
- price_list_id:
- min_quantity: 1
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- original_price:
- seller_id:
- external_references: {}
- status: active
- metadata: {}
+ id: pl_UkLWZg9DAJ
+ name: Wholesale
+ description:
+ status: draft
+ position: 1
+ match_policy: all
+ adjust_compare_at: false
+ starts_at:
+ ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- delivery_profile_id: fp_UkLWZg9DAJ
- seller_name:
- product_type_id:
- tax_category_id: taxcat_UkLWZg9DAJ
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: false
+ products_count: 0
+ prices_count: 0
+ price_adjustment_tiers: []
schema:
- "$ref": "#/components/schemas/Product"
+ "$ref": "#/components/schemas/PriceList"
'404':
- description: product not found
+ description: price list not found
content:
application/json:
example:
error:
code: record_not_found
- message: Product not found
+ message: Price list not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a product
+ summary: Update a price list
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a product. Only provided fields are updated.
+ Updates a price list. The optional `rules:` array reconciles nested
+ STI-typed price rules in a single round-trip — existing rules update
+ by `id`, new rules build, missing rules destroy. Mirrors the
+ promotion editor's "save the whole thing on Save" pattern.
+
**Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
@@ -20993,14 +20974,12 @@ paths:
secretKey: 'sk_xxx',
})
- const product = await client.products.update('prod_86Rf07xd4z', {
- name: 'Updated Name',
- status: 'active',
- tags: ['eco', 'sale'],
+ const priceList = await client.priceLists.update('pl_xxx', {
+ name: 'Wholesale (Q3)',
})
- lang: bash
label: Spree CLI
- source: spree api patch /products/{id} -d '{"name":"Updated Name","status":"active","tags":["eco","sale"]}'
+ source: spree api patch /price_lists/{id} -d '{"name":"Wholesale (Q3)"}'
parameters:
- name: x-spree-api-key
in: header
@@ -21010,92 +20989,34 @@ paths:
- 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
+ description: price list updated with nested rules
content:
application/json:
example:
- id: prod_UkLWZg9DAJ
- name: Updated Name
- slug: product-1025339
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 1
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: Laborum nostrum nemo fugit temporibus consectetur omnis.
- Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias
- at perspiciatis laborum similique. Fugit adipisci iure porro architecto
- odit. Alias enim quis rem reprehenderit temporibus. Hic quae rem
- aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam
- est tempore doloribus cumque inventore vero laborum minus. Reiciendis
- autem quia eligendi possimus beatae enim. Impedit nemo quae odit
- dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae.
- Corporis ipsa alias tempora accusantium. Adipisci sapiente illum
- id voluptatum aut illo tempora.
- description_html: |-
- Laborum nostrum nemo fugit temporibus consectetur omnis. Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias at perspiciatis laborum similique. Fugit adipisci iure porro architecto odit.
- Alias enim quis rem reprehenderit temporibus. Hic quae rem aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam est tempore doloribus cumque inventore vero laborum minus. Reiciendis autem quia eligendi possimus beatae enim.
- Impedit nemo quae odit dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae. Corporis ipsa alias tempora accusantium. Adipisci sapiente illum id voluptatum aut illo tempora.
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- currency: USD
- amount: '19.99'
- compare_at_amount:
- price_list_id:
- min_quantity: 1
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- original_price:
- seller_id:
- external_references: {}
- status: active
- metadata: {}
+ id: pl_UkLWZg9DAJ
+ name: Wholesale (Q3)
+ description:
+ status: draft
+ position: 1
+ match_policy: all
+ adjust_compare_at: false
+ starts_at:
+ ends_at:
deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- delivery_profile_id: fp_UkLWZg9DAJ
- seller_name:
- product_type_id:
- tax_category_id: taxcat_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/Product"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: false
+ products_count: 0
+ prices_count: 0
+ price_adjustment_tiers: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/PriceList"
requestBody:
content:
application/json:
@@ -21104,125 +21025,78 @@ paths:
properties:
name:
type: string
- example: Premium T-Shirt
description:
type: string
- slug:
+ nullable: true
+ starts_at:
type: string
- status:
+ nullable: true
+ ends_at:
type: string
- enum:
- - draft
- - active
- - archived
- tax_category_id:
+ nullable: true
+ match_policy:
type: string
- description: Tax category ID
- category_ids:
- type: array
- items:
- type: string
- description: Array of category IDs
- tags:
+ enum:
+ - all
+ - any
+ position:
+ type: integer
+ rules:
type: array
items:
- type: string
- example:
- - eco
- - sale
+ type: object
+ required:
+ - type
+ properties:
+ id:
+ type: string
+ nullable: true
+ type:
+ type: string
+ example: volume_rule
+ preferences:
+ type: object
+ additionalProperties: true
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.'
+ 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
- required:
- - currency
- - amount
+ oneOf:
+ - required:
+ - id
+ - required:
+ - variant_id
+ - currency
properties:
+ id:
+ type: string
+ example: price_aBc123
+ variant_id:
+ type: string
+ example: variant_xY9
currency:
type: string
example: USD
amount:
type: string
- example: '29.99'
+ nullable: true
+ example: '12.50'
compare_at_amount:
type: string
nullable: true
- example: '39.99'
- 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
- example: size
- value:
- type: string
- example: Small
- prices:
- type: array
- description: Per-currency prices. Upserted by currency.
- items:
- type: object
- required:
- - currency
- - amount
- properties:
- currency:
- type: string
- example: USD
- amount:
- type: string
- example: '29.99'
- compare_at_amount:
- type: string
- nullable: true
- example: '39.99'
- 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
- example: 50
- backorderable:
- type: boolean
+ example: '15.00'
delete:
- summary: Delete a product
+ summary: Delete a price list
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes a product.
+ Soft-deletes the price list. Associated prices are removed asynchronously.
**Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
@@ -21236,10 +21110,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.products.delete('prod_86Rf07xd4z')
+ await client.priceLists.delete('pl_xxx')
- lang: bash
label: Spree CLI
- source: spree api delete /products/{id}
+ source: spree api delete /price_lists/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -21249,44 +21123,29 @@ paths:
- 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:
- example:
- error:
- code: validation_error
- message: This product is under an active supplier contract.
- details:
- base:
- - code: under_contract
- message: This product is under an active supplier contract.
- specific: false
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/products/bulk_status_update":
- post:
- summary: Bulk-update product status
+ 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:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Sets `status` on each product in `ids`. Reindexes the affected products
- for search. Cross-store IDs are silently dropped. Returns counts.
+ Transitions a draft / inactive list to `active`. If `starts_at` is
+ in the future the list is marked `scheduled` instead, matching the
+ legacy admin behaviour.
**Required scope:** `write_products` (for API-key authentication).
@@ -21301,13 +21160,10 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkStatusUpdate({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- status: 'archived',
- })
+ const priceList = await client.priceLists.activate('pl_xxx')
- lang: bash
label: Spree CLI
- source: spree api post /products/bulk_status_update -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"status":"archived"}'
+ source: spree api patch /price_lists/{id}/activate -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -21321,65 +21177,45 @@ paths:
type: string
responses:
'200':
- description: cross-store products silently dropped
- content:
- application/json:
- example:
- product_count: 0
- status: archived
- schema:
- type: object
- properties:
- product_count:
- type: integer
- status:
- type: string
- '422':
- description: invalid status
+ description: price list activated
content:
application/json:
example:
- error:
- code: invalid_status
- message: Invalid status
+ id: pl_UkLWZg9DAJ
+ name: Wholesale
+ description:
+ status: active
+ position: 1
+ match_policy: all
+ adjust_compare_at: false
+ starts_at:
+ ends_at:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: true
+ products_count: 0
+ prices_count: 0
+ price_adjustment_tiers: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - ids
- - status
- properties:
- ids:
- type: array
- items:
- type: string
- example:
- - prod_UkLWZg9DAJ
- status:
- type: string
- enum:
- - draft
- - active
- - archived
- example: archived
- "/api/v3/admin/products/bulk_add_to_categories":
- post:
- summary: Bulk-add products to categories
+ "$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:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
- description: |-
- Attaches each product in `ids` to every category (category) in `category_ids`.
- Categories from sibling stores are silently ignored.
-
-
- **Required scope:** `write_products` (for API-key authentication).
+ description: "**Required scope:** `write_products` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21391,13 +21227,10 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkAddToCategories({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- category_ids: ['cat_AbC123XyZ'],
- })
+ const priceList = await client.priceLists.deactivate('pl_xxx')
- lang: bash
label: Spree CLI
- source: spree api post /products/bulk_add_to_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
+ source: spree api patch /price_lists/{id}/deactivate -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -21411,48 +21244,48 @@ paths:
type: string
responses:
'200':
- description: products added to categories
+ description: price list deactivated
content:
application/json:
example:
- product_count: 1
- category_count: 1
+ id: pl_UkLWZg9DAJ
+ name: Price List 2
+ description:
+ status: inactive
+ position: 1
+ match_policy: all
+ adjust_compare_at: false
+ starts_at:
+ ends_at:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: false
+ products_count: 0
+ prices_count: 0
+ price_adjustment_tiers: []
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
+ "$ref": "#/components/schemas/PriceList"
+ "/api/v3/admin/prices":
+ get:
+ summary: List prices
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Detaches each product in `ids` from every category in `category_ids`.
+ Generic prices endpoint covering both base prices and price-list
+ overrides. Filter with Ransack: `q[price_list_id_eq]=…`,
+ `q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).
- **Required scope:** `write_products` (for API-key authentication).
+ The admin spreadsheet uses this with server-side pagination so it
+ scales past the metadata-PATCH path on `/price_lists/:id`.
+
+
+ **Required scope:** `read_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21464,13 +21297,14 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkRemoveFromCategories({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- category_ids: ['cat_AbC123XyZ'],
+ const { data: prices } = await client.prices.list({
+ price_list_id_eq: 'pl_xxx',
+ currency_eq: 'USD',
+ expand: ['variant'],
})
- lang: bash
label: Spree CLI
- source: spree api post /products/bulk_remove_from_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
+ source: spree api get /prices -d '{"price_list_id_eq":"pl_xxx","currency_eq":"USD","expand":["variant"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -21482,45 +21316,179 @@ paths:
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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `compare_at_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `min_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `price_list_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `variant_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[price_list_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |
+ | `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` |
+ | `variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
+ | `variant_product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
+ | `variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+
+ </Accordion>
+
+ **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: products removed from categories
+ description: prices found
content:
application/json:
example:
- product_count: 1
- category_count: 1
- 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":
+ data:
+ - id: price_UkLWZg9DAJ
+ currency: USD
+ amount: '19.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: price_gbHJdmfrXB
+ currency: USD
+ amount: '19.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_gbHJdmfrXB
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: price_EfhxLZ9ck8
+ currency: USD
+ amount: '5.00'
+ compare_at_amount:
+ price_list_id: pl_UkLWZg9DAJ
+ min_quantity: 1
+ variant_id: variant_gbHJdmfrXB
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 3
+ pages: 1
+ from: 1
+ to: 3
+ in: 3
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Price"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Bulk-add products to collections
+ summary: Create a price
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Attaches each product in `ids` to every manual collection in `collection_ids`.
- Automatic (rule-based) and sibling-store collections are silently ignored.
+ Creates a single price. Omit `price_list_id` to create a base price.
+ For more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.
**Required scope:** `write_products` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const price = await client.prices.create({
+ variant_id: 'variant_xxx',
+ currency: 'USD',
+ amount: '19.99',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /prices -d '{"variant_id":"variant_xxx","currency":"USD","amount":"19.99"}'
parameters:
- name: x-spree-api-key
in: header
@@ -21533,49 +21501,79 @@ paths:
schema:
type: string
responses:
- '200':
- description: products added to collections
+ '201':
+ description: price created
content:
application/json:
example:
- product_count: 1
- collection_count: 1
+ id: price_uw2YK1rnl0
+ currency: EUR
+ amount: '9.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_EfhxLZ9ck8
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
schema:
- type: object
- properties:
- product_count:
- type: integer
- collection_count:
- type: integer
+ "$ref": "#/components/schemas/Price"
requestBody:
content:
application/json:
schema:
type: object
required:
- - ids
- - collection_ids
+ - variant_id
+ - currency
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
+ variant_id:
+ type: string
+ example: variant_xY9
+ currency:
+ type: string
+ example: USD
+ amount:
+ type: string
+ nullable: true
+ example: '19.99'
+ compare_at_amount:
+ type: string
+ nullable: true
+ example: '24.99'
+ price_list_id:
+ type: string
+ nullable: true
+ example: pl_aBc123
+ "/api/v3/admin/prices/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ get:
+ summary: Get a price
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
- description: |-
- Detaches each product in `ids` from every collection in `collection_ids`.
+ description: "**Required scope:** `read_products` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
- **Required scope:** `write_products` (for API-key authentication).
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const price = await client.prices.get('price_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /prices/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -21589,44 +21587,39 @@ paths:
type: string
responses:
'200':
- description: products removed from collections
+ description: price found
content:
application/json:
example:
- product_count: 1
- collection_count: 1
- 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
+ id: price_EfhxLZ9ck8
+ currency: USD
+ amount: '5.00'
+ compare_at_amount:
+ price_list_id: pl_UkLWZg9DAJ
+ min_quantity: 1
+ variant_id: variant_gbHJdmfrXB
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Price"
+ '404':
+ description: price not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Price not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a price
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
- description: |-
- Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —
- re-publishing on an existing channel is a no-op. Channels from sibling stores
- are silently ignored.
-
-
- **Required scope:** `write_products` (for API-key authentication).
+ description: "**Required scope:** `write_products` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21638,13 +21631,12 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkAddToChannels({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- channel_ids: ['channel_AbC123XyZ'],
+ const price = await client.prices.update('price_xxx', {
+ amount: '12.34',
})
- lang: bash
label: Spree CLI
- source: spree api post /products/bulk_add_to_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
+ source: spree api patch /prices/{id} -d '{"amount":"12.34"}'
parameters:
- name: x-spree-api-key
in: header
@@ -21658,46 +21650,42 @@ paths:
type: string
responses:
'200':
- description: products published on channels
+ description: price updated
content:
application/json:
example:
- product_count: 1
- channel_count: 1
+ id: price_EfhxLZ9ck8
+ currency: USD
+ amount: '12.34'
+ compare_at_amount:
+ price_list_id: pl_UkLWZg9DAJ
+ min_quantity: 1
+ variant_id: variant_gbHJdmfrXB
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
schema:
- type: object
- properties:
- product_count:
- type: integer
- channel_count:
- type: integer
+ "$ref": "#/components/schemas/Price"
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
+ amount:
+ type: string
+ nullable: true
+ compare_at_amount:
+ type: string
+ nullable: true
+ delete:
+ summary: Delete a price
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Unpublishes each product in `ids` from every channel in `channel_ids`.
+ Soft-deletes the price (acts_as_paranoid).
**Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
@@ -21711,13 +21699,10 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkRemoveFromChannels({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- channel_ids: ['channel_AbC123XyZ'],
- })
+ await client.prices.delete('price_xxx')
- lang: bash
label: Spree CLI
- source: spree api post /products/bulk_remove_from_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
+ source: spree api delete /prices/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -21730,50 +21715,28 @@ paths:
schema:
type: string
responses:
- '200':
- description: products unpublished from channels
- content:
- application/json:
- example:
- product_count: 1
- channel_count: 1
- removed: 1
- 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":
+ '204':
+ description: price deleted
+ "/api/v3/admin/prices/bulk_upsert":
post:
- summary: Bulk-add tags to products
+ summary: Bulk-upsert prices
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.
+ Upserts a batch of prices in a single SQL round trip.
+
+ Each row either:
+ * targets an existing price by `id`, OR
+ * matches on the unique key `(variant_id, currency, price_list_id)` —
+ updating the existing row if one exists, creating one otherwise.
+
+ Model callbacks (e.g. PriceHistory) are bypassed; this is a
+ bulk-write fast path for the admin spreadsheet. The response
+ carries `price_count` — the number of rows touched.
+
**Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
@@ -21787,13 +21750,25 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkAddTags({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- tags: ['summer', 'sale'],
+ const { price_count } = await client.prices.bulkUpsert({
+ prices: [
+ {
+ variant_id: 'variant_xxx',
+ currency: 'USD',
+ price_list_id: 'pl_xxx',
+ amount: '11.11',
+ },
+ {
+ variant_id: 'variant_yyy',
+ currency: 'USD',
+ price_list_id: 'pl_xxx',
+ amount: '22.22',
+ },
+ ],
})
- lang: bash
label: Spree CLI
- source: spree api post /products/bulk_add_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer","sale"]}'
+ source: spree api post /prices/bulk_upsert -d '{"prices":[{"variant_id":"variant_xxx","currency":"USD","price_list_id":"pl_xxx","amount":"11.11"},{"variant_id":"variant_yyy","currency":"USD","price_list_id":"pl_xxx","amount":"22.22"}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -21807,115 +21782,74 @@ paths:
type: string
responses:
'200':
- description: tags added
+ description: prices upserted
content:
application/json:
example:
- product_count: 1
- tag_count: 2
+ price_count: 2
schema:
type: object
properties:
- product_count:
- type: integer
- tag_count:
+ price_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
- example:
- - summer
- - sale
- "/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`.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const result = await client.products.bulkRemoveTags({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- tags: ['summer'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /products/bulk_remove_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer"]}'
- 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
+ '422':
+ description: missing prices key
content:
application/json:
example:
- product_count: 1
- tag_count: 1
+ error:
+ code: missing_prices
+ message: prices is required (send an empty array to no-op).
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
required:
- - ids
- - tags
+ - prices
properties:
- ids:
- type: array
- items:
- type: string
- tags:
+ prices:
type: array
items:
- type: string
- "/api/v3/admin/products/bulk_destroy":
+ type: object
+ required:
+ - variant_id
+ - currency
+ properties:
+ id:
+ type: string
+ nullable: true
+ example: price_aBc123
+ variant_id:
+ type: string
+ example: variant_xY9
+ currency:
+ type: string
+ example: USD
+ price_list_id:
+ type: string
+ nullable: true
+ example: pl_aBc123
+ amount:
+ type: string
+ nullable: true
+ example: '19.99'
+ compare_at_amount:
+ type: string
+ nullable: true
+ example: '24.99'
+ "/api/v3/admin/prices/bulk_destroy":
delete:
- summary: Bulk-delete products
+ summary: Bulk-delete prices
tags:
- - Products
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes each product in `ids`. Returns the count actually destroyed.
+ Soft-deletes each price in `ids`. Returns the count actually destroyed.
**Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
@@ -21929,12 +21863,12 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkDestroy({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ const { price_count } = await client.prices.bulkDestroy({
+ ids: ['price_xxx', 'price_yyy'],
})
- lang: bash
label: Spree CLI
- source: spree api delete /products/bulk_destroy -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"]}'
+ source: spree api delete /prices/bulk_destroy -d '{"ids":["price_xxx","price_yyy"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -21948,15 +21882,15 @@ paths:
type: string
responses:
'200':
- description: products deleted
+ description: prices deleted
content:
application/json:
example:
- product_count: 1
+ price_count: 1
schema:
type: object
properties:
- product_count:
+ price_count:
type: integer
requestBody:
content:
@@ -21970,112 +21904,18 @@ paths:
type: array
items:
type: string
- "/api/v3/admin/translations":
+ "/api/v3/admin/products/{product_id}/custom_fields":
get:
- summary: Translation coverage for a resource type
+ summary: List product custom fields
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.
+ Returns the product's custom field values.
**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:
- example:
- data:
- resource_type: product
- default_locale: en
- locales:
- - de
- field_count: 5
- search_field: name_cont
- coverage:
- - locale: de
- translated: 0
- total: 1
- coverage: 0.0
- records:
- - id: prod_UkLWZg9DAJ
- label: Espresso Machine
- locales:
- de: 2
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- '404':
- description: resource type is not translatable
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: record not found
- "/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
- policy, returns policy, shipping policy, and any others the merchant
- has written. Every store is created with the four standard policies,
- named but empty.
-
- A marketplace seller's own policies are managed by the seller and are
- not listed here.
-
-
- **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22087,10 +21927,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: policies } = await client.policies.list()
+ const { data: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /policies
+ source: spree api get /products/{product_id}/custom_fields
parameters:
- name: x-spree-api-key
in: header
@@ -22100,27 +21940,27 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: q[search]
- in: query
- required: false
+ - name: product_id
+ in: path
+ required: true
schema:
type: string
- description: Matches any of name (partial, case-insensitive).
- - name: page
+ - name: expand
in: query
required: false
- description: Page number
+ description: Comma-separated associations to expand (e.g., custom_field_definition).
+ Use dot notation for nested expand (max 4 levels).
schema:
- type: integer
- - name: limit
+ type: string
+ - name: fields
in: query
required: false
- description: Number of records per page
+ description: Comma-separated list of fields to include (e.g., key,value,namespace).
+ id is always included.
schema:
- type: integer
+ type: string
- name: q
in: query
required: false
@@ -22131,128 +21971,62 @@ paths:
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
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `owner_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `owner_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `name`, `owner_id`, `owner_type`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: Policy
+ table: CustomField
sortable:
- created_at
- id
- - name
- - owner_id
- - owner_type
- updated_at
responses:
'200':
- description: policies listed
+ description: custom fields found
content:
application/json:
example:
data:
- - id: pol_gbHJdmfrXB
- name: Privacy Policy
- slug: privacy-policy
- body: ''
- body_html: ''
- updated_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- - id: pol_uw2YK1rnl0
- name: Restocking Policy
- slug: restocking-policy
- body: Return anything unopened within 30 days.
- body_html: "<p>Return anything unopened within 30 days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- - id: pol_EfhxLZ9ck8
- name: Returns Policy
- slug: returns-policy
- body: ''
- body_html: ''
- updated_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- - id: pol_VqXmZF31wY
- name: Shipping Policy
- slug: shipping-policy
- body: ''
- body_html: ''
- updated_at: '2026-01-15T12:00:00.000Z'
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
created_at: '2026-01-15T12:00:00.000Z'
- - id: pol_UkLWZg9DAJ
- name: Terms of Service
- slug: terms-of-service
- body: ''
- body_html: ''
updated_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
page: 1
limit: 25
- count: 5
+ count: 1
pages: 1
from: 1
- to: 5
- in: 5
+ to: 1
+ in: 1
previous:
next:
- 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:
- example:
- error:
- code: authentication_required
- message: Authentication required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a policy
+ summary: Create a product custom field
tags:
- - Policies
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a policy. `body` accepts HTML and is sanitized before it is
- stored; the stored markup is returned as `body_html`, and `body` reads
- back as plain text.
-
- The slug is derived from the name when one is not given, and is what
- the storefront addresses the policy by.
-
+ Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22264,14 +22038,13 @@ paths:
secretKey: 'sk_xxx',
})
- const policy = await client.policies.create({
- name: 'Wholesale Policy',
- body: '<p>Trade orders ship within five working days.</p>',
+ const customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {
+ custom_field_definition_id: 'cfdef_AbC123XyZ',
+ value: 'wool',
})
- lang: bash
label: Spree CLI
- source: spree api post /policies -d '{"name":"Wholesale Policy","body":"<p>Trade
- orders ship within five working days.</p>"}'
+ source: spree api post /products/{product_id}/custom_fields -d '{"custom_field_definition_id":"cfdef_AbC123XyZ","value":"wool"}'
parameters:
- name: x-spree-api-key
in: header
@@ -22281,75 +22054,65 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: product_id
+ in: path
+ required: true
schema:
type: string
responses:
'201':
- description: policy created
+ description: custom field created
content:
application/json:
example:
- id: pol_OIJLhNcSbf
- name: Wholesale Policy
- slug: wholesale-policy
- body: Trade orders ship within five working days.
- body_html: "<p>Trade orders ship within five working days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
+ id: cf_gbHJdmfrXB
+ label: Description
+ field_type: long_text
+ key: custom.description
+ value: A longer description
created_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/Policy"
- '422':
- description: validation error
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_gbHJdmfrXB
+ '422':
+ description: duplicate definition for the same product
content:
application/json:
example:
error:
code: validation_error
- message: Name can't be blank
+ message: Custom field definition has already been taken
details:
- name:
- - code: blank
- message: can't be blank
+ custom_field_definition_id:
+ - value: 1
+ code: taken
+ message: has already been taken
specific: false
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - custom_field_definition_id
+ - value
properties:
- name:
- type: string
- example: Wholesale Policy
- slug:
- type: string
- example: wholesale-policy
- body:
+ custom_field_definition_id:
type: string
- example: "<p>Trade orders ship within five working days.</p>"
- required:
- - name
- "/api/v3/admin/policies/{id}":
- parameters:
- - name: id
- in: path
- required: true
- description: Policy prefixed ID or slug
- schema:
- 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: Get a policy
+ summary: Show a product custom field
tags:
- - Policies
+ - Products
security:
- api_key: []
bearer_auth: []
- description: |-
- Returns a single policy, addressed by prefixed ID or by slug.
-
- **Required scope:** `read_settings` (for API-key authentication).
+ description: "**Required scope:** `read_products` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22361,11 +22124,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Addressable by slug as well as prefixed id.
- const policy = await client.policies.get('returns-policy')
+ const customField = await client.products.customFields.get('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
- lang: bash
label: Spree CLI
- source: spree api get /policies/{id}
+ source: spree api get /products/{product_id}/custom_fields/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -22375,45 +22137,58 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ 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: policy found
+ description: custom field found
content:
application/json:
example:
- id: pol_uw2YK1rnl0
- name: Restocking Policy
- slug: restocking-policy
- body: Return anything unopened within 30 days.
- body_html: "<p>Return anything unopened within 30 days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
+ id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
created_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/Policy"
- '404':
- description: policy not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Policy not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
- summary: Update a policy
+ summary: Update a product custom field
tags:
- - Policies
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a policy. `body` accepts HTML and is sanitized before it is stored.
+ Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22425,13 +22200,12 @@ paths:
secretKey: 'sk_xxx',
})
- const policy = await client.policies.update('returns-policy', {
- body: '<p>Return anything unopened within 60 days.</p>',
+ const customField = await client.products.customFields.update('prod_UkLWZg9DAJ', 'cf_AbC123XyZ', {
+ value: 'cotton',
})
- lang: bash
label: Spree CLI
- source: spree api patch /policies/{id} -d '{"body":"<p>Return anything unopened
- within 60 days.</p>"}'
+ source: spree api patch /products/{product_id}/custom_fields/{id} -d '{"value":"cotton"}'
parameters:
- name: x-spree-api-key
in: header
@@ -22441,49 +22215,51 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ 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: policy updated
+ description: custom field updated
content:
application/json:
example:
- id: pol_uw2YK1rnl0
- name: Restocking Policy
- slug: restocking-policy
- body: Return anything unopened within 60 days.
- body_html: "<p>Return anything unopened within 60 days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
+ id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: cotton
created_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/Policy"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - value
properties:
- name:
- type: string
- slug:
- type: string
- body:
- type: string
+ value:
+ description: New value
delete:
- summary: Delete a policy
+ summary: Delete a product custom field
tags:
- - Policies
+ - Products
security:
- api_key: []
bearer_auth: []
- description: |-
- Deletes a policy. The four policies a store is created with can be
- deleted like any other — they are conventions, not fixtures.
-
-
- **Required scope:** `write_settings` (for API-key authentication).
+ description: "**Required scope:** `write_products` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22495,10 +22271,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.policies.delete('wholesale-policy')
+ await client.products.customFields.delete('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
- lang: bash
label: Spree CLI
- source: spree api delete /policies/{id}
+ source: spree api delete /products/{product_id}/custom_fields/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -22508,44 +22284,40 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ 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: policy deleted
- "/api/v3/admin/claim_reasons":
+ 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 claim reasons
+ summary: List product digital assets
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.
-
- The vocabulary is the merchant's own — seeded with a starting set and
- edited from the dashboard. Inactive rows stay for the records that
- already reference them, but are not offered on new ones.
+ Returns the downloadable files attached to the product's variants, oldest first.
-
- **Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: reasons } = await client.claimReasons.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /claim_reasons
+ **Required scope:** `read_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -22580,48 +22352,47 @@ paths:
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
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: ClaimReason
+ table: DigitalAsset
sortable:
- - active
- created_at
- id
- - name
- updated_at
responses:
'200':
- description: claim reasons found
+ description: digital assets found
content:
application/json:
example:
data:
- - id: clr_UkLWZg9DAJ
- name: Arrived damaged
- active: true
+ - id: dig_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ filename: thinking-cat.jpg
+ content_type: image/jpeg
+ authorized_clicks:
+ authorized_days:
+ byte_size: 18090
+ provider_settings: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
+ provider_type:
+ provider_name: File
+ download_url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJ0Z252N2l0MG55YnkwbHhkczg5Y2hteTd6aXlvIiwiZGlzcG9zaXRpb24iOiJhdHRhY2htZW50OyBmaWxlbmFtZT1cInRoaW5raW5nLWNhdC5qcGdcIjsgZmlsZW5hbWUqPVVURi04Jyd0aGlua2luZy1jYXQuanBnIiwiY29udGVudF90eXBlIjoiaW1hZ2UvanBlZyIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl9rZXkifX0=--5b8cceb2276ef40ff0ebf9b7ad17b0b385fee97d/thinking-cat.jpg
+ effective_authorized_clicks: 5
+ effective_authorized_days: 7
meta:
page: 1
limit: 25
@@ -22632,44 +22403,30 @@ paths:
in: 1
previous:
next:
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: authentication_required
- message: Authentication required
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a claim reason
+ 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:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Adds a claim reason to this store. Names are unique per store, ignoring case.
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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.
- const reason = await client.claimReasons.create({
- name: 'Arrived damaged',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /claim_reasons -d '{"name":"Arrived damaged"}'
+ **Required scope:** `read_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -22677,135 +22434,76 @@ paths:
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:
- example:
- id: clr_gbHJdmfrXB
- name: A new reason
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - name
- properties:
- name:
- type: string
- example: Arrived damaged
- active:
- type: boolean
- example: true
- 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.
-
- **Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const reason = await client.claimReasons.get('clr_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /claim_reasons/{id}
- parameters:
- - name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
+ - name: product_id
+ in: path
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: claim reason found
- content:
- application/json:
- example:
- id: clr_UkLWZg9DAJ
- name: Arrived damaged
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- '404':
- description: claim reason not found
+ description: translations found
content:
application/json:
example:
- error:
- code: record_not_found
- message: Claim reason not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a claim reason
+ data:
+ resource_id: prod_UkLWZg9DAJ
+ resource_type: product
+ translations:
+ de:
+ name: Espressomaschine
+ description:
+ slug: espressomaschine
+ meta_description:
+ meta_title:
+ translated_field_count: 2
+ fr:
+ name:
+ description:
+ slug:
+ meta_description:
+ meta_title:
+ translated_field_count: 0
+ fields:
+ - key: name
+ type: string
+ source: Espresso Machine
+ - key: description
+ type: html
+ source: |-
+ Atque esse occaecati recusandae quam sit blanditiis accusamus. Et temporibus optio quos est esse nobis odit nihil. Magnam quo illum voluptas dolorum quidem. Modi rerum labore praesentium laborum veritatis iusto.
+ Tempora exercitationem sed vero itaque nihil odio distinctio explicabo. Corporis nesciunt minus veritatis beatae quaerat facilis similique eius. Esse dolores suscipit iusto totam velit ipsa.
+ Aut saepe quibusdam mollitia amet. Eius beatae facilis asperiores maiores. Fuga doloremque provident perspiciatis natus a quaerat reprehenderit occaecati. Eius deserunt commodi placeat delectus.
+ Consequatur quas ipsum voluptas quis. Vel cumque molestiae magnam optio. Recusandae eum cum sequi autem fugiat animi tenetur.
+ - key: slug
+ type: string
+ source: espresso-machine
+ - key: meta_description
+ type: string
+ source:
+ - key: meta_title
+ type: string
+ source:
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
+ "/api/v3/admin/products":
+ get:
+ summary: List products
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Renames a claim reason or retires it. Deactivating keeps it on the records
- that already carry it while removing it from the pickers.
-
+ Returns a paginated list of products for the current store.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `read_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22817,12 +22515,15 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.claimReasons.update('clr_UkLWZg9DAJ', {
- active: false,
+ const { data: products } = await client.products.list({
+ search: 'shirt',
+ status_eq: 'active',
+ sort: '-created_at',
+ limit: 25,
})
- lang: bash
label: Spree CLI
- source: spree api patch /claim_reasons/{id} -d '{"active":false}'
+ source: spree api get /products -d '{"search":"shirt","status_eq":"active","sort":"-created_at","limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -22835,116 +22536,105 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- responses:
- '200':
- description: claim reason updated
- content:
- application/json:
- example:
- id: clr_UkLWZg9DAJ
- name: Arrived damaged
- active: false
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- 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
- on a document is refused — deactivate it instead, so the history it
- explains stays readable.
-
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- await client.claimReasons.delete('clr_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /claim_reasons/{id}
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ - name: q[search]
+ in: query
+ required: false
schema:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
+ 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
- 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.
-
- The vocabulary is the merchant's own — seeded with a starting set and
- edited from the dashboard. Inactive rows stay for the records that
- already reference them, but are not offered on new ones.
-
-
- **Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: reasons } = await client.orderCancellationReasons.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /order_cancellation_reasons
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ description: Applies `in_category` to the given value.
+ - name: q[in_collection]
+ in: query
+ required: false
schema:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
+ 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
@@ -22957,6 +22647,26 @@ paths:
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
@@ -22967,12 +22677,6 @@ paths:
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
@@ -22981,34 +22685,122 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
- | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
+ | `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
+ | `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
+ | `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` |
+ | `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
+ | `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
+ | `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+ | `labels_` | `created_at`, `id`, `name`, `updated_at` |
+ | `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
+ | `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
+ | `product_type_` | `created_at`, `id`, `name`, `updated_at` |
+ | `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `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` |
+ | `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
+ | `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
+ | `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+
+ </Accordion>
+
+ Also filters and sorts on the store's searchable custom fields, as `q[cf_<namespace>_<key>_<predicate>]` and `sort=cf_<namespace>_<key>`.
+
+ **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: OrderCancellationReason
+ table: Product
sortable:
- - active
+ - 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: order cancellation reasons found
+ description: products found
content:
application/json:
example:
data:
- - id: ocr_UkLWZg9DAJ
- name: Out of stock
- active: true
+ - id: prod_UkLWZg9DAJ
+ name: Product 1066550
+ slug: product-1066550
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 1
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Saepe quas nemo facilis nam. Voluptatem facere nam
+ impedit sunt minus possimus totam ullam. Pariatur ullam sed tenetur
+ quibusdam deleniti.
+ description_html: Saepe quas nemo facilis nam. Voluptatem facere
+ nam impedit sunt minus possimus totam ullam. Pariatur ullam sed
+ tenetur quibusdam deleniti.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ currency: USD
+ amount: '19.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ original_price:
+ seller_id:
+ external_references: {}
+ status: active
+ metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id: taxcat_UkLWZg9DAJ
meta:
page: 1
limit: 25
@@ -23019,6 +22811,18 @@ paths:
in: 1
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
'401':
description: unauthorized
content:
@@ -23030,16 +22834,20 @@ paths:
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a order cancellation reason
+ summary: Create a product
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Adds a order cancellation reason to this store. Names are unique per store, ignoring case.
+ Creates a new product. Supports nested variants with prices and option types.
- **Required scope:** `write_settings` (for API-key authentication).
+ Option types and values are auto-created if they don't exist.
+ Prices are upserted by currency. Stock items are upserted by stock location.
+
+
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23051,12 +22859,40 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.orderCancellationReasons.create({
- name: 'Out of stock',
+ const product = await client.products.create({
+ name: 'Premium T-Shirt',
+ // Rich text: send HTML. Reads return this as plain text, plus
+ // `description_html` with the markup.
+ description: '<p>Soft, organic cotton.</p>',
+ status: 'active',
+ variants: [
+ {
+ sku: 'TSHIRT-S-NAVY',
+ options: [
+ { name: 'size', value: 'Small' },
+ { name: 'color', value: 'navy' },
+ ],
+ prices: [
+ { currency: 'USD', amount: '29.99' },
+ { currency: 'EUR', amount: '27.99' },
+ ],
+ stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 50 }],
+ },
+ {
+ sku: 'TSHIRT-M-NAVY',
+ options: [
+ { name: 'size', value: 'Medium' },
+ { name: 'color', value: 'navy' },
+ ],
+ prices: [{ currency: 'USD', amount: '29.99' }],
+ stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 30 }],
+ },
+ ],
})
- lang: bash
label: Spree CLI
- source: spree api post /order_cancellation_reasons -d '{"name":"Out of stock"}'
+ source: spree api post /products -d '{"name":"Premium T-Shirt","description":"<p>Soft,
+ organic cotton.</p>","status":"active","variants":[{"sku":"TSHIRT-S-NAVY","options":[{"name":"size","value":"Small"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99"},{"currency":"EUR","amount":"27.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":50}]},{"sku":"TSHIRT-M-NAVY","options":[{"name":"size","value":"Medium"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":30}]}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23071,16 +22907,45 @@ paths:
type: string
responses:
'201':
- description: order cancellation reason created
+ description: product created
content:
application/json:
example:
- id: ocr_gbHJdmfrXB
- name: A new reason
- active: true
+ id: prod_gbHJdmfrXB
+ name: New Product
+ slug: new-product
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on:
+ preorder_ships_at:
+ purchasable: false
+ preorder: false
+ in_stock: false
+ backorderable: false
+ available: false
+ description:
+ description_html:
+ default_variant_id: variant_gbHJdmfrXB
+ buy_box_variant_id: variant_gbHJdmfrXB
+ thumbnail_url:
+ tags: []
+ price:
+ original_price:
+ seller_id:
+ external_references: {}
+ status: draft
+ metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id:
+ schema:
+ "$ref": "#/components/schemas/Product"
'422':
description: validation error
content:
@@ -23101,36 +22966,133 @@ paths:
application/json:
schema:
type: object
- required:
- - name
properties:
name:
type: string
- example: Out of stock
- active:
- type: boolean
- example: true
- 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
+ example: Premium T-Shirt
+ 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
+ example:
+ - eco
+ - sale
+ 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
+ example: USD
+ amount:
+ type: string
+ example: '29.99'
+ compare_at_amount:
+ type: string
+ nullable: true
+ example: '39.99'
+ 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
+ example: size
+ value:
+ type: string
+ example: Small
+ prices:
+ type: array
+ description: Per-currency prices. Upserted by currency.
+ items:
+ type: object
+ required:
+ - currency
+ - amount
+ properties:
+ currency:
+ type: string
+ example: USD
+ amount:
+ type: string
+ example: '29.99'
+ compare_at_amount:
+ type: string
+ nullable: true
+ example: '39.99'
+ 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
+ example: 50
+ backorderable:
+ type: boolean
+ required:
+ - name
+ "/api/v3/admin/products/{id}":
get:
- summary: Get a order cancellation reason
+ summary: Get a product
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single order cancellation reason by prefixed ID.
+ Returns a single product by ID.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23142,10 +23104,12 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.orderCancellationReasons.get('ocr_UkLWZg9DAJ')
+ const product = await client.products.get('prod_86Rf07xd4z', {
+ expand: ['variants', 'option_types'],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /order_cancellation_reasons/{id}
+ source: spree api get /products/{id} -d '{"expand":["variants","option_types"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23158,41 +23122,99 @@ paths:
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: order cancellation reason found
+ description: product found
content:
application/json:
example:
- id: ocr_UkLWZg9DAJ
- name: Out of stock
- active: true
+ id: prod_UkLWZg9DAJ
+ name: Product 1102061
+ slug: product-1102061
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 1
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Illo error explicabo cupiditate consequatur. Et expedita
+ velit laborum iure. Harum sit eaque nam ipsam maiores.
+ description_html: Illo error explicabo cupiditate consequatur. Et
+ expedita velit laborum iure. Harum sit eaque nam ipsam maiores.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ currency: USD
+ amount: '19.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ original_price:
+ seller_id:
+ external_references: {}
+ status: active
+ metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id: taxcat_UkLWZg9DAJ
+ schema:
+ "$ref": "#/components/schemas/Product"
'404':
- description: order cancellation reason not found
+ description: product not found
content:
application/json:
example:
error:
code: record_not_found
- message: Order cancellation reason not found
+ message: Product not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a order cancellation reason
+ summary: Update a product
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Renames a order cancellation reason or retires it. Deactivating keeps it on the records
- that already carry it while removing it from the pickers.
-
+ Updates a product. Only provided fields are updated.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23204,12 +23226,14 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.orderCancellationReasons.update('ocr_UkLWZg9DAJ', {
- active: false,
+ const product = await client.products.update('prod_86Rf07xd4z', {
+ name: 'Updated Name',
+ status: 'active',
+ tags: ['eco', 'sale'],
})
- lang: bash
label: Spree CLI
- source: spree api patch /order_cancellation_reasons/{id} -d '{"active":false}'
+ source: spree api patch /products/{id} -d '{"name":"Updated Name","status":"active","tags":["eco","sale"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23222,18 +23246,89 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Product ID
+ schema:
+ type: string
responses:
'200':
- description: order cancellation reason updated
+ description: product updated
content:
application/json:
example:
- id: ocr_UkLWZg9DAJ
- name: Out of stock
- active: false
+ id: prod_UkLWZg9DAJ
+ name: Updated Name
+ slug: product-1125339
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 1
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Laborum nostrum nemo fugit temporibus consectetur omnis.
+ Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias
+ at perspiciatis laborum similique. Fugit adipisci iure porro architecto
+ odit. Alias enim quis rem reprehenderit temporibus. Hic quae rem
+ aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam
+ est tempore doloribus cumque inventore vero laborum minus. Reiciendis
+ autem quia eligendi possimus beatae enim. Impedit nemo quae odit
+ dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae.
+ Corporis ipsa alias tempora accusantium. Adipisci sapiente illum
+ id voluptatum aut illo tempora.
+ description_html: |-
+ Laborum nostrum nemo fugit temporibus consectetur omnis. Necessitatibus voluptas ut delectus aperiam incidunt tenetur. Alias at perspiciatis laborum similique. Fugit adipisci iure porro architecto odit.
+ Alias enim quis rem reprehenderit temporibus. Hic quae rem aspernatur tempore in. Praesentium assumenda sequi quis quasi. Laboriosam est tempore doloribus cumque inventore vero laborum minus. Reiciendis autem quia eligendi possimus beatae enim.
+ Impedit nemo quae odit dolor velit possimus commodi. Sequi ullam dolorum odio at quam vitae. Corporis ipsa alias tempora accusantium. Adipisci sapiente illum id voluptatum aut illo tempora.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ currency: USD
+ amount: '19.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ original_price:
+ seller_id:
+ external_references: {}
+ status: active
+ metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id: taxcat_UkLWZg9DAJ
+ schema:
+ "$ref": "#/components/schemas/Product"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
@@ -23242,22 +23337,127 @@ paths:
properties:
name:
type: string
- active:
- type: boolean
+ example: Premium T-Shirt
+ 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
+ example:
+ - eco
+ - sale
+ 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
+ example: USD
+ amount:
+ type: string
+ example: '29.99'
+ compare_at_amount:
+ type: string
+ nullable: true
+ example: '39.99'
+ 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
+ example: size
+ value:
+ type: string
+ example: Small
+ prices:
+ type: array
+ description: Per-currency prices. Upserted by currency.
+ items:
+ type: object
+ required:
+ - currency
+ - amount
+ properties:
+ currency:
+ type: string
+ example: USD
+ amount:
+ type: string
+ example: '29.99'
+ compare_at_amount:
+ type: string
+ nullable: true
+ example: '39.99'
+ 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
+ example: 50
+ backorderable:
+ type: boolean
delete:
- summary: Delete a order cancellation reason
+ summary: Delete a product
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Removes a order cancellation reason the store no longer uses. A reason already recorded
- on a document is refused — deactivate it instead, so the history it
- explains stays readable.
-
+ Soft-deletes a product.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23269,10 +23469,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orderCancellationReasons.delete('ocr_UkLWZg9DAJ')
+ await client.products.delete('prod_86Rf07xd4z')
- lang: bash
label: Spree CLI
- source: spree api delete /order_cancellation_reasons/{id}
+ source: spree api delete /products/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -23285,26 +23485,44 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Product ID
+ schema:
+ type: string
responses:
'204':
- description: order cancellation reason deleted
- "/api/v3/admin/refund_reasons":
- get:
- summary: List refund reasons
+ description: product deleted
+ '422':
+ description: deletion refused by a store rule
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: This product is under an active supplier contract.
+ details:
+ base:
+ - code: under_contract
+ message: This product is under an active supplier contract.
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/products/bulk_status_update":
+ post:
+ summary: Bulk-update product status
tags:
- - Reasons
+ - Products
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.
-
- The vocabulary is the merchant's own — seeded with a starting set and
- edited from the dashboard. Inactive rows stay for the records that
- already reference them, but are not offered on new ones.
+ Sets `status` on each product in `ids`. Reindexes the affected products
+ for search. Cross-store IDs are silently dropped. Returns counts.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23316,10 +23534,13 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: reasons } = await client.refundReasons.list()
+ const result = await client.products.bulkStatusUpdate({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ status: 'archived',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /refund_reasons
+ source: spree api post /products/bulk_status_update -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"status":"archived"}'
parameters:
- name: x-spree-api-key
in: header
@@ -23329,104 +23550,69 @@ paths:
- 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
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- **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
+ description: cross-store products silently dropped
content:
application/json:
example:
- data:
- - id: rr_UkLWZg9DAJ
- name: Goodwill gesture
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- '401':
- description: unauthorized
+ product_count: 0
+ status: archived
+ schema:
+ type: object
+ properties:
+ product_count:
+ type: integer
+ status:
+ type: string
+ '422':
+ description: invalid status
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: invalid_status
+ message: Invalid status
schema:
"$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - ids
+ - status
+ properties:
+ ids:
+ type: array
+ items:
+ type: string
+ example:
+ - prod_UkLWZg9DAJ
+ status:
+ type: string
+ enum:
+ - draft
+ - active
+ - archived
+ example: archived
+ "/api/v3/admin/products/bulk_add_to_categories":
post:
- summary: Create a refund reason
+ summary: Bulk-add products to categories
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Adds a refund reason to this store. Names are unique per store, ignoring case.
+ Attaches each product in `ids` to every category (category) in `category_ids`.
+ Categories from sibling stores are silently ignored.
- **Required scope:** `write_settings` (for API-key authentication).
+
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23438,12 +23624,13 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.refundReasons.create({
- name: 'Goodwill gesture',
+ const result = await client.products.bulkAddToCategories({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ category_ids: ['cat_AbC123XyZ'],
})
- lang: bash
label: Spree CLI
- source: spree api post /refund_reasons -d '{"name":"Goodwill gesture"}'
+ source: spree api post /products/bulk_add_to_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23453,71 +23640,52 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
- '201':
- description: refund reason created
- content:
- application/json:
- example:
- id: rr_gbHJdmfrXB
- name: A new reason
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- '422':
- description: validation error
+ '200':
+ description: products added to categories
content:
application/json:
example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
+ product_count: 1
+ category_count: 1
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
+ type: object
+ properties:
+ product_count:
+ type: integer
+ category_count:
+ type: integer
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
required:
- - name
+ - ids
+ - category_ids
properties:
- name:
- type: string
- example: Goodwill gesture
- active:
- type: boolean
- example: true
- 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
+ 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:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single refund reason by prefixed ID.
+ Detaches each product in `ids` from every category in `category_ids`.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23529,10 +23697,13 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.refundReasons.get('rr_UkLWZg9DAJ')
+ const result = await client.products.bulkRemoveFromCategories({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ category_ids: ['cat_AbC123XyZ'],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /refund_reasons/{id}
+ source: spree api post /products/bulk_remove_from_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23542,61 +23713,47 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: refund reason found
- content:
- application/json:
- example:
- id: rr_UkLWZg9DAJ
- name: Goodwill gesture
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- '404':
- description: refund reason not found
+ description: products removed from categories
content:
application/json:
example:
- error:
- code: record_not_found
- message: Refund reason not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a refund reason
+ product_count: 1
+ category_count: 1
+ 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:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Renames a refund reason or retires it. Deactivating keeps it on the records
- that already carry it while removing it from the pickers.
-
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Attaches each product in `ids` to every manual collection in `collection_ids`.
+ Automatic (rule-based) and sibling-store collections are silently ignored.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const reason = await client.refundReasons.update('rr_UkLWZg9DAJ', {
- active: false,
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /refund_reasons/{id} -d '{"active":false}'
+ **Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -23606,60 +23763,52 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: refund reason updated
+ description: products added to collections
content:
application/json:
example:
- id: rr_UkLWZg9DAJ
- name: Goodwill gesture
- active: false
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
+ product_count: 1
+ collection_count: 1
+ schema:
+ type: object
+ properties:
+ product_count:
+ type: integer
+ collection_count:
+ type: integer
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - ids
+ - collection_ids
properties:
- name:
- type: string
- active:
- type: boolean
- delete:
- summary: Delete a refund reason
+ 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:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Removes a refund reason the store no longer uses. A reason already recorded
- on a document is refused — deactivate it instead, so the history it
- explains stays readable.
-
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Detaches each product in `ids` from every collection in `collection_ids`.
- await client.refundReasons.delete('rr_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /refund_reasons/{id}
+ **Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -23669,29 +23818,48 @@ paths:
- 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
+ '200':
+ description: products removed from collections
+ content:
+ application/json:
+ example:
+ product_count: 1
+ collection_count: 1
+ 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:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Why a customer is sending items back. Shared by returns and exchanges.
-
- The vocabulary is the merchant's own — seeded with a starting set and
- edited from the dashboard. Inactive rows stay for the records that
- already reference them, but are not offered on new ones.
+ Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —
+ re-publishing on an existing channel is a no-op. Channels from sibling stores
+ are silently ignored.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23703,10 +23871,13 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: reasons } = await client.returnReasons.list()
+ const result = await client.products.bulkAddToChannels({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ channel_ids: ['channel_AbC123XyZ'],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /return_reasons
+ source: spree api post /products/bulk_add_to_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23716,104 +23887,52 @@ paths:
- 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
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- **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:
- example:
- data:
- - id: rar_UkLWZg9DAJ
- name: Damaged in transit
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- '401':
- description: unauthorized
+ description: products published on channels
content:
application/json:
example:
- error:
- code: authentication_required
- message: Authentication required
+ product_count: 1
+ channel_count: 1
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ 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: Create a return reason
+ summary: Bulk-remove products from channels
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Adds a return reason to this store. Names are unique per store, ignoring case.
+ Unpublishes each product in `ids` from every channel in `channel_ids`.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23825,12 +23944,13 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.returnReasons.create({
- name: 'Damaged in transit',
+ const result = await client.products.bulkRemoveFromChannels({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ channel_ids: ['channel_AbC123XyZ'],
})
- lang: bash
label: Spree CLI
- source: spree api post /return_reasons -d '{"name":"Damaged in transit"}'
+ source: spree api post /products/bulk_remove_from_channels -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"channel_ids":["channel_AbC123XyZ"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23840,71 +23960,55 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
- '201':
- description: return reason created
- content:
- application/json:
- example:
- id: rar_gbHJdmfrXB
- name: A new reason
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- '422':
- description: validation error
+ '200':
+ description: products unpublished from channels
content:
application/json:
example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
+ product_count: 1
+ channel_count: 1
+ removed: 1
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ type: object
+ properties:
+ product_count:
+ type: integer
+ channel_count:
+ type: integer
+ removed:
+ type: integer
requestBody:
content:
application/json:
schema:
type: object
required:
- - name
+ - ids
+ - channel_ids
properties:
- name:
- type: string
- example: Damaged in transit
- active:
- type: boolean
- example: true
- 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
+ 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:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single return reason by prefixed ID.
+ Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23916,10 +24020,13 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.returnReasons.get('rar_UkLWZg9DAJ')
+ const result = await client.products.bulkAddTags({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ tags: ['summer', 'sale'],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /return_reasons/{id}
+ source: spree api post /products/bulk_add_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer","sale"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23929,44 +24036,55 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: return reason found
- content:
- application/json:
- example:
- id: rar_UkLWZg9DAJ
- name: Damaged in transit
- active: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
- '404':
- description: return reason not found
+ description: tags added
content:
application/json:
example:
- error:
- code: record_not_found
- message: Return reason not found
+ product_count: 1
+ tag_count: 2
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a return reason
+ 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
+ example:
+ - summer
+ - sale
+ "/api/v3/admin/products/bulk_remove_tags":
+ post:
+ summary: Bulk-remove tags from products
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Renames a return reason or retires it. Deactivating keeps it on the records
- that already carry it while removing it from the pickers.
-
+ Removes each tag in `tags` from every product in `ids`.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23978,12 +24096,13 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.returnReasons.update('rar_UkLWZg9DAJ', {
- active: false,
+ const result = await client.products.bulkRemoveTags({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ tags: ['summer'],
})
- lang: bash
label: Spree CLI
- source: spree api patch /return_reasons/{id} -d '{"active":false}'
+ source: spree api post /products/bulk_remove_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -23993,45 +24112,45 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: return reason updated
+ description: tags removed
content:
application/json:
example:
- id: rar_UkLWZg9DAJ
- name: Damaged in transit
- active: false
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- can_be_deleted: true
+ product_count: 1
+ tag_count: 1
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - ids
+ - tags
properties:
- name:
- type: string
- active:
- type: boolean
+ ids:
+ type: array
+ items:
+ type: string
+ tags:
+ type: array
+ items:
+ type: string
+ "/api/v3/admin/products/bulk_destroy":
delete:
- summary: Delete a return reason
+ summary: Bulk-delete products
tags:
- - Reasons
+ - Products
security:
- api_key: []
bearer_auth: []
description: |-
- Removes a return reason the store no longer uses. A reason already recorded
- on a document is refused — deactivate it instead, so the history it
- explains stays readable.
-
+ Soft-deletes each product in `ids`. Returns the count actually destroyed.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24043,10 +24162,12 @@ paths:
secretKey: 'sk_xxx',
})
- await client.returnReasons.delete('rar_UkLWZg9DAJ')
+ const result = await client.products.bulkDestroy({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ })
- lang: bash
label: Spree CLI
- source: spree api delete /return_reasons/{id}
+ source: spree api delete /products/bulk_destroy -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -24056,45 +24177,44 @@ paths:
- 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
+ '200':
+ description: products deleted
+ content:
+ application/json:
+ example:
+ product_count: 1
+ 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: List coupon codes for a promotion
+ summary: Translation coverage for a resource type
tags:
- - Promotions
+ - Products
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.
-
- **Required scope:** `read_promotions` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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.
- const { data: coupons } = await client.promotions.couponCodes.list('promo_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /promotions/{promotion_id}/coupon_codes
+ **Required scope:** `read_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -24106,97 +24226,89 @@ paths:
required: true
schema:
type: string
- - name: q
+ - 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
- 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
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `promotion_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `state` | One of `unused`, `used` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[promotion_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `promotion_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
-
- </Accordion>
-
- **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
+ 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: coupon codes found
+ description: coverage found
content:
application/json:
example:
data:
- - id: coupon_UkLWZg9DAJ
- code: AAA111
- state: unused
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- promotion_id: promo_UkLWZg9DAJ
- order_id:
- - id: coupon_gbHJdmfrXB
- code: BBB222
- state: unused
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- promotion_id: promo_UkLWZg9DAJ
- order_id:
+ resource_type: product
+ default_locale: en
+ locales:
+ - de
+ field_count: 5
+ search_field: name_cont
+ coverage:
+ - locale: de
+ translated: 0
+ total: 1
+ coverage: 0.0
+ records:
+ - id: prod_UkLWZg9DAJ
+ label: Espresso Machine
+ locales:
+ de: 2
meta:
page: 1
limit: 25
- count: 2
+ count: 1
pages: 1
from: 1
- to: 2
- in: 2
+ to: 1
+ in: 1
previous:
next:
- "/api/v3/admin/promotions/{promotion_id}/promotion_actions":
- parameters:
- - name: promotion_id
- in: path
- required: true
- schema:
- type: string
+ '404':
+ description: resource type is not translatable
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: record not found
+ "/api/v3/admin/policies":
get:
- summary: List actions for a promotion
+ summary: List policies
tags:
- - Promotions
+ - Policies
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_promotions` (for API-key authentication)."
+ description: |-
+ Returns the store's policy documents — terms of service, privacy
+ policy, returns policy, shipping policy, and any others the merchant
+ has written. Every store is created with the four standard policies,
+ named but empty.
+
+ A marketplace seller's own policies are managed by the seller and are
+ not listed here.
+
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24208,10 +24320,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: actions } = await client.promotions.actions.list('promo_UkLWZg9DAJ')
+ const { data: policies } = await client.policies.list()
- lang: bash
label: Spree CLI
- source: spree api get /promotions/{promotion_id}/promotion_actions
+ source: spree api get /policies
parameters:
- name: x-spree-api-key
in: header
@@ -24221,8 +24333,27 @@ paths:
- 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
@@ -24233,63 +24364,128 @@ paths:
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
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `owner_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `owner_type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `id`, `name`, `owner_id`, `owner_type`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: PromotionAction
+ table: Policy
sortable:
- created_at
- id
- - position
+ - name
+ - owner_id
+ - owner_type
- updated_at
responses:
'200':
- description: actions found
+ description: policies listed
content:
application/json:
example:
data:
- - id: pact_UkLWZg9DAJ
+ - id: pol_gbHJdmfrXB
+ name: Privacy Policy
+ slug: privacy-policy
+ body: ''
+ body_html: ''
+ updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
+ - id: pol_uw2YK1rnl0
+ name: Restocking Policy
+ slug: restocking-policy
+ body: Return anything unopened within 30 days.
+ body_html: "<p>Return anything unopened within 30 days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
- type: free_shipping
- promotion_id: promo_UkLWZg9DAJ
- preferences: {}
- calculator:
- line_items:
+ created_at: '2026-01-15T12:00:00.000Z'
+ - id: pol_EfhxLZ9ck8
+ name: Returns Policy
+ slug: returns-policy
+ body: ''
+ body_html: ''
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ - id: pol_VqXmZF31wY
+ name: Shipping Policy
+ slug: shipping-policy
+ body: ''
+ body_html: ''
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ - id: pol_UkLWZg9DAJ
+ name: Terms of Service
+ slug: terms-of-service
+ body: ''
+ body_html: ''
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
meta:
page: 1
limit: 25
- count: 1
+ count: 5
pages: 1
from: 1
- to: 1
- in: 1
+ to: 5
+ in: 5
previous:
next:
+ 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:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create an action on a promotion
+ summary: Create a policy
tags:
- - Promotions
+ - Policies
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`).
+ Creates a policy. `body` accepts HTML and is sanitized before it is
+ stored; the stored markup is returned as `body_html`, and `body` reads
+ back as plain text.
- **Required scope:** `write_promotions` (for API-key authentication).
+ The slug is derived from the name when one is not given, and is what
+ the storefront addresses the policy by.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24301,12 +24497,14 @@ paths:
secretKey: 'sk_xxx',
})
- const action = await client.promotions.actions.create('promo_UkLWZg9DAJ', {
- type: 'free_shipping',
+ const policy = await client.policies.create({
+ name: 'Wholesale Policy',
+ body: '<p>Trade orders ship within five working days.</p>',
})
- lang: bash
label: Spree CLI
- source: spree api post /promotions/{promotion_id}/promotion_actions -d '{"type":"free_shipping"}'
+ source: spree api post /policies -d '{"name":"Wholesale Policy","body":"<p>Trade
+ orders ship within five working days.</p>"}'
parameters:
- name: x-spree-api-key
in: header
@@ -24316,64 +24514,75 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: action created
+ description: policy created
content:
application/json:
example:
- id: pact_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
+ id: pol_OIJLhNcSbf
+ name: Wholesale Policy
+ slug: wholesale-policy
+ body: Trade orders ship within five working days.
+ body_html: "<p>Trade orders ship within five working days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
- type: free_shipping
- promotion_id: promo_UkLWZg9DAJ
- preferences: {}
- calculator:
- line_items:
+ created_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Policy"
'422':
- description: unknown action type
+ description: validation error
content:
application/json:
example:
error:
- code: unknown_promotion_action_type
- message: Unknown type
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- type:
+ name:
type: string
- example: free_shipping
- preferences:
- type: object
- additionalProperties: true
+ example: Wholesale Policy
+ slug:
+ type: string
+ example: wholesale-policy
+ body:
+ type: string
+ example: "<p>Trade orders ship within five working days.</p>"
required:
- - type
- "/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":
+ - name
+ "/api/v3/admin/policies/{id}":
parameters:
- - name: promotion_id
- in: path
- required: true
- schema:
- type: string
- name: id
in: path
required: true
+ description: Policy prefixed ID or slug
schema:
type: string
- delete:
- summary: Delete an action from a promotion
+ get:
+ summary: Get a policy
tags:
- - Promotions
+ - Policies
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ description: |-
+ Returns a single policy, addressed by prefixed ID or by slug.
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24385,10 +24594,11 @@ paths:
secretKey: 'sk_xxx',
})
- await client.promotions.actions.delete('promo_UkLWZg9DAJ', 'promoact_k5nR8xLq')
+ // Addressable by slug as well as prefixed id.
+ const policy = await client.policies.get('returns-policy')
- lang: bash
label: Spree CLI
- source: spree api delete /promotions/{promotion_id}/promotion_actions/{id}
+ source: spree api get /policies/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -24398,26 +24608,45 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
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
+ '200':
+ description: policy found
+ content:
+ application/json:
+ example:
+ id: pol_uw2YK1rnl0
+ name: Restocking Policy
+ slug: restocking-policy
+ body: Return anything unopened within 30 days.
+ body_html: "<p>Return anything unopened within 30 days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Policy"
+ '404':
+ description: policy not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Policy not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a policy
tags:
- - Promotions
+ - Policies
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_promotions` (for API-key authentication)."
+ description: |-
+ Updates a policy. `body` accepts HTML and is sanitized before it is stored.
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24429,10 +24658,13 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: rules } = await client.promotions.rules.list('promo_UkLWZg9DAJ')
+ const policy = await client.policies.update('returns-policy', {
+ body: '<p>Return anything unopened within 60 days.</p>',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /promotions/{promotion_id}/promotion_rules
+ source: spree api patch /policies/{id} -d '{"body":"<p>Return anything unopened
+ within 60 days.</p>"}'
parameters:
- name: x-spree-api-key
in: header
@@ -24442,55 +24674,187 @@ paths:
- 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
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
- x-spree-filters:
- table: PromotionRule
- sortable:
- - created_at
- - id
+ responses:
+ '200':
+ description: policy updated
+ content:
+ application/json:
+ example:
+ id: pol_uw2YK1rnl0
+ name: Restocking Policy
+ slug: restocking-policy
+ body: Return anything unopened within 60 days.
+ body_html: "<p>Return anything unopened within 60 days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ 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
+ deleted like any other — they are conventions, not fixtures.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.policies.delete('wholesale-policy')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /policies/{id}
+ parameters:
+ - name: x-spree-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.
+
+ The vocabulary is the merchant's own — seeded with a starting set and
+ edited from the dashboard. Inactive rows stay for the records that
+ already reference them, but are not offered on new ones.
+
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: reasons } = await client.claimReasons.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /claim_reasons
+ parameters:
+ - name: x-spree-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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: rules found
+ description: claim reasons found
content:
application/json:
example:
data:
- - id: prorule_UkLWZg9DAJ
+ - id: clr_UkLWZg9DAJ
+ name: Arrived damaged
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- type: currency
- promotion_id: promo_UkLWZg9DAJ
- preferences:
- currency: USD
- product_ids:
- category_ids:
- customer_ids:
- option_value_ids:
+ can_be_deleted: true
meta:
page: 1
limit: 25
@@ -24501,17 +24865,27 @@ paths:
in: 1
previous:
next:
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a rule on a promotion
+ summary: Create a claim reason
tags:
- - Promotions
+ - Reasons
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`).
+ Adds a claim reason to this store. Names are unique per store, ignoring case.
- **Required scope:** `write_promotions` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24523,13 +24897,12 @@ paths:
secretKey: 'sk_xxx',
})
- const rule = await client.promotions.rules.create('promo_UkLWZg9DAJ', {
- type: 'currency',
- preferences: { currency: 'EUR' },
+ const reason = await client.claimReasons.create({
+ name: 'Arrived damaged',
})
- lang: bash
label: Spree CLI
- source: spree api post /promotions/{promotion_id}/promotion_rules -d '{"type":"currency","preferences":{"currency":"EUR"}}'
+ source: spree api post /claim_reasons -d '{"name":"Arrived damaged"}'
parameters:
- name: x-spree-api-key
in: header
@@ -24539,67 +24912,133 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: rule created with preferences
+ description: claim reason created
content:
application/json:
example:
- id: prorule_UkLWZg9DAJ
+ id: clr_gbHJdmfrXB
+ name: A new reason
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- type: currency
- promotion_id: promo_UkLWZg9DAJ
- preferences:
- currency: EUR
- product_ids:
- category_ids:
- customer_ids:
- option_value_ids:
+ can_be_deleted: true
'422':
- description: unknown rule type
+ description: validation error
content:
application/json:
example:
error:
- code: unknown_promotion_rule_type
- message: Unknown type
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - name
properties:
- type:
+ name:
type: string
- example: currency
- preferences:
- type: object
- additionalProperties: true
- required:
- - type
- "/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":
+ example: Arrived damaged
+ active:
+ type: boolean
+ example: true
+ description: Inactive reasons are hidden from the pickers on new
+ records.
+ "/api/v3/admin/claim_reasons/{id}":
parameters:
- - name: promotion_id
- in: path
- required: true
- schema:
- type: string
- 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.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const reason = await client.claimReasons.get('clr_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /claim_reasons/{id}
+ parameters:
+ - name: x-spree-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:
+ example:
+ id: clr_UkLWZg9DAJ
+ name: Arrived damaged
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ can_be_deleted: true
+ '404':
+ description: claim reason not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Claim reason not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a rule's preferences
+ summary: Update a claim reason
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ description: |-
+ Renames a claim reason or retires it. Deactivating keeps it on the records
+ that already carry it while removing it from the pickers.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24611,13 +25050,12 @@ paths:
secretKey: 'sk_xxx',
})
- const rule = await client.promotions.rules.update('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq', {
- preferences: { currency: 'USD' },
+ const reason = await client.claimReasons.update('clr_UkLWZg9DAJ', {
+ active: false,
})
- lang: bash
label: Spree CLI
- source: spree api patch /promotions/{promotion_id}/promotion_rules/{id} -d
- '{"preferences":{"currency":"USD"}}'
+ source: spree api patch /claim_reasons/{id} -d '{"active":false}'
parameters:
- name: x-spree-api-key
in: header
@@ -24627,42 +25065,45 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: rule updated
+ description: claim reason updated
content:
application/json:
example:
- id: prorule_UkLWZg9DAJ
+ id: clr_UkLWZg9DAJ
+ name: Arrived damaged
+ active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- type: currency
- promotion_id: promo_UkLWZg9DAJ
- preferences:
- currency: GBP
- product_ids:
- category_ids:
- customer_ids:
- option_value_ids:
+ can_be_deleted: true
requestBody:
content:
application/json:
schema:
type: object
properties:
- preferences:
- type: object
- additionalProperties: true
+ name:
+ type: string
+ active:
+ type: boolean
delete:
- summary: Delete a rule from a promotion
+ summary: Delete a claim reason
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ description: |-
+ Removes a claim reason the store no longer uses. A reason already recorded
+ on a document is refused — deactivate it instead, so the history it
+ explains stays readable.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24674,10 +25115,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.promotions.rules.delete('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq')
+ await client.claimReasons.delete('clr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /promotions/{promotion_id}/promotion_rules/{id}
+ source: spree api delete /claim_reasons/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -24687,23 +25128,29 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'204':
- description: rule deleted
- "/api/v3/admin/promotions":
+ description: claim reason deleted
+ "/api/v3/admin/order_cancellation_reasons":
get:
- summary: List promotions
+ summary: List order cancellation reasons
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the store's promotions, including manual coupon and automatic promotions.
+ Why an order was called off before it shipped. Staff pick one when canceling.
- **Required scope:** `read_promotions` (for API-key authentication).
+ The vocabulary is the merchant's own — seeded with a starting set and
+ edited from the dashboard. Inactive rows stay for the records that
+ already reference them, but are not offered on new ones.
+
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24715,10 +25162,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: promotions } = await client.promotions.list()
+ const { data: reasons } = await client.orderCancellationReasons.list()
- lang: bash
label: Spree CLI
- source: spree api get /promotions
+ source: spree api get /order_cancellation_reasons
parameters:
- name: x-spree-api-key
in: header
@@ -24728,14 +25175,21 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: q[search]
+ - 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: string
- description: Matches any of name and code (partial, case-insensitive).
+ type: integer
- name: q
in: query
required: false
@@ -24746,6 +25200,12 @@ paths:
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
@@ -24754,67 +25214,34 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
- | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `kind` | One of `coupon_code`, `automatic` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `path` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `promotion_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[coupon_codes_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |
-
- </Accordion>
-
- **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.
+ **Sort by:** `active`, `created_at`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: Promotion
+ table: OrderCancellationReason
sortable:
- - code
+ - active
- created_at
- - expires_at
- id
- - kind
- name
- - path
- - promotion_category_id
- - starts_at
- updated_at
responses:
'200':
- description: promotions found
+ description: order cancellation reasons found
content:
application/json:
example:
data:
- - id: promo_UkLWZg9DAJ
- name: Summer Sale
- description:
- code: summer
- starts_at: '2026-01-15T11:00:00.000Z'
- expires_at:
- usage_limit:
- match_policy: all
- path:
- kind: coupon_code
- multi_codes: false
- number_of_codes:
- code_prefix:
- promotion_category_id:
- metadata: {}
+ - id: ocr_UkLWZg9DAJ
+ name: Out of stock
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- action_ids: []
- rule_ids: []
+ can_be_deleted: true
meta:
page: 1
limit: 25
@@ -24825,23 +25252,27 @@ paths:
in: 1
previous:
next:
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a promotion
+ summary: Create a order cancellation reason
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new promotion. `code` is required for single-code coupon promotions;
- pass `multi_codes: true` with `number_of_codes` to auto-generate a batch.
-
- Rules and actions can be created in the same request by passing arrays of
- `{ type, preferences, ... }` rows. The server reconciles to the desired set:
- new rows are built, existing rows (by `id`) are updated, omitted rows are removed.
-
+ Adds a order cancellation reason to this store. Names are unique per store, ignoring case.
- **Required scope:** `write_promotions` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -24853,51 +25284,12 @@ paths:
secretKey: 'sk_xxx',
})
- // Single coupon code, no rules/actions
- const promotion = await client.promotions.create({
- name: 'Black Friday',
- code: 'BLACKFRIDAY',
- starts_at: '2026-11-29T00:00:00Z',
- expires_at: '2026-12-01T00:00:00Z',
- })
-
- // One-shot: promotion + rules + actions in a single request
- const blackFriday = await client.promotions.create({
- name: 'Black Friday',
- code: 'BLACKFRIDAY',
- kind: 'coupon_code',
- starts_at: '2026-11-29T00:00:00Z',
- expires_at: '2026-12-01T00:00:00Z',
- match_policy: 'all',
- rules: [
- {
- type: 'currency',
- preferences: { currency: 'USD' },
- },
- {
- type: 'item_total',
- preferences: { amount_min: '100.00', operator_min: 'gte' },
- },
- {
- type: 'product',
- preferences: { match_policy: 'any' },
- product_ids: ['prod_abc123', 'prod_def456'],
- },
- ],
- actions: [
- {
- type: 'create_item_adjustments',
- calculator: {
- type: 'percent_on_line_item',
- preferences: { percent: '25' },
- },
- },
- { type: 'free_shipping' },
- ],
+ const reason = await client.orderCancellationReasons.create({
+ name: 'Out of stock',
})
- lang: bash
label: Spree CLI
- source: spree api post /promotions -d '{"name":"Black Friday","code":"BLACKFRIDAY","starts_at":"2026-11-29T00:00:00Z","expires_at":"2026-12-01T00:00:00Z"}'
+ source: spree api post /order_cancellation_reasons -d '{"name":"Out of stock"}'
parameters:
- name: x-spree-api-key
in: header
@@ -24907,159 +25299,71 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: promotion created with rules and actions
+ description: order cancellation reason created
content:
application/json:
example:
- id: promo_gbHJdmfrXB
- name: Black Friday
- description:
- code: blackfriday-os
- starts_at: '2026-01-15T12:00:00.000Z'
- expires_at:
- usage_limit:
- match_policy: all
- path:
- kind: coupon_code
- multi_codes: false
- number_of_codes:
- code_prefix:
- promotion_category_id:
- metadata: {}
+ id: ocr_gbHJdmfrXB
+ name: A new reason
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- action_ids:
- - pact_UkLWZg9DAJ
- - pact_gbHJdmfrXB
- rule_ids:
- - prorule_UkLWZg9DAJ
- - prorule_gbHJdmfrXB
- - prorule_EfhxLZ9ck8
+ can_be_deleted: true
'422':
- description: invalid params
+ description: validation error
content:
application/json:
example:
error:
code: validation_error
- message: Name can't be blank and Code can't be blank
+ message: Name can't be blank
details:
name:
- code: blank
message: can't be blank
specific: false
- code:
- - code: blank
- message: can't be blank
- specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - name
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:
+ example: Out of stock
+ active:
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
- example: currency
- 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
- example: free_shipping
- preferences:
- type: object
- additionalProperties: true
- calculator:
- type: object
- properties:
- type:
- type: string
- example: flat_percent_item_total
- preferences:
- type: object
- additionalProperties: true
- required:
- - type
- required:
- - name
- "/api/v3/admin/promotions/{id}":
+ example: true
+ 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: Show a promotion
+ summary: Get a order cancellation reason
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_promotions` (for API-key authentication)."
+ description: |-
+ Returns a single order cancellation reason by prefixed ID.
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25071,10 +25375,10 @@ paths:
secretKey: 'sk_xxx',
})
- const promotion = await client.promotions.get('promo_UkLWZg9DAJ')
+ const reason = await client.orderCancellationReasons.get('ocr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /promotions/{id}
+ source: spree api get /order_cancellation_reasons/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -25084,53 +25388,44 @@ paths:
- name: Authorization
in: header
required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: promotion found
+ description: order cancellation reason found
content:
application/json:
example:
- id: promo_UkLWZg9DAJ
- name: Summer Sale
- description:
- code: summer
- starts_at: '2026-01-15T11:00:00.000Z'
- expires_at:
- usage_limit:
- match_policy: all
- path:
- kind: coupon_code
- multi_codes: false
- number_of_codes:
- code_prefix:
- promotion_category_id:
- metadata: {}
+ id: ocr_UkLWZg9DAJ
+ name: Out of stock
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- action_ids: []
- rule_ids: []
+ can_be_deleted: true
+ '404':
+ description: order cancellation reason not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Order cancellation reason not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a promotion
+ summary: Update a order cancellation reason
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a promotion. The `rules` and `actions` arrays are treated as
- a *desired set* — rows with `id` update in place, rows without `id` are
- built fresh, and any existing row not present in the array is destroyed.
- Pass `rules: []` or `actions: []` to clear them.
+ Renames a order cancellation reason or retires it. Deactivating keeps it on the records
+ that already carry it while removing it from the pickers.
- **Required scope:** `write_promotions` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25142,48 +25437,12 @@ paths:
secretKey: 'sk_xxx',
})
- // Basic field update
- await client.promotions.update(promotionId, {
- description: 'Updated description',
- })
-
- // One-shot: rewrite rules + actions in a single request
- await client.promotions.update(promotionId, {
- name: 'Holiday Sale',
- rules: [
- // Update an existing rule by id — `preferences` overwrite the prior set
- {
- id: 'prorule_existing',
- type: 'currency',
- preferences: { currency: 'EUR' },
- },
- // Add a new rule
- {
- type: 'item_total',
- preferences: { amount_min: '50.00', operator_min: 'gte' },
- },
- ],
- actions: [
- // Swap calculator type on an existing action
- {
- id: 'proaction_existing',
- type: 'create_item_adjustments',
- calculator: {
- type: 'percent_on_line_item',
- preferences: { percent: '15' },
- },
- },
- ],
- })
-
- // Remove all rules/actions
- await client.promotions.update(promotionId, {
- rules: [],
- actions: [],
+ const reason = await client.orderCancellationReasons.update('ocr_UkLWZg9DAJ', {
+ active: false,
})
- lang: bash
label: Spree CLI
- source: spree api patch /promotions/{id} -d '{"description":"Updated description"}'
+ source: spree api patch /order_cancellation_reasons/{id} -d '{"active":false}'
parameters:
- name: x-spree-api-key
in: header
@@ -25193,38 +25452,21 @@ paths:
- name: Authorization
in: header
required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: rules and actions cleared with empty arrays
+ description: order cancellation reason updated
content:
application/json:
example:
- id: promo_UkLWZg9DAJ
- name: Summer Sale
- description:
- code: summer
- starts_at: '2026-01-15T11:00:00.000Z'
- expires_at:
- usage_limit:
- match_policy: all
- path:
- kind: coupon_code
- multi_codes: false
- number_of_codes:
- code_prefix:
- promotion_category_id:
- metadata: {}
+ id: ocr_UkLWZg9DAJ
+ name: Out of stock
+ active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- action_ids: []
- rule_ids: []
+ can_be_deleted: true
requestBody:
content:
application/json:
@@ -25233,99 +25475,22 @@ paths:
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
- example: currency
- 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
- example: free_shipping
- preferences:
- type: object
- additionalProperties: true
- calculator:
- type: object
- properties:
- type:
- type: string
- example: flat_percent_item_total
- preferences:
- type: object
- additionalProperties: true
- required:
- - type
+ active:
+ type: boolean
delete:
- summary: Delete a promotion
+ summary: Delete a order cancellation reason
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ description: |-
+ Removes a order cancellation reason the store no longer uses. A reason already recorded
+ on a document is refused — deactivate it instead, so the history it
+ explains stays readable.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25337,10 +25502,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.promotions.delete('promo_UkLWZg9DAJ')
+ await client.orderCancellationReasons.delete('ocr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /promotions/{id}
+ source: spree api delete /order_cancellation_reasons/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -25350,28 +25515,29 @@ paths:
- name: Authorization
in: header
required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'204':
- description: promotion deleted
- "/api/v3/admin/promotion_actions/types":
+ description: order cancellation reason deleted
+ "/api/v3/admin/refund_reasons":
get:
- summary: List available promotion action types
+ summary: List refund reasons
tags:
- - Promotions
+ - Reasons
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.
+ Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.
- **Required scope:** `read_promotions` (for API-key authentication).
+ The vocabulary is the merchant's own — seeded with a starting set and
+ edited from the dashboard. Inactive rows stay for the records that
+ already reference them, but are not offered on new ones.
+
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25383,10 +25549,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: actionTypes } = await client.promotionActions.types()
+ const { data: reasons } = await client.refundReasons.list()
- lang: bash
label: Spree CLI
- source: spree api get /promotion_actions/types
+ source: spree api get /refund_reasons
parameters:
- name: x-spree-api-key
in: header
@@ -25396,56 +25562,104 @@ paths:
- 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: action types found
+ description: refund reasons found
content:
application/json:
example:
data:
- - type: create_line_items
- label: Create line items
- description: Adds the specified quantity of a variant to the cart
- free of charge
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: create_item_adjustments
- label: Create per-line-item adjustment
- description: Creates a promotion credit adjustment on a line item
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: create_adjustment
- label: Create whole-order adjustment
- description: Creates a promotion credit adjustment on the order
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: free_shipping
- label: Free shipping
- description: Makes all shipments for the order free
- schema:
- type: object
- properties: {}
- additionalProperties: false
- "/api/v3/admin/promotion_rules/types":
- get:
- summary: List available promotion rule types
+ - id: rr_UkLWZg9DAJ
+ name: Goodwill gesture
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ can_be_deleted: true
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ post:
+ summary: Create a refund reason
tags:
- - Promotions
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the registered Spree::PromotionRule subclasses with their preference schemas.
+ Adds a refund reason to this store. Names are unique per store, ignoring case.
- **Required scope:** `read_promotions` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25457,10 +25671,12 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: ruleTypes } = await client.promotionRules.types()
+ const reason = await client.refundReasons.create({
+ name: 'Goodwill gesture',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /promotion_rules/types
+ source: spree api post /refund_reasons -d '{"name":"Goodwill gesture"}'
parameters:
- name: x-spree-api-key
in: header
@@ -25470,209 +25686,71 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
- '200':
- description: rule types found
+ '201':
+ description: refund reason created
content:
application/json:
example:
- data:
- - type: category
- label: Categories
- description: Order includes products in specified categories
- schema:
- type: object
- properties:
- match_policy:
- type: string
- enum:
- - any
- - all
- default: any
- additionalProperties: false
- - type: channel
- label: Channel(s)
- description: Limit to orders placed through specified channel(s)
- schema:
- 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
- - type: country
- label: Country
- description: Limit to orders with shipping address in a specific
- country
- schema:
- type: object
- properties:
- country_codes:
- type: array
- items:
- type: string
- format: iso-country
- pattern: "^[A-Z]{2}$"
- default: []
- country_id:
- type:
- - integer
- - 'null'
- country_code:
- type:
- - string
- - 'null'
- format: iso-country
- pattern: "^[A-Z]{2}$"
- additionalProperties: false
- - type: currency
- label: Currency
- description: Limit to orders in a specific currency
- schema:
- type: object
- properties:
- currency:
- type:
- - string
- - 'null'
- format: currency
- pattern: "^[A-Z]{3}$"
- additionalProperties: false
- - type: customer_group
- label: Customer Group(s)
- description: Available only to customers in specified customer group(s)
- schema:
- 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
- - type: customer
- label: Customers
- description: Available only to the specified customers
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: first_order
- label: First order
- description: Must be the customer's first order
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: item_total
- label: Item total
- description: Order total meets these criteria
- schema:
- type: object
- properties:
- amount_min:
- type: string
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: '100'
- operator_min:
- type: string
- default: ">"
- amount_max:
- type:
- - string
- - 'null'
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- operator_max:
- type: string
- default: "<"
- additionalProperties: false
- - type: market
- label: Market(s)
- description: Limit to orders placed in specified market(s)
- schema:
- 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
- - type: one_use_per_user
- label: One Use Per User
- description: Only One Use Per User
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: customer_logged_in
- label: Only logged in customers
- description: Available only to logged in customers
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: option_value
- label: Option Value(s)
- description: Order includes products with matching option value(s)
- schema:
- 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
- - type: product
- label: Product(s)
- description: Order includes specified product(s)
- schema:
- type: object
- properties:
- match_policy:
- type: string
- enum:
- - any
- - all
- - none
- default: any
- additionalProperties: false
- "/api/v3/admin/orders/{order_id}/refunds":
+ id: rr_gbHJdmfrXB
+ name: A new reason
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ can_be_deleted: true
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ example: Goodwill gesture
+ active:
+ type: boolean
+ example: true
+ 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: List refunds
+ summary: Get a refund reason
tags:
- - Refunds
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Returns all refunds for an order.
+ Returns a single refund reason by prefixed ID.
- **Required scope:** `read_refunds` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25684,10 +25762,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: refunds } = await client.orders.refunds.list('or_UkLWZg9DAJ')
+ const reason = await client.refundReasons.get('rr_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /orders/{order_id}/refunds
+ source: spree api get /refund_reasons/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -25700,83 +25778,41 @@ paths:
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
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- **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
+ description: refund reason found
content:
application/json:
example:
- data: []
- meta:
- page: 1
- limit: 25
- count: 0
- pages: 1
- from: 0
- to: 0
- in: 0
- previous:
- next:
- post:
- summary: Create a refund
+ id: rr_UkLWZg9DAJ
+ name: Goodwill gesture
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ can_be_deleted: true
+ '404':
+ description: refund reason not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Refund reason not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a refund reason
tags:
- - Refunds
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.
+ Renames a refund reason or retires it. Deactivating keeps it on the records
+ that already carry it while removing it from the pickers.
- **Required scope:** `write_refunds` (for API-key authentication).
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25788,14 +25824,12 @@ paths:
secretKey: 'sk_xxx',
})
- const refund = await client.orders.refunds.create('or_UkLWZg9DAJ', {
- payment_id: 'pay_UkLWZg9DAJ',
- amount: '5.00',
- refund_reason_id: 'rr_UkLWZg9DAJ',
+ const reason = await client.refundReasons.update('rr_UkLWZg9DAJ', {
+ active: false,
})
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/refunds -d '{"payment_id":"pay_UkLWZg9DAJ","amount":"5.00","refund_reason_id":"rr_UkLWZg9DAJ"}'
+ source: spree api patch /refund_reasons/{id} -d '{"active":false}'
parameters:
- name: x-spree-api-key
in: header
@@ -25808,61 +25842,57 @@ paths:
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
+ '200':
+ description: refund reason updated
content:
application/json:
example:
- id: re_UkLWZg9DAJ
- transaction_id: BGS-c5ae59a82a25
- amount: '5.00'
- payment_id: py_UkLWZg9DAJ
- refund_reason_id: rr_UkLWZg9DAJ
- originator_id:
- originator_type:
- metadata: {}
+ id: rr_UkLWZg9DAJ
+ name: Goodwill gesture
+ active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- tax_amount: '0.00'
- refunder_id: adm_UkLWZg9DAJ
- refunder_type: admin_user
+ can_be_deleted: true
requestBody:
content:
application/json:
schema:
type: object
- required:
- - payment_id
- - amount
properties:
- payment_id:
- type: string
- description: Payment ID
- amount:
- type: string
- example: '10.00'
- refund_reason_id:
+ name:
type: string
- description: Refund reason ID
- "/api/v3/admin/locales":
- get:
- summary: List supported locales
+ active:
+ type: boolean
+ delete:
+ summary: Delete a refund reason
tags:
- - Settings
+ - Reasons
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.
+ Removes a refund reason the store no longer uses. A reason already recorded
+ on a document is refused — deactivate it instead, so the history it
+ explains stays readable.
- **Required scope:** `read_settings` (for API-key authentication).
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.refundReasons.delete('rr_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /refund_reasons/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -25872,37 +25902,27 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
- '200':
- description: locales found
- content:
- application/json:
- example:
- data:
- - code: de
- name: Deutsch
- default: false
- rtl: false
- - code: en
- name: English
- default: true
- rtl: false
- - code: fr
- name: Français
- default: false
- rtl: false
- "/api/v3/admin/store":
+ '204':
+ description: refund reason deleted
+ "/api/v3/admin/return_reasons":
get:
- summary: Get the current store
+ summary: List return reasons
tags:
- - Settings
+ - Reasons
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.
+ Why a customer is sending items back. Shared by returns and exchanges.
+
+ The vocabulary is the merchant's own — seeded with a starting set and
+ edited from the dashboard. Inactive rows stay for the records that
+ already reference them, but are not offered on new ones.
+
**Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
@@ -25916,10 +25936,10 @@ paths:
secretKey: 'sk_xxx',
})
- const store = await client.store.get()
+ const { data: reasons } = await client.returnReasons.list()
- lang: bash
label: Spree CLI
- source: spree api get /store
+ source: spree api get /return_reasons
parameters:
- name: x-spree-api-key
in: header
@@ -25932,295 +25952,80 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- responses:
- '200':
- description: current store
- content:
- application/json:
- example:
- id: store_UkLWZg9DAJ
- metadata: {}
- name: Spree Test Store
- code: spree_1
- default_currency: USD
- default_locale: en
- default_country_code: US
- mail_from_address: [email protected]
- customer_support_email: [email protected]
- new_order_notifications_email: [email protected]
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- order_routing_strategy: rules
- payout_provider:
- admin_locale:
- timezone: UTC
- storefront_url:
- weight_unit: lb
- unit_system: imperial
- storefront_access: public
- guest_checkout: true
- always_include_confirm_step: false
- company_field_enabled: false
- address_requires_company: false
- address_requires_phone: false
- capture_method: checkout
- track_inventory_levels: true
- stock_reservations_enabled: true
- low_stock_threshold: 5
- tax_using_ship_address: true
- track_price_history: true
- show_products_without_price: false
- disable_sku_validation: false
- pricing_provider: internal
- inventory_provider: internal
- pricing_provider_failure_policy: strict
- inventory_provider_failure_policy: fallback
- default_payouts_schedule_interval: monthly
- auto_approve_sellers: false
- auto_approve_seller_products: false
- send_seller_transactional_emails: true
- document_number_format: sequential
- order_number_prefix: R
- order_number_suffix: ''
- order_number_sequence_start: 1001
- limit_digital_download_count: true
- digital_asset_authorized_clicks: 5
- limit_digital_download_days: true
- digital_asset_authorized_days: 7
- send_consumer_transactional_emails: true
- email_accent_color:
- email_background_color:
- email_card_color:
- email_text_color:
- email_heading_color:
- email_font:
- order_number_sequence_started: false
- default_minimum_payout_amount: '0.00'
- default_commission_tax_rate: '0'
- url: http://www.example.com:3000
- api_url: http://www.example.com:3000
- setup_tasks:
- - name: setup_address
- done: false
- - name: setup_payment_method
- done: false
- - name: add_products
- done: false
- - name: set_customer_support_email
- done: true
- - name: setup_taxes_collection
- done: false
- - name: setup_storefront
- done: false
- supported_currencies:
- - USD
- - EUR
- - GBP
- supported_locales:
- - en
- available_locales:
- - aa
- - ab
- - ae
- - af
- - ak
- - am
- - an
- - ar
- - as
- - av
- - ay
- - az
- - ba
- - be
- - bg
- - bh
- - bi
- - bm
- - bn
- - bo
- - br
- - bs
- - ca
- - ce
- - ch
- - co
- - cr
- - cs
- - cu
- - cv
- - cy
- - da
- - de
- - de-AT
- - de-CH
- - dv
- - dz
- - ee
- - el
- - en
- - en-AU
- - en-CA
- - en-GB
- - en-IN
- - en-NZ
- - eo
- - es
- - es-419
- - es-MX
- - et
- - eu
- - fa
- - ff
- - fi
- - fj
- - fo
- - fr
- - fr-CA
- - fy
- - ga
- - gd
- - gl
- - gn
- - gu
- - gv
- - ha
- - he
- - hi
- - ho
- - hr
- - ht
- - hu
- - hy
- - hz
- - ia
- - id
- - ie
- - ig
- - ii
- - ik
- - io
- - is
- - it
- - iu
- - ja
- - jv
- - ka
- - kg
- - ki
- - kj
- - kk
- - kl
- - km
- - kn
- - ko
- - kr
- - ks
- - ku
- - kv
- - kw
- - ky
- - la
- - lb
- - lg
- - li
- - ln
- - lo
- - lt
- - lu
- - lv
- - mg
- - mh
- - mi
- - mk
- - ml
- - mn
- - mr
- - ms
- - mt
- - my
- - na
- - nb
- - nd
- - ne
- - ng
- - nl
- - nn
- - 'no'
- - nr
- - nv
- - ny
- - oc
- - oj
- - om
- - or
- - os
- - pa
- - pi
- - pl
- - ps
- - pt
- - pt-BR
- - pt-PT
- - qu
- - rm
- - rn
- - ro
- - ru
- - rw
- - sa
- - sc
- - sd
- - se
- - sg
- - si
- - sk
- - sl
- - sm
- - sn
- - so
- - sq
- - sr
- - ss
- - st
- - su
- - sv
- - sw
- - ta
- - te
- - tg
- - th
- - ti
- - tk
- - tl
- - tn
- - to
- - tr
- - ts
- - tt
- - tw
- - ty
- - ug
- - uk
- - ur
- - uz
- - ve
- - vi
- - vo
- - wa
- - wo
- - xh
- - yi
- - yo
- - za
- - zh-CN
- - zh-HK
- - zh-TW
- - zu
- logo_url:
- mailer_logo_url:
- schema:
- "$ref": "#/components/schemas/Store"
+ - 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: rar_UkLWZg9DAJ
+ name: Damaged in transit
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ can_be_deleted: true
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
'401':
description: unauthorized
content:
@@ -26231,15 +26036,15 @@ paths:
message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update the current store
+ post:
+ summary: Create a return reason
tags:
- - Settings
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Updates the current store configuration.
+ Adds a return reason to this store. Names are unique per store, ignoring case.
**Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
@@ -26253,12 +26058,101 @@ paths:
secretKey: 'sk_xxx',
})
- const store = await client.store.update({
- name: 'My Store',
+ const reason = await client.returnReasons.create({
+ name: 'Damaged in transit',
})
- lang: bash
label: Spree CLI
- source: spree api patch /store -d '{"name":"My Store"}'
+ source: spree api post /return_reasons -d '{"name":"Damaged in transit"}'
+ parameters:
+ - name: x-spree-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:
+ example:
+ id: rar_gbHJdmfrXB
+ name: A new reason
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ can_be_deleted: true
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ example: Damaged in transit
+ active:
+ type: boolean
+ example: true
+ 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.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const reason = await client.returnReasons.get('rar_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /return_reasons/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -26273,339 +26167,39 @@ paths:
type: string
responses:
'200':
- description: store updated
+ description: return reason found
content:
application/json:
example:
- id: store_UkLWZg9DAJ
- metadata: {}
- name: Renamed Store
- code: spree_1
- default_currency: USD
- default_locale: en
- default_country_code: US
- mail_from_address: [email protected]
- customer_support_email: [email protected]
- new_order_notifications_email: [email protected]
+ id: rar_UkLWZg9DAJ
+ name: Damaged in transit
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- order_routing_strategy: rules
- payout_provider:
- admin_locale:
- timezone: UTC
- storefront_url:
- weight_unit: lb
- unit_system: imperial
- storefront_access: public
- guest_checkout: true
- always_include_confirm_step: false
- company_field_enabled: false
- address_requires_company: false
- address_requires_phone: false
- capture_method: checkout
- track_inventory_levels: true
- stock_reservations_enabled: true
- low_stock_threshold: 5
- tax_using_ship_address: true
- track_price_history: true
- show_products_without_price: false
- disable_sku_validation: false
- pricing_provider: internal
- inventory_provider: internal
- pricing_provider_failure_policy: strict
- inventory_provider_failure_policy: fallback
- default_payouts_schedule_interval: monthly
- auto_approve_sellers: false
- auto_approve_seller_products: false
- send_seller_transactional_emails: true
- document_number_format: sequential
- order_number_prefix: R
- order_number_suffix: ''
- order_number_sequence_start: 1001
- limit_digital_download_count: true
- digital_asset_authorized_clicks: 5
- limit_digital_download_days: true
- digital_asset_authorized_days: 7
- send_consumer_transactional_emails: true
- email_accent_color:
- email_background_color:
- email_card_color:
- email_text_color:
- email_heading_color:
- email_font:
- order_number_sequence_started: false
- default_minimum_payout_amount: '0.00'
- default_commission_tax_rate: '0'
- url: http://www.example.com:3000
- api_url: http://www.example.com:3000
- setup_tasks:
- - name: setup_address
- done: false
- - name: setup_payment_method
- done: false
- - name: add_products
- done: false
- - name: set_customer_support_email
- done: true
- - name: setup_taxes_collection
- done: false
- - name: setup_storefront
- done: false
- supported_currencies:
- - USD
- - EUR
- - GBP
- supported_locales:
- - en
- available_locales:
- - aa
- - ab
- - ae
- - af
- - ak
- - am
- - an
- - ar
- - as
- - av
- - ay
- - az
- - ba
- - be
- - bg
- - bh
- - bi
- - bm
- - bn
- - bo
- - br
- - bs
- - ca
- - ce
- - ch
- - co
- - cr
- - cs
- - cu
- - cv
- - cy
- - da
- - de
- - de-AT
- - de-CH
- - dv
- - dz
- - ee
- - el
- - en
- - en-AU
- - en-CA
- - en-GB
- - en-IN
- - en-NZ
- - eo
- - es
- - es-419
- - es-MX
- - et
- - eu
- - fa
- - ff
- - fi
- - fj
- - fo
- - fr
- - fr-CA
- - fy
- - ga
- - gd
- - gl
- - gn
- - gu
- - gv
- - ha
- - he
- - hi
- - ho
- - hr
- - ht
- - hu
- - hy
- - hz
- - ia
- - id
- - ie
- - ig
- - ii
- - ik
- - io
- - is
- - it
- - iu
- - ja
- - jv
- - ka
- - kg
- - ki
- - kj
- - kk
- - kl
- - km
- - kn
- - ko
- - kr
- - ks
- - ku
- - kv
- - kw
- - ky
- - la
- - lb
- - lg
- - li
- - ln
- - lo
- - lt
- - lu
- - lv
- - mg
- - mh
- - mi
- - mk
- - ml
- - mn
- - mr
- - ms
- - mt
- - my
- - na
- - nb
- - nd
- - ne
- - ng
- - nl
- - nn
- - 'no'
- - nr
- - nv
- - ny
- - oc
- - oj
- - om
- - or
- - os
- - pa
- - pi
- - pl
- - ps
- - pt
- - pt-BR
- - pt-PT
- - qu
- - rm
- - rn
- - ro
- - ru
- - rw
- - sa
- - sc
- - sd
- - se
- - sg
- - si
- - sk
- - sl
- - sm
- - sn
- - so
- - sq
- - sr
- - ss
- - st
- - su
- - sv
- - sw
- - ta
- - te
- - tg
- - th
- - ti
- - tk
- - tl
- - tn
- - to
- - tr
- - ts
- - tt
- - tw
- - ty
- - ug
- - uk
- - ur
- - uz
- - ve
- - vi
- - vo
- - wa
- - wo
- - xh
- - yi
- - yo
- - za
- - zh-CN
- - zh-HK
- - zh-TW
- - zu
- logo_url:
- mailer_logo_url:
- schema:
- "$ref": "#/components/schemas/Store"
- '422':
- description: validation error
+ can_be_deleted: true
+ '404':
+ description: return reason not found
content:
application/json:
example:
error:
- code: validation_error
- message: Site Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
+ code: record_not_found
+ message: Return reason not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: My Store
- admin_locale:
- type: string
- example: en
- timezone:
- type: string
- example: UTC
- weight_unit:
- type: string
- example: kg
- unit_system:
- type: string
- example: metric
- "/api/v3/admin/tags":
- get:
- summary: List tags
+ patch:
+ summary: Update a return reason
tags:
- - Settings
+ - Reasons
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.
+ description: |-
+ Renames a return reason or retires it. Deactivating keeps it on the records
+ that already carry it while removing it from the pickers.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26617,13 +26211,12 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: tags } = await client.tags.list({
- taggable_type: 'customer',
- q: 'vip',
+ const reason = await client.returnReasons.update('rar_UkLWZg9DAJ', {
+ active: false,
})
- lang: bash
label: Spree CLI
- source: spree api get /tags -d '{"taggable_type":"customer","q":"vip"}'
+ source: spree api patch /return_reasons/{id} -d '{"active":false}'
parameters:
- name: x-spree-api-key
in: header
@@ -26633,57 +26226,60 @@ paths:
- 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
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'200':
- description: tags found
- content:
- application/json:
- example:
- data:
- - name: vip
- - name: wholesale
- '422':
- description: invalid taggable type
+ description: return reason updated
content:
application/json:
example:
- error:
- code: invalid_taggable_type
- message: taggable_type must be one of product, order, customer
- "/api/v3/admin/tax_rates":
- get:
- summary: List tax rates
+ id: rar_UkLWZg9DAJ
+ name: Damaged in transit
+ active: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ can_be_deleted: true
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ active:
+ type: boolean
+ delete:
+ summary: Delete a return reason
tags:
- - Settings
+ - Reasons
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the store's tax rates. Rates are the entire configuration of
- the built-in tax provider: each pairs a tax category with a jurisdiction
- (a country, optionally narrowed to one state) and a percentage, and
- decides whether the tax is already included in the product price
- (VAT-style) or added on top (US-style).
+ Removes a return reason the store no longer uses. A reason already recorded
+ on a document is refused — deactivate it instead, so the history it
+ explains stays readable.
- Markets using an external tax provider ignore these rows — that
- provider carries its own jurisdiction data.
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
- **Required scope:** `read_settings` (for API-key authentication).
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.returnReasons.delete('rar_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /return_reasons/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -26696,24 +26292,53 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: q[search]
- in: query
- required: false
+ 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.
+
+ **Required scope:** `read_promotions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: coupons } = await client.promotions.couponCodes.list('promo_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /promotions/{promotion_id}/coupon_codes
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
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
+ - name: Authorization
+ in: header
+ required: true
schema:
- type: integer
+ type: string
- name: q
in: query
required: false
@@ -26724,216 +26349,102 @@ paths:
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
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `included_in_price` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `promotion_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `state` | One of `unused`, `used` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **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.
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[promotion_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `promotion_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+
+ </Accordion>
+
+ **Sort by:** `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: TaxRate
+ table: CouponCode
sortable:
- - amount
- - country_code
+ - code
- created_at
- id
- - included_in_price
- - name
- - rate
- - state_code
- - tax_category_id
+ - promotion_id
+ - state
- updated_at
responses:
'200':
- description: tax rates found
+ description: coupon codes found
content:
application/json:
example:
data:
- - id: tax_UkLWZg9DAJ
- name: TaxRate - 124492
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
+ - id: coupon_UkLWZg9DAJ
+ code: AAA111
+ state: unused
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- deleted_at:
- rate: '0.19'
- rate_percent: '19'
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
+ promotion_id: promo_UkLWZg9DAJ
+ order_id:
+ - id: coupon_gbHJdmfrXB
+ code: BBB222
+ state: unused
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ promotion_id: promo_UkLWZg9DAJ
+ order_id:
meta:
page: 1
limit: 25
- count: 1
+ count: 2
pages: 1
from: 1
- to: 1
- in: 1
+ to: 2
+ in: 2
previous:
next:
- 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:
- example:
- error:
- code: authentication_required
- message: Authentication required
- 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
- decimal string (`"0.19"`) or `rate_percent` as a percentage string (`"19"`).
-
- Name the jurisdiction with `country_code` (and `state_code` for a
- state-level rate). Omitting the country makes the rate apply everywhere.
-
- Set `included_in_price` for VAT-style pricing, where the rate is backed
- out of the displayed price rather than added to it.
-
-
- **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:
- example:
- id: tax_gbHJdmfrXB
- name: VAT
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- deleted_at:
- rate: '0.19'
- rate_percent: '19'
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
- schema:
- "$ref": "#/components/schemas/TaxRate"
- '422':
- description: validation failed
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Tax category must exist and Name can't be blank
- details:
- tax_category:
- - code: blank
- message: must exist
- specific: true
- name:
- - code: blank
- message: can't be blank
- specific: false
- 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}":
+ "/api/v3/admin/promotions/{promotion_id}/promotion_actions":
parameters:
- - name: id
+ - name: promotion_id
in: path
- description: Tax rate ID
required: true
schema:
type: string
get:
- summary: Get a tax rate
+ summary: List actions for a promotion
tags:
- - Settings
+ - Promotions
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_settings` (for API-key authentication)."
+ description: "**Required scope:** `read_promotions` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: actions } = await client.promotions.actions.list('promo_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /promotions/{promotion_id}/promotion_actions
parameters:
- name: x-spree-api-key
in: header
@@ -26943,39 +26454,92 @@ paths:
- 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: tax rate found
+ description: actions found
content:
application/json:
example:
- id: tax_UkLWZg9DAJ
- name: TaxRate - 312890
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- deleted_at:
- rate: '0.19'
- rate_percent: '19'
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
- schema:
- "$ref": "#/components/schemas/TaxRate"
- patch:
- summary: Update a tax rate
+ data:
+ - id: pact_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: free_shipping
+ promotion_id: promo_UkLWZg9DAJ
+ preferences: {}
+ calculator:
+ line_items:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create an action on a promotion
tags:
- - Settings
+ - Promotions
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_settings` (for API-key authentication)."
+ 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`).
+
+ **Required scope:** `write_promotions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const action = await client.promotions.actions.create('promo_UkLWZg9DAJ', {
+ type: 'free_shipping',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /promotions/{promotion_id}/promotion_actions -d '{"type":"free_shipping"}'
parameters:
- name: x-spree-api-key
in: header
@@ -26985,65 +26549,79 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
- '200':
- description: tax rate updated
+ '201':
+ description: action created
content:
application/json:
example:
- id: tax_UkLWZg9DAJ
- name: TaxRate - 470830
- included_in_price: true
- show_rate_in_label: true
- metadata: {}
+ id: pact_UkLWZg9DAJ
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- deleted_at:
- rate: '0.07'
- rate_percent: '7'
- tax_category_id: taxcat_UkLWZg9DAJ
- store_id: store_UkLWZg9DAJ
- country_code: DE
- state_code:
- schema:
- "$ref": "#/components/schemas/TaxRate"
+ type: free_shipping
+ promotion_id: promo_UkLWZg9DAJ
+ preferences: {}
+ calculator:
+ line_items:
+ '422':
+ description: unknown action type
+ content:
+ application/json:
+ example:
+ error:
+ code: unknown_promotion_action_type
+ message: Unknown type
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:
type: string
- required: true
+ example: free_shipping
+ 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 a tax rate
+ summary: Delete an action from a promotion
tags:
- - Settings
+ - Promotions
security:
- api_key: []
bearer_auth: []
- description: |-
- Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.
+ description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
- **Required scope:** `write_settings` (for API-key authentication).
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.promotions.actions.delete('promo_UkLWZg9DAJ', 'promoact_k5nR8xLq')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /promotions/{promotion_id}/promotion_actions/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -27053,24 +26631,41 @@ paths:
- 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":
+ 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 translatable resources
+ summary: List rules for a promotion
tags:
- - Settings
+ - Promotions
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.
+ description: "**Required scope:** `read_promotions` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
- **Required scope:** `read_settings` (for API-key authentication).
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: rules } = await client.promotions.rules.list('promo_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /promotions/{promotion_id}/promotion_rules
parameters:
- name: x-spree-api-key
in: header
@@ -27082,104 +26677,92 @@ paths:
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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: translatable resources found
+ description: rules found
content:
application/json:
example:
data:
- - resource_type: option_type
- fields:
- - key: label
- type: string
- readable: true
- - resource_type: option_value
- fields:
- - key: label
- type: string
- readable: false
- - resource_type: product
- fields:
- - key: name
- type: string
- - key: description
- type: html
- - key: slug
- type: string
- - key: meta_description
- type: string
- - key: meta_title
- type: string
- readable: true
- - resource_type: product_type
- fields:
- - key: name
- type: string
- readable: false
- - resource_type: collection
- fields:
- - key: name
- type: string
- - key: description
- type: html
- - key: permalink
- type: string
- readable: true
- - resource_type: category
- fields:
- - key: name
- type: string
- - key: pretty_name
- type: string
- - key: description
- type: html
- - key: permalink
- type: string
- readable: true
- - resource_type: store
- fields:
- - key: name
- type: string
- - key: meta_description
- type: string
- - key: meta_keywords
- type: string
- - key: seo_title
- type: string
- - key: customer_support_email
- type: string
- - key: address
- type: string
- - key: contact_phone
- type: string
- readable: false
- - resource_type: policy
- fields:
- - key: name
- type: string
- - key: body
- type: html
- readable: true
- - resource_type: seller
- fields:
- - key: name
- type: string
- - key: about
- type: html
- readable: false
- "/api/v3/admin/translations/batch":
+ - id: prorule_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: currency
+ promotion_id: promo_UkLWZg9DAJ
+ preferences:
+ currency: USD
+ product_ids:
+ category_ids:
+ customer_ids:
+ option_value_ids:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
post:
- summary: Batch upsert translations
+ summary: Create a rule on a promotion
tags:
- - Settings
+ - Promotions
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.
+ Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`).
- **Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).
+ **Required scope:** `write_promotions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const rule = await client.promotions.rules.create('promo_UkLWZg9DAJ', {
+ type: 'currency',
+ preferences: { currency: 'EUR' },
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /promotions/{promotion_id}/promotion_rules -d '{"type":"currency","preferences":{"currency":"EUR"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -27192,270 +26775,64 @@ paths:
schema:
type: string
responses:
- '200':
- description: translations upserted
+ '201':
+ description: rule created with preferences
content:
application/json:
example:
- data:
- - resource_id: opt_UkLWZg9DAJ
- resource_type: option_type
- translations:
- de:
- label: Größe
- translated_field_count: 1
- fr:
- label:
- translated_field_count: 0
- default_locale: en
- supported_locales:
- - de
- - en
- - fr
- - resource_id: optval_UkLWZg9DAJ
- resource_type: option_value
- translations:
- de:
- label: Klein
- translated_field_count: 1
- fr:
- label:
- translated_field_count: 0
- default_locale: en
- supported_locales:
- - de
- - en
- - fr
+ id: prorule_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: currency
+ promotion_id: promo_UkLWZg9DAJ
+ preferences:
+ currency: EUR
+ product_ids:
+ category_ids:
+ customer_ids:
+ option_value_ids:
'422':
- description: unsupported locale rolls back the whole batch
+ description: unknown rule type
content:
application/json:
example:
error:
- code: validation_error
- message: 'Unsupported locale(s): es'
- details:
- translations:
- '0':
- - 'Unsupported locale(s): es'
+ code: unknown_promotion_rule_type
+ message: Unknown type
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.
-
- **Required scope:** `read_staff` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: staff } = await client.adminUsers.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /admin_users
- 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
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[spree_roles_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
-
- </Accordion>
-
- **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:
- example:
- data:
- - id: adm_UkLWZg9DAJ
- first_name: Carole
- last_name: Kling
- full_name: Carole Kling
- selected_locale:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- roles:
- - id: role_UkLWZg9DAJ
- name: admin
- stores:
- - id: store_UkLWZg9DAJ
- name: Spree Test Store
- code: spree_1
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- "/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)."
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const staff = await client.adminUsers.get('admin_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api get /admin_users/{id}
- 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:
- example:
- id: adm_UkLWZg9DAJ
- first_name: Lynell
- last_name: Heaney
- full_name: Lynell Heaney
- selected_locale:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- roles:
- - id: role_UkLWZg9DAJ
- name: admin
- stores:
- - id: store_UkLWZg9DAJ
- name: Spree Test Store
- code: spree_1
+ type:
+ type: string
+ example: currency
+ 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 staff member
+ summary: Update a rule's preferences
tags:
- - Staff
+ - Promotions
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.
-
- **Required scope:** `write_staff` (for API-key authentication).
+ description: "**Required scope:** `write_promotions` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27467,13 +26844,13 @@ paths:
secretKey: 'sk_xxx',
})
- const staff = await client.adminUsers.update('admin_xxx', {
- first_name: 'Ada',
- role_ids: ['role_xxx'],
+ const rule = await client.promotions.rules.update('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq', {
+ preferences: { currency: 'USD' },
})
- lang: bash
label: Spree CLI
- source: spree api patch /admin_users/{id} -d '{"first_name":"Ada","role_ids":["role_xxx"]}'
+ source: spree api patch /promotions/{promotion_id}/promotion_rules/{id} -d
+ '{"preferences":{"currency":"USD"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -27485,60 +26862,40 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
responses:
'200':
- description: staff member updated
+ description: rule updated
content:
application/json:
example:
- id: adm_UkLWZg9DAJ
- first_name: Renamed
- last_name: King
- full_name: Renamed King
- selected_locale:
+ id: prorule_UkLWZg9DAJ
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- roles:
- - id: role_UkLWZg9DAJ
- name: admin
- stores:
- - id: store_UkLWZg9DAJ
- name: Spree Test Store
- code: spree_1
+ type: currency
+ promotion_id: promo_UkLWZg9DAJ
+ preferences:
+ currency: GBP
+ product_ids:
+ category_ids:
+ customer_ids:
+ option_value_ids:
requestBody:
content:
application/json:
schema:
type: object
properties:
- first_name:
- type: string
- example: Ada
- last_name:
- type: string
- example: Lovelace
- role_ids:
- type: array
- items:
- type: string
+ preferences:
+ type: object
+ additionalProperties: true
delete:
- summary: Remove a staff member from this store
+ summary: Delete a rule from a promotion
tags:
- - Staff
+ - Promotions
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.
-
- **Required scope:** `write_staff` (for API-key authentication).
+ description: "**Required scope:** `write_promotions` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27550,10 +26907,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.adminUsers.delete('admin_xxx')
+ await client.promotions.rules.delete('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq')
- lang: bash
label: Spree CLI
- source: spree api delete /admin_users/{id}
+ source: spree api delete /promotions/{promotion_id}/promotion_rules/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -27565,26 +26922,21 @@ paths:
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":
+ description: rule deleted
+ "/api/v3/admin/promotions":
get:
- summary: List invitations
+ summary: List promotions
tags:
- - Staff
+ - Promotions
security:
- api_key: []
bearer_auth: []
description: |-
- Returns invitations for the current store, including pending and accepted.
+ Returns the store's promotions, including manual coupon and automatic promotions.
- **Required scope:** `read_staff` (for API-key authentication).
+ **Required scope:** `read_promotions` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27596,10 +26948,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: invitations } = await client.invitations.list()
+ const { data: promotions } = await client.promotions.list()
- lang: bash
label: Spree CLI
- source: spree api get /invitations
+ source: spree api get /promotions
parameters:
- name: x-spree-api-key
in: header
@@ -27611,6 +26963,12 @@ paths:
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
@@ -27625,41 +26983,71 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
+ | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `kind` | One of `coupon_code`, `automatic` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `path` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `promotion_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `starts_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[coupon_codes_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `coupon_codes_` | `code`, `created_at`, `id`, `promotion_id`, `state`, `updated_at` |
+
+ </Accordion>
+
+ **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: Invitation
+ table: Promotion
sortable:
+ - code
- created_at
+ - expires_at
- id
+ - kind
+ - name
+ - path
+ - promotion_category_id
+ - starts_at
- updated_at
responses:
'200':
- description: invitations found
+ description: promotions found
content:
application/json:
example:
data:
- - id: inv_UkLWZg9DAJ
- status: pending
+ - id: promo_UkLWZg9DAJ
+ name: Summer Sale
+ description:
+ code: summer
+ starts_at: '2026-01-15T11:00:00.000Z'
+ expires_at:
+ usage_limit:
+ match_policy: all
+ path:
+ kind: coupon_code
+ multi_codes: false
+ number_of_codes:
+ code_prefix:
+ promotion_category_id:
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- expires_at: '2026-01-29T12:00:00.000Z'
- role_id: role_UkLWZg9DAJ
- role_name: admin
- inviter_email: [email protected]
- invitee_exists: false
- store:
- id: store_UkLWZg9DAJ
- name: Spree Test Store
+ action_ids: []
+ rule_ids: []
meta:
page: 1
limit: 25
@@ -27671,16 +27059,22 @@ paths:
previous:
next:
post:
- summary: Create an invitation
+ summary: Create a promotion
tags:
- - Staff
+ - Promotions
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.
+ Creates a new promotion. `code` is required for single-code coupon promotions;
+ pass `multi_codes: true` with `number_of_codes` to auto-generate a batch.
- **Required scope:** `write_staff` (for API-key authentication).
+ Rules and actions can be created in the same request by passing arrays of
+ `{ type, preferences, ... }` rows. The server reconciles to the desired set:
+ new rows are built, existing rows (by `id`) are updated, omitted rows are removed.
+
+
+ **Required scope:** `write_promotions` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27692,13 +27086,51 @@ paths:
secretKey: 'sk_xxx',
})
- const invitation = await client.invitations.create({
- email: '[email protected]',
- role_id: 'role_xxx',
+ // Single coupon code, no rules/actions
+ const promotion = await client.promotions.create({
+ name: 'Black Friday',
+ code: 'BLACKFRIDAY',
+ starts_at: '2026-11-29T00:00:00Z',
+ expires_at: '2026-12-01T00:00:00Z',
+ })
+
+ // One-shot: promotion + rules + actions in a single request
+ const blackFriday = await client.promotions.create({
+ name: 'Black Friday',
+ code: 'BLACKFRIDAY',
+ kind: 'coupon_code',
+ starts_at: '2026-11-29T00:00:00Z',
+ expires_at: '2026-12-01T00:00:00Z',
+ match_policy: 'all',
+ rules: [
+ {
+ type: 'currency',
+ preferences: { currency: 'USD' },
+ },
+ {
+ type: 'item_total',
+ preferences: { amount_min: '100.00', operator_min: 'gte' },
+ },
+ {
+ type: 'product',
+ preferences: { match_policy: 'any' },
+ product_ids: ['prod_abc123', 'prod_def456'],
+ },
+ ],
+ actions: [
+ {
+ type: 'create_item_adjustments',
+ calculator: {
+ type: 'percent_on_line_item',
+ preferences: { percent: '25' },
+ },
+ },
+ { type: 'free_shipping' },
+ ],
})
- lang: bash
label: Spree CLI
- source: spree api post /invitations -d '{"email":"[email protected]","role_id":"role_xxx"}'
+ source: spree api post /promotions -d '{"name":"Black Friday","code":"BLACKFRIDAY","starts_at":"2026-11-29T00:00:00Z","expires_at":"2026-12-01T00:00:00Z"}'
parameters:
- name: x-spree-api-key
in: header
@@ -27712,47 +27144,155 @@ paths:
type: string
responses:
'201':
- description: invitation created
+ description: promotion created with rules and actions
content:
application/json:
example:
- id: inv_gbHJdmfrXB
- status: pending
+ id: promo_gbHJdmfrXB
+ name: Black Friday
+ description:
+ code: blackfriday-os
+ starts_at: '2026-01-15T12:00:00.000Z'
+ expires_at:
+ usage_limit:
+ match_policy: all
+ path:
+ kind: coupon_code
+ multi_codes: false
+ number_of_codes:
+ code_prefix:
+ promotion_category_id:
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- expires_at: '2026-01-29T12:00:00.000Z'
- role_id: role_UkLWZg9DAJ
- role_name: admin
- inviter_email: [email protected]
- invitee_exists: false
- store:
- id: store_UkLWZg9DAJ
- name: Spree Test Store
+ action_ids:
+ - pact_UkLWZg9DAJ
+ - pact_gbHJdmfrXB
+ rule_ids:
+ - prorule_UkLWZg9DAJ
+ - prorule_gbHJdmfrXB
+ - prorule_EfhxLZ9ck8
+ '422':
+ description: invalid params
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank and Code can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ code:
+ - code: blank
+ message: can't be blank
+ specific: false
requestBody:
content:
application/json:
schema:
type: object
- required:
- - email
- - role_id
properties:
- email:
+ name:
type: string
- role_id:
+ code:
type: string
- example: role_xxx
- "/api/v3/admin/invitations/{id}":
- delete:
- summary: Revoke an invitation
+ 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
+ example: currency
+ 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
+ example: free_shipping
+ preferences:
+ type: object
+ additionalProperties: true
+ calculator:
+ type: object
+ properties:
+ type:
+ type: string
+ example: flat_percent_item_total
+ preferences:
+ type: object
+ additionalProperties: true
+ required:
+ - type
+ required:
+ - name
+ "/api/v3/admin/promotions/{id}":
+ get:
+ summary: Show a promotion
tags:
- - Staff
+ - Promotions
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_staff` (for API-key authentication)."
+ description: "**Required scope:** `read_promotions` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27764,10 +27304,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.invitations.delete('inv_xxx')
+ const promotion = await client.promotions.get('promo_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /invitations/{id}
+ source: spree api get /promotions/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -27785,20 +27325,45 @@ paths:
schema:
type: string
responses:
- '204':
- description: invitation revoked
- "/api/v3/admin/invitations/{invitation_id}/acceptance_link":
- get:
- summary: Get an invitation acceptance link
+ '200':
+ description: promotion found
+ content:
+ application/json:
+ example:
+ id: promo_UkLWZg9DAJ
+ name: Summer Sale
+ description:
+ code: summer
+ starts_at: '2026-01-15T11:00:00.000Z'
+ expires_at:
+ usage_limit:
+ match_policy: all
+ path:
+ kind: coupon_code
+ multi_codes: false
+ number_of_codes:
+ code_prefix:
+ promotion_category_id:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ action_ids: []
+ rule_ids: []
+ patch:
+ summary: Update a promotion
tags:
- - Staff
+ - Promotions
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.
+ Updates a promotion. The `rules` and `actions` arrays are treated as
+ a *desired set* — rows with `id` update in place, rows without `id` are
+ built fresh, and any existing row not present in the array is destroyed.
+ Pass `rules: []` or `actions: []` to clear them.
- **Required scope:** `write_staff` (for API-key authentication).
+
+ **Required scope:** `write_promotions` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27810,10 +27375,48 @@ paths:
secretKey: 'sk_xxx',
})
- const { acceptance_url } = await client.invitations.acceptanceLink('inv_xxx')
+ // Basic field update
+ await client.promotions.update(promotionId, {
+ description: 'Updated description',
+ })
+
+ // One-shot: rewrite rules + actions in a single request
+ await client.promotions.update(promotionId, {
+ name: 'Holiday Sale',
+ rules: [
+ // Update an existing rule by id — `preferences` overwrite the prior set
+ {
+ id: 'prorule_existing',
+ type: 'currency',
+ preferences: { currency: 'EUR' },
+ },
+ // Add a new rule
+ {
+ type: 'item_total',
+ preferences: { amount_min: '50.00', operator_min: 'gte' },
+ },
+ ],
+ actions: [
+ // Swap calculator type on an existing action
+ {
+ id: 'proaction_existing',
+ type: 'create_item_adjustments',
+ calculator: {
+ type: 'percent_on_line_item',
+ preferences: { percent: '15' },
+ },
+ },
+ ],
+ })
+
+ // Remove all rules/actions
+ await client.promotions.update(promotionId, {
+ rules: [],
+ actions: [],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /invitations/{invitation_id}/acceptance_link
+ source: spree api patch /promotions/{id} -d '{"description":"Updated description"}'
parameters:
- name: x-spree-api-key
in: header
@@ -27825,33 +27428,137 @@ paths:
required: true
schema:
type: string
- - name: invitation_id
+ - name: id
in: path
required: true
schema:
type: string
responses:
'200':
- description: acceptance link found
+ description: rules and actions cleared with empty arrays
content:
application/json:
example:
- id: inv_UkLWZg9DAJ
- acceptance_url: http://www.example.com:3000/accept-invitation/inv_UkLWZg9DAJ?token=jDy3giwKk1iUW1wTMg5LRLEG
- schema:
- "$ref": "#/components/schemas/InvitationAcceptanceLink"
- "/api/v3/admin/invitations/{id}/resend":
- patch:
- summary: Resend an invitation
+ id: promo_UkLWZg9DAJ
+ name: Summer Sale
+ description:
+ code: summer
+ starts_at: '2026-01-15T11:00:00.000Z'
+ expires_at:
+ usage_limit:
+ match_policy: all
+ path:
+ kind: coupon_code
+ multi_codes: false
+ number_of_codes:
+ code_prefix:
+ promotion_category_id:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ action_ids: []
+ rule_ids: []
+ 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
+ example: currency
+ 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
+ example: free_shipping
+ preferences:
+ type: object
+ additionalProperties: true
+ calculator:
+ type: object
+ properties:
+ type:
+ type: string
+ example: flat_percent_item_total
+ preferences:
+ type: object
+ additionalProperties: true
+ required:
+ - type
+ delete:
+ summary: Delete a promotion
tags:
- - Staff
+ - Promotions
security:
- api_key: []
bearer_auth: []
- description: |-
- Issues a fresh token and dispatches the invitation email again.
-
- **Required scope:** `write_staff` (for API-key authentication).
+ description: "**Required scope:** `write_promotions` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27863,10 +27570,10 @@ paths:
secretKey: 'sk_xxx',
})
- const invitation = await client.invitations.resend('inv_xxx')
+ await client.promotions.delete('promo_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /invitations/{id}/resend -d '{ ... }'
+ source: spree api delete /promotions/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -27883,37 +27590,95 @@ paths:
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.
+
+ **Required scope:** `read_promotions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: actionTypes } = await client.promotionActions.types()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /promotion_actions/types
+ 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: invitation resent
+ description: action types found
content:
application/json:
example:
- id: inv_UkLWZg9DAJ
- status: pending
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- expires_at: '2026-01-29T12:00:00.000Z'
- role_id: role_UkLWZg9DAJ
- role_name: admin
- inviter_email: [email protected]
- invitee_exists: false
- store:
- id: store_UkLWZg9DAJ
- name: Spree Test Store
- "/api/v3/admin/permissions":
+ data:
+ - type: create_line_items
+ label: Create line items
+ description: Adds the specified quantity of a variant to the cart
+ free of charge
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: create_item_adjustments
+ label: Create per-line-item adjustment
+ description: Creates a promotion credit adjustment on a line item
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: create_adjustment
+ label: Create whole-order adjustment
+ description: Creates a promotion credit adjustment on the order
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: free_shipping
+ label: Free shipping
+ description: Makes all shipments for the order free
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ "/api/v3/admin/promotion_rules/types":
get:
- summary: List the permission catalog
+ summary: List available promotion rule types
tags:
- - Staff
+ - Promotions
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.
+ description: |-
+ Returns the registered Spree::PromotionRule subclasses with their preference schemas.
+
+ **Required scope:** `read_promotions` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27925,10 +27690,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: permissions } = await client.permissions.list()
+ const { data: ruleTypes } = await client.promotionRules.types()
- lang: bash
label: Spree CLI
- source: spree api get /permissions
+ source: spree api get /promotion_rules/types
parameters:
- name: x-spree-api-key
in: header
@@ -27942,65 +27707,2647 @@ paths:
type: string
responses:
'200':
- description: catalog returned
+ description: rule types found
content:
application/json:
example:
data:
- - key: read_dashboard
- resource: dashboard
- kind: read
- group: analytics
- group_label: Analytics
- label: Analytics dashboard
- description: Sales and performance analytics
- - key: read_reports
- resource: reports
- kind: read
- group: analytics
- group_label: Analytics
- label: Reports
- description: ''
- - key: write_reports
- resource: reports
- kind: write
- group: analytics
- group_label: Analytics
- label: Reports
- description: ''
- - key: read_orders
- resource: orders
- kind: read
- group: orders
- group_label: Orders
- label: Orders
- description: Orders, line items, returns, exchanges and claims
- - key: write_orders
- resource: orders
- kind: write
- group: orders
- group_label: Orders
- label: Orders
- description: Orders, line items, returns, exchanges and claims
- - key: read_payments
- resource: payments
- kind: read
- group: orders
- group_label: Orders
- label: Payments
- description: Order payments and payment capture
- - key: write_payments
- resource: payments
- kind: write
- group: orders
- group_label: Orders
- label: Payments
- description: Order payments and payment capture
- - key: read_fulfillments
- resource: fulfillments
- kind: read
- group: orders
- group_label: Orders
+ - type: category
+ label: Categories
+ description: Order includes products in specified categories
+ schema:
+ type: object
+ properties:
+ match_policy:
+ type: string
+ enum:
+ - any
+ - all
+ default: any
+ additionalProperties: false
+ - type: channel
+ label: Channel(s)
+ description: Limit to orders placed through specified channel(s)
+ schema:
+ 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
+ - type: country
+ label: Country
+ description: Limit to orders with shipping address in a specific
+ country
+ schema:
+ type: object
+ properties:
+ country_codes:
+ type: array
+ items:
+ type: string
+ format: iso-country
+ pattern: "^[A-Z]{2}$"
+ default: []
+ country_id:
+ type:
+ - integer
+ - 'null'
+ country_code:
+ type:
+ - string
+ - 'null'
+ format: iso-country
+ pattern: "^[A-Z]{2}$"
+ additionalProperties: false
+ - type: currency
+ label: Currency
+ description: Limit to orders in a specific currency
+ schema:
+ type: object
+ properties:
+ currency:
+ type:
+ - string
+ - 'null'
+ format: currency
+ pattern: "^[A-Z]{3}$"
+ additionalProperties: false
+ - type: customer_group
+ label: Customer Group(s)
+ description: Available only to customers in specified customer group(s)
+ schema:
+ 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
+ - type: customer
+ label: Customers
+ description: Available only to the specified customers
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: first_order
+ label: First order
+ description: Must be the customer's first order
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: item_total
+ label: Item total
+ description: Order total meets these criteria
+ schema:
+ type: object
+ properties:
+ amount_min:
+ type: string
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: '100'
+ operator_min:
+ type: string
+ default: ">"
+ amount_max:
+ type:
+ - string
+ - 'null'
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ operator_max:
+ type: string
+ default: "<"
+ additionalProperties: false
+ - type: market
+ label: Market(s)
+ description: Limit to orders placed in specified market(s)
+ schema:
+ 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
+ - type: one_use_per_user
+ label: One Use Per User
+ description: Only One Use Per User
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: customer_logged_in
+ label: Only logged in customers
+ description: Available only to logged in customers
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: option_value
+ label: Option Value(s)
+ description: Order includes products with matching option value(s)
+ schema:
+ 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
+ - type: product
+ label: Product(s)
+ description: Order includes specified product(s)
+ schema:
+ type: object
+ properties:
+ match_policy:
+ type: string
+ enum:
+ - any
+ - all
+ - none
+ default: any
+ additionalProperties: false
+ "/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.
+
+ **Required scope:** `read_refunds` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: refunds } = await client.orders.refunds.list('or_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /orders/{order_id}/refunds
+ parameters:
+ - name: x-spree-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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data: []
+ meta:
+ page: 1
+ limit: 25
+ count: 0
+ pages: 1
+ from: 0
+ to: 0
+ in: 0
+ previous:
+ next:
+ 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.
+
+ **Required scope:** `write_refunds` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const refund = await client.orders.refunds.create('or_UkLWZg9DAJ', {
+ payment_id: 'pay_UkLWZg9DAJ',
+ amount: '5.00',
+ refund_reason_id: 'rr_UkLWZg9DAJ',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /orders/{order_id}/refunds -d '{"payment_id":"pay_UkLWZg9DAJ","amount":"5.00","refund_reason_id":"rr_UkLWZg9DAJ"}'
+ parameters:
+ - name: x-spree-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:
+ example:
+ id: re_UkLWZg9DAJ
+ transaction_id: BGS-c5ae59a82a25
+ amount: '5.00'
+ payment_id: py_UkLWZg9DAJ
+ refund_reason_id: rr_UkLWZg9DAJ
+ originator_id:
+ originator_type:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ tax_amount: '0.00'
+ refunder_id: adm_UkLWZg9DAJ
+ refunder_type: admin_user
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - payment_id
+ - amount
+ properties:
+ payment_id:
+ type: string
+ description: Payment ID
+ amount:
+ type: string
+ example: '10.00'
+ 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.
+
+ **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:
+ example:
+ data:
+ - code: de
+ name: Deutsch
+ default: false
+ rtl: false
+ - code: en
+ name: English
+ default: true
+ rtl: false
+ - code: fr
+ name: Français
+ default: false
+ rtl: false
+ "/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.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const store = await client.store.get()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /store
+ parameters:
+ - name: x-spree-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:
+ example:
+ id: store_UkLWZg9DAJ
+ metadata: {}
+ name: Spree Test Store
+ code: spree_1
+ default_currency: USD
+ default_locale: en
+ default_country_code: US
+ mail_from_address: [email protected]
+ customer_support_email: [email protected]
+ new_order_notifications_email: [email protected]
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_routing_strategy: rules
+ payout_provider:
+ admin_locale:
+ timezone: UTC
+ storefront_url:
+ weight_unit: lb
+ unit_system: imperial
+ storefront_access: public
+ guest_checkout: true
+ always_include_confirm_step: false
+ company_field_enabled: false
+ address_requires_company: false
+ address_requires_phone: false
+ capture_method: checkout
+ track_inventory_levels: true
+ stock_reservations_enabled: true
+ low_stock_threshold: 5
+ tax_using_ship_address: true
+ track_price_history: true
+ show_products_without_price: false
+ disable_sku_validation: false
+ pricing_provider: internal
+ inventory_provider: internal
+ pricing_provider_failure_policy: strict
+ inventory_provider_failure_policy: fallback
+ default_payouts_schedule_interval: monthly
+ auto_approve_sellers: false
+ auto_approve_seller_products: false
+ send_seller_transactional_emails: true
+ document_number_format: sequential
+ order_number_prefix: R
+ order_number_suffix: ''
+ order_number_sequence_start: 1001
+ limit_digital_download_count: true
+ digital_asset_authorized_clicks: 5
+ limit_digital_download_days: true
+ digital_asset_authorized_days: 7
+ send_consumer_transactional_emails: true
+ email_accent_color:
+ email_background_color:
+ email_card_color:
+ email_text_color:
+ email_heading_color:
+ email_font:
+ order_number_sequence_started: false
+ default_minimum_payout_amount: '0.00'
+ default_commission_tax_rate: '0'
+ url: http://www.example.com:3000
+ api_url: http://www.example.com:3000
+ setup_tasks:
+ - name: setup_address
+ done: false
+ - name: setup_payment_method
+ done: false
+ - name: add_products
+ done: false
+ - name: set_customer_support_email
+ done: true
+ - name: setup_taxes_collection
+ done: false
+ - name: setup_storefront
+ done: false
+ supported_currencies:
+ - USD
+ - EUR
+ - GBP
+ supported_locales:
+ - en
+ available_locales:
+ - aa
+ - ab
+ - ae
+ - af
+ - ak
+ - am
+ - an
+ - ar
+ - as
+ - av
+ - ay
+ - az
+ - ba
+ - be
+ - bg
+ - bh
+ - bi
+ - bm
+ - bn
+ - bo
+ - br
+ - bs
+ - ca
+ - ce
+ - ch
+ - co
+ - cr
+ - cs
+ - cu
+ - cv
+ - cy
+ - da
+ - de
+ - de-AT
+ - de-CH
+ - dv
+ - dz
+ - ee
+ - el
+ - en
+ - en-AU
+ - en-CA
+ - en-GB
+ - en-IN
+ - en-NZ
+ - eo
+ - es
+ - es-419
+ - es-MX
+ - et
+ - eu
+ - fa
+ - ff
+ - fi
+ - fj
+ - fo
+ - fr
+ - fr-CA
+ - fy
+ - ga
+ - gd
+ - gl
+ - gn
+ - gu
+ - gv
+ - ha
+ - he
+ - hi
+ - ho
+ - hr
+ - ht
+ - hu
+ - hy
+ - hz
+ - ia
+ - id
+ - ie
+ - ig
+ - ii
+ - ik
+ - io
+ - is
+ - it
+ - iu
+ - ja
+ - jv
+ - ka
+ - kg
+ - ki
+ - kj
+ - kk
+ - kl
+ - km
+ - kn
+ - ko
+ - kr
+ - ks
+ - ku
+ - kv
+ - kw
+ - ky
+ - la
+ - lb
+ - lg
+ - li
+ - ln
+ - lo
+ - lt
+ - lu
+ - lv
+ - mg
+ - mh
+ - mi
+ - mk
+ - ml
+ - mn
+ - mr
+ - ms
+ - mt
+ - my
+ - na
+ - nb
+ - nd
+ - ne
+ - ng
+ - nl
+ - nn
+ - 'no'
+ - nr
+ - nv
+ - ny
+ - oc
+ - oj
+ - om
+ - or
+ - os
+ - pa
+ - pi
+ - pl
+ - ps
+ - pt
+ - pt-BR
+ - pt-PT
+ - qu
+ - rm
+ - rn
+ - ro
+ - ru
+ - rw
+ - sa
+ - sc
+ - sd
+ - se
+ - sg
+ - si
+ - sk
+ - sl
+ - sm
+ - sn
+ - so
+ - sq
+ - sr
+ - ss
+ - st
+ - su
+ - sv
+ - sw
+ - ta
+ - te
+ - tg
+ - th
+ - ti
+ - tk
+ - tl
+ - tn
+ - to
+ - tr
+ - ts
+ - tt
+ - tw
+ - ty
+ - ug
+ - uk
+ - ur
+ - uz
+ - ve
+ - vi
+ - vo
+ - wa
+ - wo
+ - xh
+ - yi
+ - yo
+ - za
+ - zh-CN
+ - zh-HK
+ - zh-TW
+ - zu
+ logo_url:
+ mailer_logo_url:
+ schema:
+ "$ref": "#/components/schemas/Store"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update the current store
+ tags:
+ - Settings
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Updates the current store configuration.
+
+ **Required scope:** `write_settings` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const store = await client.store.update({
+ name: 'My Store',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /store -d '{"name":"My Store"}'
+ parameters:
+ - name: x-spree-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:
+ example:
+ id: store_UkLWZg9DAJ
+ metadata: {}
+ name: Renamed Store
+ code: spree_1
+ default_currency: USD
+ default_locale: en
+ default_country_code: US
+ mail_from_address: [email protected]
+ customer_support_email: [email protected]
+ new_order_notifications_email: [email protected]
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_routing_strategy: rules
+ payout_provider:
+ admin_locale:
+ timezone: UTC
+ storefront_url:
+ weight_unit: lb
+ unit_system: imperial
+ storefront_access: public
+ guest_checkout: true
+ always_include_confirm_step: false
+ company_field_enabled: false
+ address_requires_company: false
+ address_requires_phone: false
+ capture_method: checkout
+ track_inventory_levels: true
+ stock_reservations_enabled: true
+ low_stock_threshold: 5
+ tax_using_ship_address: true
+ track_price_history: true
+ show_products_without_price: false
+ disable_sku_validation: false
+ pricing_provider: internal
+ inventory_provider: internal
+ pricing_provider_failure_policy: strict
+ inventory_provider_failure_policy: fallback
+ default_payouts_schedule_interval: monthly
+ auto_approve_sellers: false
+ auto_approve_seller_products: false
+ send_seller_transactional_emails: true
+ document_number_format: sequential
+ order_number_prefix: R
+ order_number_suffix: ''
+ order_number_sequence_start: 1001
+ limit_digital_download_count: true
+ digital_asset_authorized_clicks: 5
+ limit_digital_download_days: true
+ digital_asset_authorized_days: 7
+ send_consumer_transactional_emails: true
+ email_accent_color:
+ email_background_color:
+ email_card_color:
+ email_text_color:
+ email_heading_color:
+ email_font:
+ order_number_sequence_started: false
+ default_minimum_payout_amount: '0.00'
+ default_commission_tax_rate: '0'
+ url: http://www.example.com:3000
+ api_url: http://www.example.com:3000
+ setup_tasks:
+ - name: setup_address
+ done: false
+ - name: setup_payment_method
+ done: false
+ - name: add_products
+ done: false
+ - name: set_customer_support_email
+ done: true
+ - name: setup_taxes_collection
+ done: false
+ - name: setup_storefront
+ done: false
+ supported_currencies:
+ - USD
+ - EUR
+ - GBP
+ supported_locales:
+ - en
+ available_locales:
+ - aa
+ - ab
+ - ae
+ - af
+ - ak
+ - am
+ - an
+ - ar
+ - as
+ - av
+ - ay
+ - az
+ - ba
+ - be
+ - bg
+ - bh
+ - bi
+ - bm
+ - bn
+ - bo
+ - br
+ - bs
+ - ca
+ - ce
+ - ch
+ - co
+ - cr
+ - cs
+ - cu
+ - cv
+ - cy
+ - da
+ - de
+ - de-AT
+ - de-CH
+ - dv
+ - dz
+ - ee
+ - el
+ - en
+ - en-AU
+ - en-CA
+ - en-GB
+ - en-IN
+ - en-NZ
+ - eo
+ - es
+ - es-419
+ - es-MX
+ - et
+ - eu
+ - fa
+ - ff
+ - fi
+ - fj
+ - fo
+ - fr
+ - fr-CA
+ - fy
+ - ga
+ - gd
+ - gl
+ - gn
+ - gu
+ - gv
+ - ha
+ - he
+ - hi
+ - ho
+ - hr
+ - ht
+ - hu
+ - hy
+ - hz
+ - ia
+ - id
+ - ie
+ - ig
+ - ii
+ - ik
+ - io
+ - is
+ - it
+ - iu
+ - ja
+ - jv
+ - ka
+ - kg
+ - ki
+ - kj
+ - kk
+ - kl
+ - km
+ - kn
+ - ko
+ - kr
+ - ks
+ - ku
+ - kv
+ - kw
+ - ky
+ - la
+ - lb
+ - lg
+ - li
+ - ln
+ - lo
+ - lt
+ - lu
+ - lv
+ - mg
+ - mh
+ - mi
+ - mk
+ - ml
+ - mn
+ - mr
+ - ms
+ - mt
+ - my
+ - na
+ - nb
+ - nd
+ - ne
+ - ng
+ - nl
+ - nn
+ - 'no'
+ - nr
+ - nv
+ - ny
+ - oc
+ - oj
+ - om
+ - or
+ - os
+ - pa
+ - pi
+ - pl
+ - ps
+ - pt
+ - pt-BR
+ - pt-PT
+ - qu
+ - rm
+ - rn
+ - ro
+ - ru
+ - rw
+ - sa
+ - sc
+ - sd
+ - se
+ - sg
+ - si
+ - sk
+ - sl
+ - sm
+ - sn
+ - so
+ - sq
+ - sr
+ - ss
+ - st
+ - su
+ - sv
+ - sw
+ - ta
+ - te
+ - tg
+ - th
+ - ti
+ - tk
+ - tl
+ - tn
+ - to
+ - tr
+ - ts
+ - tt
+ - tw
+ - ty
+ - ug
+ - uk
+ - ur
+ - uz
+ - ve
+ - vi
+ - vo
+ - wa
+ - wo
+ - xh
+ - yi
+ - yo
+ - za
+ - zh-CN
+ - zh-HK
+ - zh-TW
+ - zu
+ logo_url:
+ mailer_logo_url:
+ schema:
+ "$ref": "#/components/schemas/Store"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Site Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: My Store
+ admin_locale:
+ type: string
+ example: en
+ timezone:
+ type: string
+ example: UTC
+ weight_unit:
+ type: string
+ example: kg
+ unit_system:
+ type: string
+ example: metric
+ "/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.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: tags } = await client.tags.list({
+ taggable_type: 'customer',
+ q: 'vip',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /tags -d '{"taggable_type":"customer","q":"vip"}'
+ 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:
+ example:
+ data:
+ - name: vip
+ - name: wholesale
+ '422':
+ description: invalid taggable type
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_taggable_type
+ message: taggable_type must be one of product, order, customer
+ "/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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `is_default` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `tax_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: taxcat_UkLWZg9DAJ
+ name: Clothing
+ tax_code:
+ description: Accusamus architecto mollitia possimus eos tempore
+ laudantium.
+ is_default: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
+ the built-in tax provider: each pairs a tax category with a jurisdiction
+ (a country, optionally narrowed to one state) and a percentage, and
+ decides whether the tax is already included in the product price
+ (VAT-style) or added on top (US-style).
+
+ Markets using an external tax provider ignore these rows — that
+ provider carries its own jurisdiction data.
+
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `included_in_price` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `tax_category_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: tax_UkLWZg9DAJ
+ name: TaxRate - 124492
+ included_in_price: true
+ show_rate_in_label: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ rate: '0.19'
+ rate_percent: '19'
+ tax_category_id: taxcat_UkLWZg9DAJ
+ store_id: store_UkLWZg9DAJ
+ country_code: DE
+ state_code:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ 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
+ decimal string (`"0.19"`) or `rate_percent` as a percentage string (`"19"`).
+
+ Name the jurisdiction with `country_code` (and `state_code` for a
+ state-level rate). Omitting the country makes the rate apply everywhere.
+
+ Set `included_in_price` for VAT-style pricing, where the rate is backed
+ out of the displayed price rather than added to it.
+
+
+ **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:
+ example:
+ id: tax_gbHJdmfrXB
+ name: VAT
+ included_in_price: true
+ show_rate_in_label: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ rate: '0.19'
+ rate_percent: '19'
+ tax_category_id: taxcat_UkLWZg9DAJ
+ store_id: store_UkLWZg9DAJ
+ country_code: DE
+ state_code:
+ schema:
+ "$ref": "#/components/schemas/TaxRate"
+ '422':
+ description: validation failed
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Tax category must exist and Name can't be blank
+ details:
+ tax_category:
+ - code: blank
+ message: must exist
+ specific: true
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ 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:
+ example:
+ id: tax_UkLWZg9DAJ
+ name: TaxRate - 312890
+ included_in_price: true
+ show_rate_in_label: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ rate: '0.19'
+ rate_percent: '19'
+ tax_category_id: taxcat_UkLWZg9DAJ
+ store_id: store_UkLWZg9DAJ
+ country_code: DE
+ state_code:
+ 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:
+ example:
+ id: tax_UkLWZg9DAJ
+ name: TaxRate - 470830
+ included_in_price: true
+ show_rate_in_label: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ rate: '0.07'
+ rate_percent: '7'
+ tax_category_id: taxcat_UkLWZg9DAJ
+ store_id: store_UkLWZg9DAJ
+ country_code: DE
+ state_code:
+ 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.
+
+ **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.
+
+ **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:
+ example:
+ data:
+ - resource_type: option_type
+ fields:
+ - key: label
+ type: string
+ readable: true
+ - resource_type: option_value
+ fields:
+ - key: label
+ type: string
+ readable: false
+ - resource_type: product
+ fields:
+ - key: name
+ type: string
+ - key: description
+ type: html
+ - key: slug
+ type: string
+ - key: meta_description
+ type: string
+ - key: meta_title
+ type: string
+ readable: true
+ - resource_type: product_type
+ fields:
+ - key: name
+ type: string
+ readable: false
+ - resource_type: collection
+ fields:
+ - key: name
+ type: string
+ - key: description
+ type: html
+ - key: permalink
+ type: string
+ readable: true
+ - resource_type: category
+ fields:
+ - key: name
+ type: string
+ - key: pretty_name
+ type: string
+ - key: description
+ type: html
+ - key: permalink
+ type: string
+ readable: true
+ - resource_type: store
+ fields:
+ - key: name
+ type: string
+ - key: meta_description
+ type: string
+ - key: meta_keywords
+ type: string
+ - key: seo_title
+ type: string
+ - key: customer_support_email
+ type: string
+ - key: address
+ type: string
+ - key: contact_phone
+ type: string
+ readable: false
+ - resource_type: policy
+ fields:
+ - key: name
+ type: string
+ - key: body
+ type: html
+ readable: true
+ - resource_type: seller
+ fields:
+ - key: name
+ type: string
+ - key: about
+ type: html
+ readable: false
+ "/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.
+
+ **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:
+ example:
+ data:
+ - resource_id: opt_UkLWZg9DAJ
+ resource_type: option_type
+ translations:
+ de:
+ label: Größe
+ translated_field_count: 1
+ fr:
+ label:
+ translated_field_count: 0
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
+ - resource_id: optval_UkLWZg9DAJ
+ resource_type: option_value
+ translations:
+ de:
+ label: Klein
+ translated_field_count: 1
+ fr:
+ label:
+ translated_field_count: 0
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
+ '422':
+ description: unsupported locale rolls back the whole batch
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: 'Unsupported locale(s): es'
+ details:
+ translations:
+ '0':
+ - 'Unsupported locale(s): es'
+ 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.
+
+ **Required scope:** `read_staff` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: staff } = await client.adminUsers.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /admin_users
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[spree_roles_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `spree_roles_` | `created_at`, `id`, `name`, `updated_at` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: adm_UkLWZg9DAJ
+ first_name: Carole
+ last_name: Kling
+ full_name: Carole Kling
+ selected_locale:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ stores:
+ - id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ code: spree_1
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/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)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const staff = await client.adminUsers.get('admin_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /admin_users/{id}
+ 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:
+ example:
+ id: adm_UkLWZg9DAJ
+ first_name: Lynell
+ last_name: Heaney
+ full_name: Lynell Heaney
+ selected_locale:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ stores:
+ - id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ code: spree_1
+ 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.
+
+ **Required scope:** `write_staff` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const staff = await client.adminUsers.update('admin_xxx', {
+ first_name: 'Ada',
+ role_ids: ['role_xxx'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /admin_users/{id} -d '{"first_name":"Ada","role_ids":["role_xxx"]}'
+ 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:
+ example:
+ id: adm_UkLWZg9DAJ
+ first_name: Renamed
+ last_name: King
+ full_name: Renamed King
+ selected_locale:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ roles:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ stores:
+ - id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ code: spree_1
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ first_name:
+ type: string
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ 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.
+
+ **Required scope:** `write_staff` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.adminUsers.delete('admin_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /admin_users/{id}
+ 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.
+
+ **Required scope:** `read_staff` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: invitations } = await client.invitations.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /invitations
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: inv_UkLWZg9DAJ
+ status: pending
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ role_id: role_UkLWZg9DAJ
+ role_name: admin
+ inviter_email: [email protected]
+ invitee_exists: false
+ store:
+ id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **Required scope:** `write_staff` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const invitation = await client.invitations.create({
+ email: '[email protected]',
+ role_id: 'role_xxx',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /invitations -d '{"email":"[email protected]","role_id":"role_xxx"}'
+ 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:
+ example:
+ id: inv_gbHJdmfrXB
+ status: pending
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ role_id: role_UkLWZg9DAJ
+ role_name: admin
+ inviter_email: [email protected]
+ invitee_exists: false
+ store:
+ id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - email
+ - role_id
+ properties:
+ email:
+ type: string
+ role_id:
+ type: string
+ example: role_xxx
+ "/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)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.invitations.delete('inv_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /invitations/{id}
+ 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.
+
+ **Required scope:** `write_staff` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { acceptance_url } = await client.invitations.acceptanceLink('inv_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /invitations/{invitation_id}/acceptance_link
+ 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:
+ example:
+ id: inv_UkLWZg9DAJ
+ acceptance_url: http://www.example.com:3000/accept-invitation/inv_UkLWZg9DAJ?token=jDy3giwKk1iUW1wTMg5LRLEG
+ 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.
+
+ **Required scope:** `write_staff` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const invitation = await client.invitations.resend('inv_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /invitations/{id}/resend -d '{ ... }'
+ 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:
+ example:
+ id: inv_UkLWZg9DAJ
+ status: pending
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ role_id: role_UkLWZg9DAJ
+ role_name: admin
+ inviter_email: [email protected]
+ invitee_exists: false
+ store:
+ id: store_UkLWZg9DAJ
+ name: Spree Test Store
+ "/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.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: permissions } = await client.permissions.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /permissions
+ 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:
+ example:
+ data:
+ - key: read_dashboard
+ resource: dashboard
+ kind: read
+ group: analytics
+ group_label: Analytics
+ label: Analytics dashboard
+ description: Sales and performance analytics
+ - key: read_reports
+ resource: reports
+ kind: read
+ group: analytics
+ group_label: Analytics
+ label: Reports
+ description: ''
+ - key: write_reports
+ resource: reports
+ kind: write
+ group: analytics
+ group_label: Analytics
+ label: Reports
+ description: ''
+ - key: read_orders
+ resource: orders
+ kind: read
+ group: orders
+ group_label: Orders
+ label: Orders
+ description: Orders, line items, returns, exchanges and claims
+ - key: write_orders
+ resource: orders
+ kind: write
+ group: orders
+ group_label: Orders
+ label: Orders
+ description: Orders, line items, returns, exchanges and claims
+ - key: read_payments
+ resource: payments
+ kind: read
+ group: orders
+ group_label: Orders
+ label: Payments
+ description: Order payments and payment capture
+ - key: write_payments
+ resource: payments
+ kind: write
+ group: orders
+ group_label: Orders
+ label: Payments
+ description: Order payments and payment capture
+ - key: read_fulfillments
+ resource: fulfillments
+ kind: read
+ group: orders
+ group_label: Orders
label: Fulfillments
description: Pack, ship and track order fulfillments
- key: write_fulfillments
@@ -29842,6 +32189,115 @@ paths:
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -30046,7 +32502,7 @@ paths:
data:
- id: variant_UkLWZg9DAJ
product_id: prod_UkLWZg9DAJ
- sku: SKU-215
+ sku: SKU-234
options_text: ''
track_inventory: true
media_count: 0
@@ -30101,11 +32557,11 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1596804
+ product_name: Product 1746804
delivery_profile_id: fp_UkLWZg9DAJ
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-216
+ sku: SKU-235
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -30140,11 +32596,11 @@ paths:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
- name: size-55
+ name: size-59
label: S
position: 1
color_code:
- option_type_name: foo-size-64
+ option_type_name: foo-size-69
option_type_label: Size
image_url:
metadata: {}
@@ -30172,7 +32628,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1596804
+ product_name: Product 1746804
delivery_profile_id: fp_UkLWZg9DAJ
meta:
page: 1
@@ -30318,7 +32774,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1601771
+ product_name: Product 1751771
delivery_profile_id: fp_UkLWZg9DAJ
'422':
description: validation error
@@ -30330,7 +32786,7 @@ paths:
message: SKU has already been taken
details:
sku:
- - value: SKU-220
+ - value: SKU-239
code: taken
message: has already been taken
specific: false
@@ -30500,7 +32956,7 @@ paths:
example:
id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-222
+ sku: SKU-241
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -30535,11 +32991,11 @@ paths:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
- name: size-58
+ name: size-62
label: S
position: 1
color_code:
- option_type_name: foo-size-67
+ option_type_name: foo-size-72
option_type_label: Size
image_url:
metadata: {}
@@ -30567,7 +33023,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1624025
+ product_name: Product 1774025
delivery_profile_id: fp_UkLWZg9DAJ
'404':
description: variant not found
@@ -30675,11 +33131,11 @@ paths:
option_values:
- id: optval_UkLWZg9DAJ
option_type_id: opt_UkLWZg9DAJ
- name: size-60
+ name: size-64
label: S
position: 1
color_code:
- option_type_name: foo-size-69
+ option_type_name: foo-size-74
option_type_label: Size
image_url:
metadata: {}
@@ -30707,7 +33163,7 @@ paths:
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1645672
+ product_name: Product 1795672
delivery_profile_id: fp_UkLWZg9DAJ
requestBody:
content:
@@ -30850,6 +33306,322 @@ paths:
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `carton_package_type_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `carton_weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `cartons_per_pallet` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `cost_currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `cost_price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `country_of_origin` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `deleted_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `depth` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `height` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `hs_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `minimum_order_quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `order_multiple` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `product_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `purchase_unit` | One of `unit`, `carton` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `sku` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `track_inventory` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `units_per_carton` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `weight` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `width` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[option_values_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
+ | `prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
+ | `prices_price_list_` | `catalog_id`, `created_at`, `ends_at`, `id`, `match_policy`, `name`, `position`, `starts_at`, `status`, `updated_at` |
+ | `product_` | `available_on`, `created_at`, `description`, `discontinue_on`, `id`, `name`, `price`, `seller_id`, `slug`, `status`, `updated_at` |
+ | `product_categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
+ | `product_channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `product_collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
+ | `product_labels_` | `created_at`, `id`, `name`, `updated_at` |
+ | `product_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
+ | `product_product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
+ | `product_product_type_` | `created_at`, `id`, `name`, `updated_at` |
+ | `product_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `product_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `product_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: variant_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-248
+ options_text: ''
+ track_inventory: true
+ media_count: 0
+ preorder_ships_at:
+ thumbnail_url:
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ preorder: false
+ weight: 0.0
+ height:
+ width:
+ depth:
+ weight_unit: lb
+ dimensions_unit: in
+ minimum_order_quantity:
+ order_multiple:
+ purchase_unit:
+ units_per_carton:
+ price:
+ id: price_UkLWZg9DAJ
+ currency: USD
+ amount: '19.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ original_price:
+ seller_id:
+ option_values: []
+ external_references: {}
+ metadata: {}
+ position: 1
+ cost_currency: USD
+ barcode:
+ backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
+ carton_weight:
+ cartons_per_pallet:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ cost_price: '17.00'
+ preorderable: false
+ tax_category_id:
+ carton_package_type_id:
+ units_per_pallet:
+ available_stock: 0
+ reserved_quantity: 0
+ total_on_hand: 0
+ product_name: Product 1813647
+ delivery_profile_id: fp_UkLWZg9DAJ
+ - id: variant_gbHJdmfrXB
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-249
+ options_text: 'Size: S'
+ track_inventory: true
+ media_count: 0
+ preorder_ships_at:
+ thumbnail_url:
+ purchasable: true
+ in_stock: false
+ backorderable: true
+ preorder: false
+ weight: 138.91
+ height: 145.43
+ width: 8.97
+ depth: 6.25
+ weight_unit: lb
+ dimensions_unit: in
+ minimum_order_quantity:
+ order_multiple:
+ purchase_unit:
+ units_per_carton:
+ price:
+ id: price_gbHJdmfrXB
+ currency: USD
+ amount: '19.99'
+ compare_at_amount:
+ price_list_id:
+ min_quantity: 1
+ variant_id: variant_gbHJdmfrXB
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ original_price:
+ seller_id:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-66
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-76
+ option_type_label: Size
+ image_url:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ metadata: {}
+ position: 2
+ cost_currency: USD
+ barcode:
+ backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
+ carton_weight:
+ cartons_per_pallet:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ cost_price: '17.00'
+ preorderable: false
+ tax_category_id:
+ carton_package_type_id:
+ units_per_pallet:
+ available_stock: 0
+ reserved_quantity: 0
+ total_on_hand: 0
+ product_name: Product 1813647
+ delivery_profile_id: fp_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
+ 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
@@ -33499,19 +36271,961 @@ paths:
deprecated: false
replaced_by:
meta:
- count: 251
- "/api/v3/admin/catalogs":
+ count: 251
+ "/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.
+
+ **Required scope:** `read_products` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: catalogs } = await client.catalogs.list({ active_eq: true })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /catalogs -d '{"active_eq":true}'
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: cat_UkLWZg9DAJ
+ name: Wholesale
+ description:
+ active: true
+ position: 1
+ metadata: {}
+ minimum_order_quantity:
+ order_multiple:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ products_count: 0
+ pricing_strategy: base
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **Required scope:** `write_products` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // The catalog and the price list it charges through are written together, so
+ // standing up an agreement never means visiting the price-lists page.
+ const catalog = await client.catalogs.create({
+ name: 'VIP Assortment',
+ price_list: { price_adjustment_percentage: '-15.0' },
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /catalogs -d '{"name":"VIP Assortment","price_list":{"price_adjustment_percentage":"-15.0"}}'
+ 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:
+ example:
+ id: cat_gbHJdmfrXB
+ name: VIP Assortment
+ description:
+ active: false
+ position: 2
+ metadata: {}
+ minimum_order_quantity:
+ order_multiple:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ products_count: 0
+ pricing_strategy: base
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: VIP Assortment
+ active:
+ type: boolean
+ example: true
+ 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
+ example: "-15.0"
+ adjust_compare_at:
+ type: boolean
+ example: false
+ 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.
+
+ **Required scope:** `write_products` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // A company assignment covers the node and its whole subtree.
+ const assignment = await client.catalogs.assign('cat_86Rf07xd4z', {
+ assignable_type: 'company',
+ assignable_id: 'comp_86Rf07xd4z',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /catalogs/{id}/assign -d '{"assignable_type":"company","assignable_id":"comp_86Rf07xd4z"}'
+ 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:
+ example:
+ id: cata_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ catalog_id: cat_UkLWZg9DAJ
+ assignable_type: company
+ assignable_id: comp_UkLWZg9DAJ
+ assignable_name: Acme Corp 1
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ assignable_type:
+ type: string
+ enum:
+ - customer_group
+ - company
+ example: company
+ assignable_id:
+ type: string
+ example: comp_86Rf07xd4z
+ 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
+ carries no order.
+
+ `expand=catalog_price` adds what a buyer on this agreement pays for
+ each row and where the amount comes from: `explicit` (an amount
+ entered on the catalog's own price list), `automatic` (that list's
+ percentage applied to the shop price) or `base` (the shop price
+ itself — this agreement does not price the product).
+
+
+ **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.
+ example: catalog_price
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
+ | `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
+ | `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
+ | `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` |
+ | `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
+ | `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
+ | `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+ | `labels_` | `created_at`, `id`, `name`, `updated_at` |
+ | `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
+ | `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
+ | `product_type_` | `created_at`, `id`, `name`, `updated_at` |
+ | `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `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` |
+ | `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
+ | `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
+ | `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 12159
+ thumbnail_url:
+ catalog_variants:
+ - id: variant_UkLWZg9DAJ
+ label:
+ sku: SKU-1
+ currency: USD
+ source: automatic
+ break_count: 0
+ amount: '80.00'
+ tiers: []
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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:
+ example:
+ added_count: 1
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ product_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - prod_abc123
+ 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.
+
+ **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:
+ example:
+ removed_count: 1
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ product_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - prod_abc123
+ required:
+ - product_ids
+ "/api/v3/admin/catalogs/{catalog_id}/order_minimums":
get:
- summary: List catalogs
+ 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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: com_UkLWZg9DAJ
+ currency: USD
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '500.00'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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:
+ example:
+ id: com_UkLWZg9DAJ
+ currency: USD
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '500.00'
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Amount must be greater than 0
+ details:
+ amount:
+ - value: 0
+ count: 0
+ code: greater_than
+ message: must be greater than 0
+ specific: false
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ currency:
+ type: string
+ example: USD
+ amount:
+ type: string
+ example: '500.00'
+ 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.
+
+ **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:
+ example:
+ id: com_UkLWZg9DAJ
+ currency: USD
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '750.00'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ amount:
+ type: string
+ example: '750.00'
+ delete:
+ summary: Delete a catalog order minimum
tags:
- Catalogs
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.
+ Lifts the threshold for one currency, so orders in it may come to any total.
- **Required scope:** `read_products` (for API-key authentication).
+ **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`.
+
+ **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
+ example: 48
+ order_multiple:
+ type: integer
+ nullable: true
+ example: 24
+ 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
+ assortment and paying its prices. Refused for a catalog nobody is
+ assigned to, since activating it would reach no buyer — a channel's
+ default catalog is reached through the channel instead, so it needs
+ no assignment.
+
+
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -33523,10 +37237,123 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: catalogs } = await client.catalogs.list({ active_eq: true })
+ // Puts the agreement into effect. Refused for a catalog nobody is assigned
+ // to, which would reach no buyer.
+ const catalog = await client.catalogs.activate('cat_xxx')
- lang: bash
label: Spree CLI
- source: spree api get /catalogs -d '{"active_eq":true}'
+ source: spree api patch /catalogs/{id}/activate -d '{ ... }'
+ 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:
+ example:
+ id: cat_UkLWZg9DAJ
+ name: Wholesale
+ description:
+ active: true
+ position: 1
+ metadata: {}
+ minimum_order_quantity:
+ order_multiple:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ products_count: 0
+ pricing_strategy: base
+ 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,
+ commercial terms, its price list — survives, so activating again
+ resumes exactly what was there.
+
+
+ **Required scope:** `write_products` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Takes it out of effect; its assignments, terms and prices survive.
+ const catalog = await client.catalogs.deactivate('cat_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /catalogs/{id}/deactivate -d '{ ... }'
+ 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:
+ example:
+ id: cat_UkLWZg9DAJ
+ name: Wholesale
+ description:
+ active: false
+ position: 1
+ metadata: {}
+ minimum_order_quantity:
+ order_multiple:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ products_count: 0
+ pricing_strategy: base
+ 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.
+
+ **Required scope:** `read_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -33536,6 +37363,7 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- name: q[search]
@@ -33544,6 +37372,25 @@ paths:
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
@@ -33562,83 +37409,276 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
- | `active` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `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` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `active`, `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
+ **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: Catalog
+ table: Collection
sortable:
- - active
+ - automatic
- created_at
- id
- name
+ - permalink
- position
+ - products_count
+ - sort_order
- updated_at
responses:
'200':
- description: catalogs found
+ description: collections found
+ content:
+ application/json:
+ example:
+ data:
+ - id: coll_UkLWZg9DAJ
+ name: Summer Sale
+ permalink: summer-sale
+ position: 1
+ sort_order: manual
+ meta_title:
+ meta_description:
+ meta_keywords:
+ products_count: 0
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ automatic: false
+ rules_match_policy: all
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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`.
+
+ **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:
+ example:
+ id: coll_gbHJdmfrXB
+ name: On Sale
+ permalink: on-sale
+ position: 2
+ sort_order: manual
+ meta_title:
+ meta_description:
+ meta_keywords:
+ products_count: 0
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ automatic: true
+ rules_match_policy: any
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Collection"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: On Sale
+ automatic:
+ type: boolean
+ example: true
+ rules_match_policy:
+ type: string
+ enum:
+ - all
+ - any
+ example: all
+ sort_order:
+ type: string
+ example: manual
+ 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
+ example: crule_abc123
+ type:
+ type: string
+ example: tag
+ value:
+ type: string
+ example: summer
+ match_policy:
+ type: string
+ example: contains
+ 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.
+
+ **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:
+ example:
+ id: coll_UkLWZg9DAJ
+ name: Summer Sale
+ permalink: summer-sale
+ position: 1
+ sort_order: manual
+ meta_title:
+ meta_description:
+ meta_keywords:
+ products_count: 0
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ automatic: false
+ rules_match_policy: all
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Collection"
+ '404':
+ description: collection not found
content:
application/json:
example:
- data:
- - id: cat_UkLWZg9DAJ
- name: Wholesale
- description:
- active: true
- position: 1
- metadata: {}
- minimum_order_quantity:
- order_multiple:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- products_count: 0
- pricing_strategy: base
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- post:
- summary: Create a catalog
+ error:
+ code: record_not_found
+ message: Collection not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a collection
tags:
- - Catalogs
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.
- // The catalog and the price list it charges through are written together, so
- // standing up an agreement never means visiting the price-lists page.
- const catalog = await client.catalogs.create({
- name: 'VIP Assortment',
- price_list: { price_adjustment_percentage: '-15.0' },
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /catalogs -d '{"name":"VIP Assortment","price_list":{"price_adjustment_percentage":"-15.0"}}'
+ **Required scope:** `write_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -33648,39 +37688,41 @@ paths:
- 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:
- '201':
- description: catalog created
+ '200':
+ description: collection updated
content:
application/json:
example:
- id: cat_gbHJdmfrXB
- name: VIP Assortment
- description:
- active: false
- position: 2
+ id: coll_UkLWZg9DAJ
+ name: Winter Sale
+ permalink: summer-sale
+ position: 1
+ sort_order: manual
+ meta_title:
+ meta_description:
+ meta_keywords:
+ products_count: 0
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ automatic: false
+ rules_match_policy: all
metadata: {}
- minimum_order_quantity:
- order_multiple:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- products_count: 0
- pricing_strategy: base
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
+ schema:
+ "$ref": "#/components/schemas/Collection"
requestBody:
content:
application/json:
@@ -33689,59 +37731,54 @@ paths:
properties:
name:
type: string
- example: VIP Assortment
- active:
+ example: Winter Sale
+ 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
- example: true
- 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
- example: "-15.0"
- adjust_compare_at:
- type: boolean
- example: false
- required:
- - name
- "/api/v3/admin/catalogs/{id}/assign":
- post:
- summary: Assign a catalog to an audience
+ 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:
- - Catalogs
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Shows the catalog to an audience. A company assignment covers the node and its whole subtree.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Deletes a collection.
- // A company assignment covers the node and its whole subtree.
- const assignment = await client.catalogs.assign('cat_86Rf07xd4z', {
- assignable_type: 'company',
- assignable_id: 'comp_86Rf07xd4z',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /catalogs/{id}/assign -d '{"assignable_type":"company","assignable_id":"comp_86Rf07xd4z"}'
+ **Required scope:** `write_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -33751,63 +37788,30 @@ paths:
- 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:
- '201':
- description: catalog assigned
- content:
- application/json:
- example:
- id: cata_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- catalog_id: cat_UkLWZg9DAJ
- assignable_type: company
- assignable_id: comp_UkLWZg9DAJ
- assignable_name: Acme Corp 1
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- assignable_type:
- type: string
- enum:
- - customer_group
- - company
- example: company
- assignable_id:
- type: string
- example: comp_86Rf07xd4z
- required:
- - assignable_type
- - assignable_id
- "/api/v3/admin/catalogs/{catalog_id}/products":
+ '204':
+ description: collection deleted
+ "/api/v3/admin/collections/{collection_id}/products":
get:
- summary: List catalog products
+ summary: List collection products
tags:
- - Catalogs
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- The catalog's curated assortment, listed by product name — membership
- carries no order.
-
- `expand=catalog_price` adds what a buyer on this agreement pays for
- each row and where the amount comes from: `explicit` (an amount
- entered on the catalog's own price list), `automatic` (that list's
- percentage applied to the shop price) or `base` (the shop price
- itself — this agreement does not price the product).
-
+ Products curated in the collection, ordered by their membership position.
- **Required scope:** `read_products` (for API-key authentication).
+ **Required scope:** `read_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -33817,11 +37821,13 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: catalog_id
+ - name: collection_id
in: path
required: true
+ description: Collection ID
schema:
type: string
- name: q[search]
@@ -33923,14 +37929,6 @@ paths:
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.
- example: catalog_price
- schema:
- type: string
- name: q
in: query
required: false
@@ -34009,31 +38007,19 @@ paths:
- updated_at
responses:
'200':
- description: products found, with what the agreement charges
+ description: products found
content:
application/json:
example:
- data:
- - id: prod_UkLWZg9DAJ
- name: Product 12159
- thumbnail_url:
- catalog_variants:
- - id: variant_UkLWZg9DAJ
- label:
- sku: SKU-1
- currency: USD
- source: automatic
- break_count: 0
- amount: '80.00'
- tiers: []
+ data: []
meta:
page: 1
limit: 25
- count: 1
+ count: 0
pages: 1
- from: 1
- to: 1
- in: 1
+ from: 0
+ to: 0
+ in: 0
previous:
next:
schema:
@@ -34042,198 +38028,23 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/CatalogProduct"
+ "$ref": "#/components/schemas/Product"
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.
-
- **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:
- example:
- added_count: 1
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- product_ids:
- type: array
- items:
- type: string
- example:
- - prod_abc123
- 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.
-
- **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:
- example:
- removed_count: 1
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- product_ids:
- type: array
- items:
- type: string
- example:
- - prod_abc123
- 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.
-
- **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
-
- Filter 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).
-
- | Attribute | Kind | Predicates |
- |---|---|---|
- | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
-
- **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:
- example:
- data:
- - id: com_UkLWZg9DAJ
- currency: USD
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- amount: '500.00'
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- post:
- summary: Create a catalog order minimum
+ summary: Add products to a collection
tags:
- - Catalogs
+ - Collections
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.
+ Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -34243,66 +38054,47 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: catalog_id
+ - name: collection_id
in: path
required: true
- schema:
- type: string
- responses:
- '201':
- description: order minimum created
- content:
- application/json:
- example:
- id: com_UkLWZg9DAJ
- currency: USD
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- amount: '500.00'
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Amount must be greater than 0
- details:
- amount:
- - value: 0
- count: 0
- code: greater_than
- message: must be greater than 0
- specific: false
+ description: Collection ID
+ schema:
+ type: string
+ responses:
+ '201':
+ description: products added
+ content:
+ application/json:
+ example:
+ added_count: 1
requestBody:
content:
application/json:
schema:
type: object
properties:
- currency:
- type: string
- example: USD
- amount:
- type: string
- example: '500.00'
+ product_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - prod_abc123
required:
- - currency
- - amount
- "/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":
- patch:
- summary: Update a catalog order minimum
+ - product_ids
+ delete:
+ summary: Remove products from a collection
tags:
- - Catalogs
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Restates one currency's threshold.
+ Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -34312,49 +38104,48 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: catalog_id
- in: path
- required: true
- schema:
- type: string
- - name: id
+ - name: collection_id
in: path
required: true
+ description: Collection ID
schema:
type: string
responses:
'200':
- description: order minimum updated
+ description: products removed
content:
application/json:
example:
- id: com_UkLWZg9DAJ
- currency: USD
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- amount: '750.00'
+ removed_count: 1
requestBody:
content:
application/json:
schema:
type: object
properties:
- amount:
- type: string
- example: '750.00'
- delete:
- summary: Delete a catalog order minimum
+ product_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - prod_abc123
+ required:
+ - product_ids
+ "/api/v3/admin/collections/{collection_id}/products/{id}/reposition":
+ patch:
+ summary: Reposition a collection product
tags:
- - Catalogs
+ - Collections
security:
- api_key: []
bearer_auth: []
description: |-
- Lifts the threshold for one currency, so orders in it may come to any total.
+ Moves a product to a new index among the collection's products.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -34364,33 +38155,47 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: catalog_id
+ - 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: order minimum deleted
- "/api/v3/admin/catalogs/{catalog_id}/quantity_rules":
- put:
- summary: Set catalog quantity rules
+ 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:
- - Catalogs
+ - Collections
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`.
+ 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`.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `read_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -34402,58 +38207,60 @@ paths:
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:
+ '200':
+ description: types found
+ content:
+ application/json:
+ example:
+ data:
+ - type: sale
+ label: On sale
+ description: Products currently discounted below their compare-at
+ price
+ schema:
type: object
- properties:
- minimum_order_quantity:
- type: integer
- nullable: true
- example: 48
- order_multiple:
- type: integer
- nullable: true
- example: 24
- required:
- - terms
- "/api/v3/admin/catalogs/{id}/activate":
- parameters:
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Activate a catalog
+ properties: {}
+ additionalProperties: false
+ - type: available_on
+ label: Recently published
+ description: Products published within the last N days
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ - type: tag
+ label: Tag
+ description: Products carrying a matching tag
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ "/api/v3/admin/commission_lines":
+ get:
+ summary: List commission lines
tags:
- - Catalogs
+ - Commission Lines
security:
- api_key: []
bearer_auth: []
description: |-
- Puts the agreement into effect: its audience starts seeing its
- assortment and paying its prices. Refused for a catalog nobody is
- assigned to, since activating it would reach no buyer — a channel's
- default catalog is reached through the channel instead, so it needs
- no assignment.
+ What each sale actually earned the marketplace, frozen when the order
+ was placed. A later change to a commission rate never reaches these.
+
+ `amount` is the fee charged to the seller and `tax_amount` is the VAT on
+ that fee — the marketplace's own service to the seller, a supply
+ separate from the sale itself, which is why the two are not folded
+ together. `total` is their sum.
+
+ One line per commissioned item, plus one per delivery when the rate that
+ applied charges shipping too — read `line_item_id` and `fulfillment_id`
+ to tell them apart.
+
+ Read-only: correcting a charge is a reversal, not an edit.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `read_commissions` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -34465,12 +38272,12 @@ paths:
secretKey: 'sk_xxx',
})
- // Puts the agreement into effect. Refused for a catalog nobody is assigned
- // to, which would reach no buyer.
- const catalog = await client.catalogs.activate('cat_xxx')
+ // `amount` is the fee and `tax_amount` is the VAT charged on that fee — two
+ // separate supplies, which is why they are not folded together.
+ const { data: commissionLines } = await client.commissionLines.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
- source: spree api patch /catalogs/{id}/activate -d '{ ... }'
+ source: spree api get /commission_lines -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -34480,65 +38287,162 @@ paths:
- 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `rate` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[commission_rate_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `commission_rate_` | `code`, `created_at`, `enabled`, `id`, `include_shipping`, `kind`, `name`, `position`, `tax_inclusive`, `updated_at`, `value` |
+ | `commission_rate_commission_rules_` | `created_at`, `id`, `updated_at` |
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+
+ </Accordion>
+
+ **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: catalog activated
+ description: commission lines found
content:
application/json:
example:
- id: cat_UkLWZg9DAJ
- name: Wholesale
- description:
- active: true
- position: 1
- metadata: {}
- minimum_order_quantity:
- order_multiple:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- products_count: 0
- pricing_strategy: base
+ data:
+ - id: cline_UkLWZg9DAJ
+ kind: percentage
+ currency: USD
+ taxability_reason:
+ country_code:
+ state_code:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ rate: '10'
+ tax_rate: '0'
+ amount: '10.00'
+ tax_amount: '2.10'
+ total: '12.10'
+ order_id: or_UkLWZg9DAJ
+ seller_id: sel_UkLWZg9DAJ
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ commission_rate_id:
+ seller_name: Sparks Audio
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Catalog"
- "/api/v3/admin/catalogs/{id}/deactivate":
+ 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:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ 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
- patch:
- summary: Deactivate a catalog
+ get:
+ summary: Get a commission line
tags:
- - Catalogs
+ - Commission Lines
security:
- api_key: []
bearer_auth: []
- description: |-
- Takes the agreement out of effect. Everything it holds — assignments,
- commercial terms, its price list — survives, so activating again
- resumes exactly what was there.
-
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // Takes it out of effect; its assignments, terms and prices survive.
- const catalog = await client.catalogs.deactivate('cat_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api patch /catalogs/{id}/deactivate -d '{ ... }'
+ description: "**Required scope:** `read_commissions` (for API-key authentication)."
parameters:
- name: x-spree-api-key
in: header
@@ -34552,36 +38456,80 @@ paths:
type: string
responses:
'200':
- description: catalog deactivated
+ description: commission line found
content:
application/json:
example:
- id: cat_UkLWZg9DAJ
- name: Wholesale
- description:
- active: false
- position: 1
- metadata: {}
- minimum_order_quantity:
- order_multiple:
+ id: cline_UkLWZg9DAJ
+ kind: percentage
+ currency: USD
+ taxability_reason:
+ country_code:
+ state_code:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- products_count: 0
- pricing_strategy: base
+ rate: '10'
+ tax_rate: '0'
+ amount: '10.00'
+ tax_amount: '2.10'
+ total: '12.10'
+ order_id: or_UkLWZg9DAJ
+ seller_id: sel_UkLWZg9DAJ
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ commission_rate_id:
+ seller_name: Sparks Audio
schema:
- "$ref": "#/components/schemas/Catalog"
- "/api/v3/admin/collections":
+ "$ref": "#/components/schemas/CommissionLine"
+ '404':
+ description: commission line not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Commission line not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/commission_rates":
get:
- summary: List collections
+ summary: List commission rates
tags:
- - Collections
+ - Commission Rates
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a paginated list of the store's collections.
+ What the marketplace charges its sellers.
- **Required scope:** `read_collections` (for API-key authentication).
+ Rates are returned in resolution order: the list is walked top-down and
+ the first rate whose targeting matches the sale wins, so the order you
+ see is the precedence. Move a rate with `position` on update.
+
+ A rate carrying no rules matches every sale — `global` says so — which
+ is how a marketplace expresses a single default. Because resolution
+ stops at the first match, a global rate makes everything below it
+ unreachable, so it belongs at the bottom.
+
+
+ **Required scope:** `read_commissions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Rates come back with their targeting attached. A rate holding no rules
+ // applies to every sale.
+ const { data: commissionRates } = await client.commissionRates.list({ page: 1, limit: 25 })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /commission_rates -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -34612,13 +38560,6 @@ paths:
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
@@ -34629,6 +38570,12 @@ paths:
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
@@ -34637,54 +38584,68 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
- | `automatic` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `include_shipping` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `permalink` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `products_count` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `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` |
+ | `tax_inclusive` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `value` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at`. Prefix a field with `-` to sort descending.
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[commission_rules_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `commission_rules_` | `created_at`, `id`, `updated_at` |
+
+ </Accordion>
+
+ **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: Collection
+ table: CommissionRate
sortable:
- - automatic
+ - code
- created_at
+ - enabled
- id
+ - include_shipping
+ - kind
- name
- - permalink
- position
- - products_count
- - sort_order
+ - tax_inclusive
- updated_at
+ - value
responses:
'200':
- description: collections found
+ description: commission rates found
content:
application/json:
- example:
- data:
- - id: coll_UkLWZg9DAJ
- name: Summer Sale
- permalink: summer-sale
+ example:
+ data:
+ - id: crate_UkLWZg9DAJ
+ name: Standard
+ code:
+ enabled: true
position: 1
- sort_order: manual
- meta_title:
- meta_description:
- meta_keywords:
- products_count: 0
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- automatic: false
- rules_match_policy: all
+ kind: percentage
+ tax_inclusive: false
+ include_shipping: false
metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ value: '10'
+ commission_tax_rate:
+ amounts: {}
+ bounds: {}
+ global: true
+ rules: []
meta:
page: 1
limit: 25
@@ -34701,23 +38662,71 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/Collection"
+ "$ref": "#/components/schemas/CommissionRate"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a collection
+ summary: Create a commission rate
tags:
- - Collections
+ - Commission Rates
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`.
+ Sets what the marketplace charges, and which sales it applies to.
- **Required scope:** `write_collections` (for API-key authentication).
+ `rules` is the rate's whole targeting, sent inline. Every rule has to
+ hold, and a rule naming several records means any of them — so
+ "(Cameras OR Audio) AND that seller" is a category rule holding two ids
+ beside a seller rule holding one. Send no rules to charge every sale.
+
+ Rule kinds come from `GET /commission_rates/rule_types`, which also
+ describes the configuration each one takes. A marketplace that adds its
+ own kind sees it there without this endpoint changing.
+
+ `commission_tax_rate` is VAT on the commission itself — the
+ marketplace's own service to the seller, a separate supply from the
+ sale. Leave it null to let the store's tax engine answer for wherever
+ the seller's business sits.
+
+
+ **Required scope:** `write_commissions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Charges this seller 12.5% of every sale, with VAT on the commission itself
+ // left to your tax settings. The rate lands at the top of the list, so it
+ // resolves ahead of anything more general already there.
+ const commissionRate = await client.commissionRates.create({
+ name: 'Audio sellers',
+ kind: 'percentage',
+ value: '12.5',
+ rules: [{ type: 'seller_rule', preferences: { seller_ids: ['sel_a1b2c3'] } }],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /commission_rates -d '{"name":"Audio sellers","kind":"percentage","value":"12.5","rules":[{"type":"seller_rule","preferences":{"seller_ids":["sel_a1b2c3"]}}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -34727,47 +38736,46 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: collection created
+ description: commission rate created
content:
application/json:
example:
- id: coll_gbHJdmfrXB
- name: On Sale
- permalink: on-sale
- position: 2
- sort_order: manual
- meta_title:
- meta_description:
- meta_keywords:
- products_count: 0
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- automatic: true
- rules_match_policy: any
+ id: crate_gbHJdmfrXB
+ name: Audio sellers
+ code:
+ enabled: true
+ position: 1
+ kind: percentage
+ tax_inclusive: false
+ include_shipping: false
metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ value: '12.5'
+ commission_tax_rate:
+ amounts: {}
+ bounds: {}
+ global: true
+ rules: []
schema:
- "$ref": "#/components/schemas/Collection"
+ "$ref": "#/components/schemas/CommissionRate"
'422':
- description: validation error
+ description: validation failed
content:
application/json:
example:
error:
code: validation_error
- message: Name can't be blank
+ message: needs a flat fee amount in at least one currency
details:
- name:
- - code: blank
- message: can't be blank
+ base:
+ - code: commission_rate_needs_an_amount
+ message: needs a flat fee amount in at least one currency
specific: false
schema:
"$ref": "#/components/schemas/ErrorResponse"
@@ -34776,65 +38784,126 @@ paths:
application/json:
schema:
type: object
+ required:
+ - name
+ - kind
+ - value
properties:
name:
type: string
- example: On Sale
- automatic:
+ example: Audio sellers
+ code:
+ type: string
+ example: audio
+ nullable: true
+ description: Your own identifier for this rate; unique per store.
+ enabled:
type: boolean
example: true
- rules_match_policy:
+ position:
+ type: integer
+ example: 1
+ 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:
- - all
- - any
- example: all
- sort_order:
- type: string
- example: manual
- permalink:
- type: string
- description:
- type: string
- meta_title:
- type: string
- meta_description:
+ - percentage
+ - fixed
+ example: percentage
+ value:
type: string
- meta_keywords:
+ example: '12.5'
+ description: A percentage (10 = 10%) or a flat amount, per `kind`.
+ amounts:
+ type: object
+ additionalProperties:
+ type: string
+ example:
+ USD: '2.50'
+ EUR: '2.00'
+ 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
+ example: false
+ 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
+ example: false
+ 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
+ example:
+ USD:
+ min_amount: '1.0'
+ max_amount: '50.0'
+ 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
+ example: '0.21'
+ nullable: true
+ description: A fraction, not a percentage. Null asks the tax engine.
rules:
type: array
- description: Full desired rule set. Entries with an id update, id-less
- entries create, omitted rules are removed.
+ description: The full targeting; what you send replaces what the
+ rate holds.
items:
type: object
properties:
id:
type: string
- example: crule_abc123
+ description: Present for an existing rule; omit to create
+ one.
type:
type: string
- example: tag
- value:
- type: string
- example: summer
- match_policy:
- type: string
- example: contains
- required:
- - name
- "/api/v3/admin/collections/{id}":
+ example: seller_rule
+ description: A kind from /commission_rates/rule_types.
+ preferences:
+ type: object
+ example:
+ seller_ids:
+ - sel_a1b2c3
+ 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: Get a collection
+ summary: List the commission rule kinds
tags:
- - Collections
+ - Commission Rates
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single collection by ID, including its rules.
+ Every rule kind a rate can be narrowed by, with the schema describing
+ the configuration it takes — so a client builds its editor from what
+ this marketplace has rather than a list hardcoded to match core's.
- **Required scope:** `read_collections` (for API-key authentication).
+ `association_fields` names any catalog-scale reference a kind keeps
+ outside its preferences, so an editor knows to render a picker for it.
+
+
+ **Required scope:** `read_commissions` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -34844,69 +38913,223 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: id
- in: path
+ responses:
+ '200':
+ description: subject types found
+ content:
+ application/json:
+ example:
+ data:
+ - type: seller_rule
+ name: Seller
+ description: Charges this rate only when the seller is one of the
+ selected
+ schema:
+ 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
+ association_fields:
+ - seller_ids
+ - type: category_rule
+ name: Category
+ description: Charges this rate only for products in the selected
+ categories, and anything filed beneath them
+ schema:
+ 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
+ association_fields:
+ - category_ids
+ - type: product_rule
+ name: Product
+ description: Charges this rate only for the selected products
+ schema:
+ type: object
+ properties: {}
+ additionalProperties: false
+ association_fields:
+ - product_ids
+ - type: item_total_rule
+ name: Sale value
+ description: Charges this rate only on sales within a value range
+ schema:
+ type: object
+ properties:
+ min_amount:
+ type:
+ - string
+ - 'null'
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ max_amount:
+ type:
+ - string
+ - 'null'
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ additionalProperties: false
+ association_fields: []
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ type:
+ type: string
+ example: seller_rule
+ name:
+ type: string
+ example: Seller
+ 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)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const commissionRate = await client.commissionRates.get('crate_a1b2c3')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /commission_rates/{id}
+ parameters:
+ - name: x-spree-api-key
+ in: header
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).
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: collection found
+ description: commission rate found
content:
application/json:
example:
- id: coll_UkLWZg9DAJ
- name: Summer Sale
- permalink: summer-sale
+ id: crate_UkLWZg9DAJ
+ name: Standard
+ code:
+ enabled: true
position: 1
- sort_order: manual
- meta_title:
- meta_description:
- meta_keywords:
- products_count: 0
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- automatic: false
- rules_match_policy: all
+ kind: percentage
+ tax_inclusive: false
+ include_shipping: false
metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ value: '10'
+ commission_tax_rate:
+ amounts: {}
+ bounds: {}
+ global: true
+ rules: []
schema:
- "$ref": "#/components/schemas/Collection"
+ "$ref": "#/components/schemas/CommissionRate"
'404':
- description: collection not found
+ description: commission rate not found
content:
application/json:
example:
error:
code: record_not_found
- message: Collection not found
+ message: Commission rate not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a collection
+ summary: Update a commission rate
tags:
- - Collections
+ - Commission Rates
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.
+ Editing a rate changes what the next sale is charged, never what a past
+ one was: commission lines keep their own snapshot of the rate that
+ applied.
- **Required scope:** `write_collections` (for API-key authentication).
+
+ **Required scope:** `write_commissions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // `rules` is the rate's whole targeting — what you send replaces what it holds.
+ // `position` moves the rate: 1 is tried first, and the first match wins.
+ //
+ // Every rule has to hold, so this charges 15% only on camera sales worth 50 or
+ // more. Call ruleTypes() for the kinds this marketplace has.
+ const commissionRate = await client.commissionRates.update('crate_a1b2c3', {
+ value: '15',
+ position: 1,
+ rules: [
+ { type: 'category_rule', preferences: { category_ids: ['ctg_d4e5f6'] } },
+ { type: 'item_total_rule', preferences: { min_amount: '50' } },
+ ],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /commission_rates/{id} -d '{"value":"15","position":1,"rules":[{"type":"category_rule","preferences":{"category_ids":["ctg_d4e5f6"]}},{"type":"item_total_rule","preferences":{"min_amount":"50"}}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -34916,41 +39139,34 @@ paths:
- 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
+ description: commission rate updated
content:
application/json:
example:
- id: coll_UkLWZg9DAJ
- name: Winter Sale
- permalink: summer-sale
+ id: crate_UkLWZg9DAJ
+ name: Standard
+ code:
+ enabled: true
position: 1
- sort_order: manual
- meta_title:
- meta_description:
- meta_keywords:
- products_count: 0
- description: ''
- description_html: ''
- image_url:
- square_image_url:
- automatic: false
- rules_match_policy: all
+ kind: percentage
+ tax_inclusive: false
+ include_shipping: false
metadata: {}
+ deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ value: '15'
+ commission_tax_rate:
+ amounts: {}
+ bounds: {}
+ global: true
+ rules: []
schema:
- "$ref": "#/components/schemas/Collection"
+ "$ref": "#/components/schemas/CommissionRate"
requestBody:
content:
application/json:
@@ -34959,32 +39175,18 @@ paths:
properties:
name:
type: string
- example: Winter Sale
- permalink:
- type: string
- description:
- type: string
- meta_title:
- type: string
- meta_description:
- type: string
- meta_keywords:
- type: string
- sort_order:
- type: string
- automatic:
+ example: Standard
+ enabled:
type: boolean
- rules_match_policy:
- type: string
- enum:
- - all
- - any
+ example: true
position:
type: integer
- description: Reorders the collection within the flat list (acts_as_list)
+ example: 1
+ value:
+ type: string
+ example: '15.0'
rules:
type: array
- description: Full desired rule set (see create).
items:
type: object
properties:
@@ -34992,21 +39194,40 @@ paths:
type: string
type:
type: string
- value:
- type: string
- match_policy:
- type: string
+ example: category_rule
+ preferences:
+ type: object
+ example:
+ category_ids:
+ - ctg_a1b2c3
+ product_ids:
+ type: array
+ items:
+ type: string
delete:
- summary: Delete a collection
+ summary: Delete a commission rate
tags:
- - Collections
+ - Commission Rates
security:
- api_key: []
bearer_auth: []
- description: |-
- Deletes a collection.
+ description: "**Required scope:** `write_commissions` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
- **Required scope:** `write_collections` (for API-key authentication).
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Commission already charged is unaffected — the lines keep their own snapshot.
+ await client.commissionRates.delete('crate_a1b2c3')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /commission_rates/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -35016,30 +39237,23 @@ paths:
- 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":
+ description: commission rate deleted
+ "/api/v3/admin/companies/{company_id}/addresses":
get:
- summary: List collection products
+ summary: List company addresses
tags:
- - Collections
+ - Companies
security:
- api_key: []
bearer_auth: []
description: |-
- Products curated in the collection, ordered by their membership position.
+ Returns the business's addresses: its sites, billing address and delivery points.
- **Required scope:** `read_collections` (for API-key authentication).
+ **Required scope:** `read_customers` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -35049,114 +39263,422 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: collection_id
+ - name: company_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][]
+ - name: q
in: query
required: false
+ style: deepObject
+ explode: true
schema:
- type: array
- items:
- type: string
- description: Applies `in_categories` to the given value.
- - name: q[in_category]
- in: query
- required: false
+ type: object
+ additionalProperties: true
+ description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
+ Filters above for the list.
+ x-mint:
+ content: |-
+ ## Filters
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `address1` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `address2` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `city` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `company` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `country_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `first_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `last_name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `phone` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `postal_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `state_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: addr_UkLWZg9DAJ
+ label: Head office
+ first_name:
+ last_name:
+ full_name: ''
+ address1: 9 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ latitude:
+ longitude:
+ customer_id:
+ owner_id: comp_UkLWZg9DAJ
+ owner_type: company
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **Required scope:** `read_customers` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
schema:
type: string
- description: Applies `in_category` to the given value.
- - name: q[in_collection]
- in: query
- required: false
+ - name: Authorization
+ in: header
+ required: true
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
+ - name: company_id
+ in: path
+ required: true
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]
+ - name: q
in: query
required: false
+ style: deepObject
+ explode: true
schema:
- type: string
- description: Applies `search_by_name` to the given value.
- - name: q[with_option_value_ids][]
+ type: object
+ additionalProperties: true
+ description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
+ Filters above for the list.
+ x-mint:
+ content: |-
+ ## Filters
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: cinv_UkLWZg9DAJ
+ expires_at: '2026-02-14T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ status: pending
+ accepted_at:
+ revoked_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **Required scope:** `read_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: members } = await client.companies.memberships.list('comp_86Rf07xd4z')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /companies/{company_id}/memberships
+ parameters:
+ - name: q
in: query
required: false
+ style: deepObject
+ explode: true
schema:
- type: array
- items:
- type: string
- description: Applies `with_option_value_ids` to the given value.
+ type: object
+ additionalProperties: true
+ description: Attribute filters, as `q[<attribute>_<predicate>]=value`. See
+ Filters above for the list.
+ x-mint:
+ content: |-
+ ## Filters
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: cmem_UkLWZg9DAJ
+ company_id: comp_UkLWZg9DAJ
+ customer_id: cust_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
+ membership immediately (a `cmem_…` id); an unknown email becomes an invitation
+ (a `cinv_…` id) and the invite email goes out.
+
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // An existing customer becomes a member immediately; an unknown email
+ // becomes an invitation (check the returned id prefix: cmem_ vs cinv_).
+ const member = await client.companies.memberships.create('comp_86Rf07xd4z', {
+ customer_email: '[email protected]',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /companies/{company_id}/memberships -d '{"customer_email":"[email protected]"}'
+ parameters: []
+ responses:
+ '201':
+ description: member added
+ content:
+ application/json:
+ example:
+ id: cmem_UkLWZg9DAJ
+ company_id: comp_UkLWZg9DAJ
+ customer_id: cust_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ 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
+ exempts a sale: a verified certificate stops counting once its expiry date passes, so the status
+ alone does not answer it.
+
+
+ **Required scope:** `read_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: certificates } =
+ await client.companies.taxExemptionCertificates.list('comp_UkLWZg9DAJ')
+
+ // `active` — not `status` — answers whether one exempts a sale: a verified
+ // certificate stops counting once its expiry date passes.
+ const applying = certificates.filter((certificate) => certificate.active)
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /companies/{company_id}/tax_exemption_certificates
+ parameters:
- name: q
in: query
required: false
@@ -35171,324 +39693,433 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `available_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `certificate_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `description` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `discontinue_on` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `price` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `slug` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `status` | One of `draft`, `active`, `archived`, `proposed`, `rejected` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `reason_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `pending`, `verified`, `expired`, `revoked` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[categories_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `categories_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
- | `categories_parent_` | `automatic`, `children_count`, `created_at`, `depth`, `id`, `name`, `parent_id`, `permalink`, `position`, `pretty_name`, `products_count`, `updated_at` |
- | `channels_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
- | `collections_` | `automatic`, `created_at`, `id`, `name`, `permalink`, `position`, `products_count`, `sort_order`, `updated_at` |
- | `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` |
- | `default_variant_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
- | `default_variant_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
- | `default_variant_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `default_variant_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
- | `labels_` | `created_at`, `id`, `name`, `updated_at` |
- | `option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
- | `product_categories_` | `category_id`, `created_at`, `id`, `position`, `product_id`, `updated_at` |
- | `product_type_` | `created_at`, `id`, `name`, `updated_at` |
- | `product_type_option_types_` | `created_at`, `id`, `kind`, `label`, `name`, `position`, `updated_at` |
- | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `store_` | `created_at`, `id`, `name`, `updated_at` |
- | `tags_` | `created_at`, `id`, `name`, `updated_at` |
- | `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` |
- | `variants_option_values_` | `created_at`, `id`, `label`, `name`, `position`, `updated_at` |
- | `variants_prices_` | `amount`, `compare_at_amount`, `created_at`, `currency`, `id`, `min_quantity`, `price_list_id`, `updated_at`, `variant_id` |
- | `variants_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
- | `variants_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
-
- </Accordion>
-
- **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.
+ **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: Product
+ table: TaxExemptionCertificate
sortable:
- - available_on
+ - certificate_number
- created_at
- - description
- - discontinue_on
+ - expires_at
- id
- - name
- - price
- - seller_id
- - slug
+ - reason_code
- status
- updated_at
responses:
'200':
- description: products found
+ description: certificates found
content:
application/json:
example:
- data: []
+ data:
+ - id: cert_UkLWZg9DAJ
+ certificate_number: DE-RESALE-1
+ reason_code: resale
+ status: pending
+ issuing_authority:
+ metadata: {}
+ issued_at:
+ expires_at:
+ verified_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ country_code:
+ state_code:
+ active: false
+ lapsed: false
+ can_be_deleted: true
+ document_filename:
+ document_byte_size:
+ document_url:
meta:
page: 1
limit: 25
- count: 0
+ count: 1
pages: 1
- from: 0
- to: 0
- in: 0
+ from: 1
+ to: 1
+ in: 1
previous:
next:
- 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
+ summary: Create a tax exemption certificate
tags:
- - Collections
+ - Companies
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.
+ Records exemption evidence against a business. Certificates start `pending` and exempt nothing
+ until verified.
- **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
+ `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`.
+
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ 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',
+ },
+ })
+
+ const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {
+ certificate_number: 'DE-RESALE-7',
+ reason_code: 'resale',
+ country_code: 'DE',
+ document: signed_id,
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /companies/{company_id}/tax_exemption_certificates
+ -d '{ ... }'
+ parameters: []
responses:
'201':
- description: products added
+ description: certificate created
content:
application/json:
example:
- added_count: 1
+ id: cert_gbHJdmfrXB
+ certificate_number: DE-RESALE-7
+ reason_code: resale
+ status: pending
+ issuing_authority:
+ metadata: {}
+ issued_at:
+ expires_at:
+ verified_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ country_code: DE
+ state_code:
+ active: false
+ lapsed: false
+ can_be_deleted: true
+ document_filename: resale.pdf
+ document_byte_size: 20
+ document_url: "/api/v3/admin/companies/comp_UkLWZg9DAJ/tax_exemption_certificates/cert_gbHJdmfrXB/download"
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Certificate number can't be blank
+ details:
+ certificate_number:
+ - code: blank
+ message: can't be blank
+ specific: false
requestBody:
content:
application/json:
schema:
type: object
properties:
- product_ids:
- type: array
- items:
- type: string
- example:
- - prod_abc123
+ certificate_number:
+ type: string
+ example: DE-RESALE-7
+ reason_code:
+ type: string
+ description: Becomes the tax provider's entity use code.
+ example: resale
+ country_code:
+ type: string
+ nullable: true
+ example: DE
+ state_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:
+ type: string
+ description: ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.
+ example: eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed
required:
- - product_ids
- delete:
- summary: Remove products from a collection
+ - 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:
- - Collections
+ - Companies
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.
+ Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending
+ certificate can be accepted — re-accepting a revoked one would restore evidence that was
+ deliberately withdrawn. An installation that checks numbers against a registry, or requires a
+ second approval, can refuse here, and the refusal is returned as a validation error.
- **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
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Accepting is what makes a certificate exempt sales. Only a pending one can
+ // be accepted, and an installation's own checks can refuse here.
+ const certificate = await client.companies.taxExemptionCertificates.verify(
+ 'comp_UkLWZg9DAJ',
+ 'cert_UkLWZg9DAJ',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /companies/{company_id}/tax_exemption_certificates/{id}/verify
+ -d '{ ... }'
responses:
'200':
- description: products removed
+ description: certificate verified
content:
application/json:
example:
- removed_count: 1
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- product_ids:
- type: array
- items:
- type: string
- example:
- - prod_abc123
- required:
- - product_ids
- "/api/v3/admin/collections/{collection_id}/products/{id}/reposition":
+ id: cert_UkLWZg9DAJ
+ certificate_number: DE-RESALE-1
+ reason_code: resale
+ status: verified
+ issuing_authority:
+ metadata: {}
+ issued_at:
+ expires_at:
+ verified_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ country_code:
+ state_code:
+ active: true
+ lapsed: false
+ can_be_deleted: false
+ document_filename:
+ document_byte_size:
+ document_url:
+ "/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: Reposition a collection product
+ summary: Revoke a tax exemption certificate
tags:
- - Collections
+ - Companies
security:
- api_key: []
bearer_auth: []
description: |-
- Moves a product to a new index among the collection's products.
+ Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.
- **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
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // A verified certificate cannot be deleted — how a sale was taxed has to stay
+ // explainable — so revoking is the way out.
+ const certificate = await client.companies.taxExemptionCertificates.revoke(
+ 'comp_UkLWZg9DAJ',
+ 'cert_UkLWZg9DAJ',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /companies/{company_id}/tax_exemption_certificates/{id}/revoke
+ -d '{ ... }'
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":
+ '200':
+ description: certificate revoked
+ content:
+ application/json:
+ example:
+ id: cert_gbHJdmfrXB
+ certificate_number: CERT-1
+ reason_code: resale
+ status: revoked
+ issuing_authority:
+ metadata: {}
+ issued_at:
+ expires_at:
+ verified_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ country_code:
+ state_code:
+ active: false
+ lapsed: false
+ can_be_deleted: true
+ document_filename:
+ document_byte_size:
+ document_url:
+ "/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: List available collection rule types
+ summary: Download a certificate document
tags:
- - Collections
+ - Companies
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`.
+ Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so
+ the same credentials apply to every read of a confidential document. Requires only read access.
- **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
+
+ **Required scope:** `read_customers` (for API-key authentication).
responses:
'200':
- description: types found
+ description: document streamed
+ content:
+ application/json: {}
+ '422':
+ description: no document attached
content:
application/json:
example:
- data:
- - type: sale
- label: On sale
- description: Products currently discounted below their compare-at
- price
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: available_on
- label: Recently published
- description: Products published within the last N days
- schema:
- type: object
- properties: {}
- additionalProperties: false
- - type: tag
- label: Tag
- description: Products carrying a matching tag
- schema:
- type: object
- properties: {}
- additionalProperties: false
- "/api/v3/admin/commission_lines":
+ error:
+ code: validation_error
+ message: Certificate has no attached document
+ "/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 commission lines
+ summary: List company tax registrations
tags:
- - Commission Lines
+ - Companies
security:
- api_key: []
bearer_auth: []
description: |-
- What each sale actually earned the marketplace, frozen when the order
- was placed. A later change to a commission rate never reaches these.
-
- `amount` is the fee charged to the seller and `tax_amount` is the VAT on
- that fee — the marketplace's own service to the seller, a supply
- separate from the sale itself, which is why the two are not folded
- together. `total` is their sum.
-
- One line per commissioned item, plus one per delivery when the rate that
- applied charges shipping too — read `line_item_id` and `fulfillment_id`
- to tell them apart.
-
- Read-only: correcting a charge is a reversal, not an edit.
+ Returns the business's tax registrations, one per kind. A business registration takes precedence
+ over the buyer's own when a sale is for that business, because the invoice is addressed to the
+ entity rather than the person who placed the order.
- **Required scope:** `read_commissions` (for API-key authentication).
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -35500,36 +40131,11 @@ paths:
secretKey: 'sk_xxx',
})
- // `amount` is the fee and `tax_amount` is the VAT charged on that fee — two
- // separate supplies, which is why they are not folded together.
- const { data: commissionLines } = await client.commissionLines.list({ page: 1, limit: 25 })
+ const { data: registrations } = await client.companies.taxIdentifiers.list('comp_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /commission_lines -d '{"page":1,"limit":25}'
+ source: spree api get /companies/{company_id}/tax_identifiers
parameters:
- - name: x-spree-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
@@ -35540,89 +40146,45 @@ paths:
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
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `rate` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `tax_amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `total` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[commission_rate_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `commission_rate_` | `code`, `created_at`, `enabled`, `id`, `include_shipping`, `kind`, `name`, `position`, `tax_inclusive`, `updated_at`, `value` |
- | `commission_rate_commission_rules_` | `created_at`, `id`, `updated_at` |
- | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
-
- </Accordion>
-
- **Sort by:** `amount`, `created_at`, `currency`, `id`, `kind`, `order_id`, `rate`, `tax_amount`, `total`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: CommissionLine
+ table: TaxIdentifier
sortable:
- - amount
- created_at
- - currency
- id
- - kind
- - order_id
- - rate
- - tax_amount
- - total
- updated_at
responses:
'200':
- description: commission lines found
+ description: registrations found
content:
application/json:
example:
data:
- - id: cline_UkLWZg9DAJ
- kind: percentage
- currency: USD
- taxability_reason:
- country_code:
- state_code:
+ - id: txi_UkLWZg9DAJ
+ kind: eu_vat
+ value: DE100000008
+ validation_status:
+ validation_evidence:
+ source:
+ validated_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- rate: '10'
- tax_rate: '0'
- amount: '10.00'
- tax_amount: '2.10'
- total: '12.10'
- order_id: or_UkLWZg9DAJ
- seller_id: sel_UkLWZg9DAJ
- line_item_id: li_UkLWZg9DAJ
- fulfillment_id:
- commission_rate_id:
- seller_name: Sparks Audio
+ validatable: false
+ customer_id:
+ cart_id:
+ order_id:
meta:
page: 1
limit: 25
@@ -35633,114 +40195,168 @@ paths:
in: 1
previous:
next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/CommissionLine"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- '401':
- description: unauthorized
+ 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
+ the background where a validator is installed for the kind; a stock installation registers none,
+ leaving the status unattempted.
+
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // A business registration outranks the buyer's own when the sale is for that business.
+ const registration = await client.companies.taxIdentifiers.create('comp_UkLWZg9DAJ', {
+ kind: 'eu_vat',
+ value: 'DE123456789',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /companies/{company_id}/tax_identifiers -d '{"kind":"eu_vat","value":"DE123456789"}'
+ parameters: []
+ responses:
+ '201':
+ description: registration created
+ content:
+ application/json:
+ example:
+ id: txi_gbHJdmfrXB
+ kind: gb_vat
+ value: GB123456789
+ validation_status:
+ validation_evidence:
+ source:
+ validated_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ validatable: false
+ customer_id:
+ cart_id:
+ order_id:
+ '422':
+ description: invalid request
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/commission_lines/{id}":
+ code: validation_error
+ message: Registration type has already been taken
+ details:
+ kind:
+ - value: eu_vat
+ code: taken
+ message: has already been taken
+ specific: false
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ kind:
+ type: string
+ description: The regime the number belongs to.
+ example: gb_vat
+ value:
+ type: string
+ example: GB123456789
+ 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
- description: Commission line ID
required: true
schema:
type: string
- get:
- summary: Get a commission line
+ post:
+ summary: Re-check a company tax registration
tags:
- - Commission Lines
+ - Companies
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
+ description: |-
+ Asks the registry again. Manual because a registry answers only "valid now" — a number verified
+ last year may have been deregistered since — and because a check that came back unavailable
+ cannot otherwise be retried without editing the number.
+
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // A registry answers only "valid now", so a number verified last year may
+ // have been deregistered since. The check is queued; poll for the verdict.
+ const registration = await client.companies.taxIdentifiers.validate(
+ 'comp_UkLWZg9DAJ',
+ 'txi_UkLWZg9DAJ',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /companies/{company_id}/tax_identifiers/{id}/validate
+ -d '{ ... }'
responses:
- '200':
- description: commission line found
- content:
- application/json:
- example:
- id: cline_UkLWZg9DAJ
- kind: percentage
- currency: USD
- taxability_reason:
- country_code:
- state_code:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- rate: '10'
- tax_rate: '0'
- amount: '10.00'
- tax_amount: '2.10'
- total: '12.10'
- order_id: or_UkLWZg9DAJ
- seller_id: sel_UkLWZg9DAJ
- line_item_id: li_UkLWZg9DAJ
- fulfillment_id:
- commission_rate_id:
- seller_name: Sparks Audio
- schema:
- "$ref": "#/components/schemas/CommissionLine"
- '404':
- description: commission line not found
+ '422':
+ description: no validator installed for this kind
content:
application/json:
example:
error:
- code: record_not_found
- message: Commission line not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/commission_rates":
+ code: tax_id_not_validatable
+ message: No registry validator is installed for tax identifier kind
+ 'eu_vat'
+ "/api/v3/admin/companies":
get:
- summary: List commission rates
+ summary: List companies
tags:
- - Commission Rates
+ - Companies
security:
- api_key: []
bearer_auth: []
description: |-
- What the marketplace charges its sellers.
-
- Rates are returned in resolution order: the list is walked top-down and
- the first rate whose targeting matches the sale wins, so the order you
- see is the precedence. Move a rate with `position` on update.
-
- A rate carrying no rules matches every sale — `global` says so — which
- is how a marketplace expresses a single default. Because resolution
- stops at the first match, a global rate makes everything below it
- unreachable, so it belongs at the bottom.
-
+ Returns the business customers of the current store.
- **Required scope:** `read_commissions` (for API-key authentication).
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -35752,12 +40368,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Rates come back with their targeting attached. A rate holding no rules
- // applies to every sale.
- const { data: commissionRates } = await client.commissionRates.list({ page: 1, limit: 25 })
+ const { data: companies } = await client.companies.list({ search: 'Acme' })
- lang: bash
label: Spree CLI
- source: spree api get /commission_rates -d '{"page":1,"limit":25}'
+ source: spree api get /companies -d '{"search":"Acme"}'
parameters:
- name: x-spree-api-key
in: header
@@ -35767,7 +40381,6 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- name: q[search]
@@ -35776,18 +40389,6 @@ paths:
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
@@ -35798,12 +40399,6 @@ paths:
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
@@ -35812,68 +40407,62 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
- | `code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `enabled` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `include_shipping` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
- | `kind` | One of `percentage`, `fixed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `kind` | One of `company`, `division` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `tax_inclusive` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `po_number_required` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `value` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
<Accordion title="Filters through associations">
- Prefix an associated record's attribute with the association, as in `q[commission_rules_id_eq]`. The same predicates apply.
+ Prefix an associated record's attribute with the association, as in `q[children_id_eq]`. The same predicates apply.
| Prefix | Attributes |
|---|---|
- | `commission_rules_` | `created_at`, `id`, `updated_at` |
+ | `children_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |
+ | `children_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |
+ | `children_memberships_` | `created_at`, `id`, `updated_at` |
+ | `external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |
+ | `memberships_` | `created_at`, `id`, `updated_at` |
+ | `parent_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |
+ | `parent_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |
+ | `parent_memberships_` | `created_at`, `id`, `updated_at` |
</Accordion>
- **Sort by:** `code`, `created_at`, `enabled`, `id`, `include_shipping`, `kind`, `name`, `position`, `tax_inclusive`, `updated_at`, `value`. Prefix a field with `-` to sort descending.
+ **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: CommissionRate
+ table: Company
sortable:
- - code
- created_at
- - enabled
- id
- - include_shipping
- kind
- name
- - position
- - tax_inclusive
+ - parent_id
+ - po_number_required
- updated_at
- - value
responses:
'200':
- description: commission rates found
+ description: companies found
content:
application/json:
example:
data:
- - id: crate_UkLWZg9DAJ
- name: Standard
- code:
- enabled: true
- position: 1
- kind: percentage
- tax_inclusive: false
- include_shipping: false
- metadata: {}
- deleted_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- value: '10'
- commission_tax_rate:
- amounts: {}
- bounds: {}
- global: true
- rules: []
+ - id: comp_UkLWZg9DAJ
+ name: Acme Industrial
+ kind: company
+ po_number_required: false
+ parent_id:
+ ancestors: []
+ external_references:
+ erp: ACME-1
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ children_count: 0
+ members_count: 0
meta:
page: 1
limit: 25
@@ -35884,54 +40473,17 @@ paths:
in: 1
previous:
next:
- 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:
- example:
- error:
- code: authentication_required
- message: Authentication required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a commission rate
+ summary: Create a company
tags:
- - Commission Rates
+ - Companies
security:
- api_key: []
bearer_auth: []
description: |-
- Sets what the marketplace charges, and which sales it applies to.
-
- `rules` is the rate's whole targeting, sent inline. Every rule has to
- hold, and a rule naming several records means any of them — so
- "(Cameras OR Audio) AND that seller" is a category rule holding two ids
- beside a seller rule holding one. Send no rules to charge every sale.
-
- Rule kinds come from `GET /commission_rates/rule_types`, which also
- describes the configuration each one takes. A marketplace that adds its
- own kind sees it there without this endpoint changing.
-
- `commission_tax_rate` is VAT on the commission itself — the
- marketplace's own service to the seller, a separate supply from the
- sale. Leave it null to let the store's tax engine answer for wherever
- the seller's business sits.
-
+ 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.
- **Required scope:** `write_commissions` (for API-key authentication).
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -35943,18 +40495,13 @@ paths:
secretKey: 'sk_xxx',
})
- // Charges this seller 12.5% of every sale, with VAT on the commission itself
- // left to your tax settings. The rate lands at the top of the list, so it
- // resolves ahead of anything more general already there.
- const commissionRate = await client.commissionRates.create({
- name: 'Audio sellers',
- kind: 'percentage',
- value: '12.5',
- rules: [{ type: 'seller_rule', preferences: { seller_ids: ['sel_a1b2c3'] } }],
+ const company = await client.companies.create({
+ name: 'Globex Corporation',
+ external_references: { erp: 'GLBX-42' },
})
- lang: bash
label: Spree CLI
- source: spree api post /commission_rates -d '{"name":"Audio sellers","kind":"percentage","value":"12.5","rules":[{"type":"seller_rule","preferences":{"seller_ids":["sel_a1b2c3"]}}]}'
+ source: spree api post /companies -d '{"name":"Globex Corporation","external_references":{"erp":"GLBX-42"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -35968,293 +40515,99 @@ paths:
type: string
responses:
'201':
- description: commission rate created
+ description: company created
content:
application/json:
example:
- id: crate_gbHJdmfrXB
- name: Audio sellers
- code:
- enabled: true
- position: 1
- kind: percentage
- tax_inclusive: false
- include_shipping: false
+ id: comp_gbHJdmfrXB
+ name: Globex Corporation
+ kind: company
+ po_number_required: false
+ parent_id:
+ ancestors: []
+ external_references:
+ erp: GLBX-42
metadata: {}
- deleted_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- value: '12.5'
- commission_tax_rate:
- amounts: {}
- bounds: {}
- global: true
- rules: []
- schema:
- "$ref": "#/components/schemas/CommissionRate"
+ children_count: 0
+ members_count: 0
'422':
- description: validation failed
+ description: invalid request
content:
application/json:
example:
error:
code: validation_error
- message: needs a flat fee amount in at least one currency
+ message: Name can't be blank
details:
- base:
- - code: commission_rate_needs_an_amount
- message: needs a flat fee amount in at least one currency
+ name:
+ - code: blank
+ message: can't be blank
specific: false
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
- required:
- - name
- - kind
- - value
properties:
name:
type: string
- example: Audio sellers
- code:
- type: string
- example: audio
- nullable: true
- description: Your own identifier for this rate; unique per store.
- enabled:
- type: boolean
- example: true
- position:
- type: integer
- example: 1
- 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.
+ example: Globex Corporation
kind:
type: string
enum:
- - percentage
- - fixed
- example: percentage
- value:
- type: string
- example: '12.5'
- description: A percentage (10 = 10%) or a flat amount, per `kind`.
- amounts:
- type: object
- additionalProperties:
- type: string
- example:
- USD: '2.50'
- EUR: '2.00'
- 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
- example: false
- 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
- example: false
- 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
- example:
- USD:
- min_amount: '1.0'
- max_amount: '50.0'
- 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:
+ - company
+ - division
+ description: company = legal entity (may hold tax registrations),
+ division = organizational unit. Roots must be company.
+ example: company
+ parent_id:
type: string
- example: '0.21'
nullable: true
- description: A fraction, not a percentage. Null asks the tax engine.
- rules:
+ description: The parent node. Omit for a root.
+ example: comp_86Rf07xd4z
+ external_references:
type: array
- description: The full targeting; what you send replaces what the
- rate holds.
+ 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:
- id:
+ system:
type: string
- description: Present for an existing rule; omit to create
- one.
- type:
+ example: erp
+ external_id:
type: string
- example: seller_rule
- description: A kind from /commission_rates/rule_types.
- preferences:
- type: object
- example:
- seller_ids:
- - sel_a1b2c3
- 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":
+ example: GLBX-42
+ required:
+ - system
+ - external_id
+ required:
+ - name
+ "/api/v3/admin/custom_field_definitions/resource_types":
get:
- summary: List the commission rule kinds
+ summary: List what custom fields can be attached to
tags:
- - Commission Rates
+ - Custom Field Definitions
security:
- api_key: []
bearer_auth: []
description: |-
- Every rule kind a rate can be narrowed by, with the schema describing
- the configuration it takes — so a client builds its editor from what
- this marketplace has rather than a list hardcoded to match core's.
+ The resources a definition can describe, from the server's own
+ registry (`Spree.custom_fields.enabled_resources`).
- `association_fields` names any catalog-scale reference a kind keeps
- outside its preferences, so an editor knows to render a picker for it.
+ Read this rather than carrying a list: a resource an extension
+ registers appears here without a client release, and a `resource_type`
+ that is not listed is refused on create.
+ `resource_type` is the value to send; `name` is what a merchant calls
+ it — send the value back verbatim rather than deriving it from the name.
- **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:
- example:
- data:
- - type: seller_rule
- name: Seller
- description: Charges this rate only when the seller is one of the
- selected
- schema:
- 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
- association_fields:
- - seller_ids
- - type: category_rule
- name: Category
- description: Charges this rate only for products in the selected
- categories, and anything filed beneath them
- schema:
- 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
- association_fields:
- - category_ids
- - type: product_rule
- name: Product
- description: Charges this rate only for the selected products
- schema:
- type: object
- properties: {}
- additionalProperties: false
- association_fields:
- - product_ids
- - type: item_total_rule
- name: Sale value
- description: Charges this rate only on sales within a value range
- schema:
- type: object
- properties:
- min_amount:
- type:
- - string
- - 'null'
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- max_amount:
- type:
- - string
- - 'null'
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- additionalProperties: false
- association_fields: []
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- type: object
- properties:
- type:
- type: string
- example: seller_rule
- name:
- type: string
- example: Seller
- 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)."
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -36266,10 +40619,12 @@ paths:
secretKey: 'sk_xxx',
})
- const commissionRate = await client.commissionRates.get('crate_a1b2c3')
+ // What a definition can be attached to. Comes from the server's registry, so
+ // a resource an extension adds shows up here without a client release.
+ const { data: resourceTypes } = await client.customFieldDefinitions.resourceTypes()
- lang: bash
label: Spree CLI
- source: spree api get /commission_rates/{id}
+ source: spree api get /custom_field_definitions/resource_types
parameters:
- name: x-spree-api-key
in: header
@@ -36283,81 +40638,99 @@ paths:
type: string
responses:
'200':
- description: commission rate found
- content:
- application/json:
- example:
- id: crate_UkLWZg9DAJ
- name: Standard
- code:
- enabled: true
- position: 1
- kind: percentage
- tax_inclusive: false
- include_shipping: false
- metadata: {}
- deleted_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- value: '10'
- commission_tax_rate:
- amounts: {}
- bounds: {}
- global: true
- rules: []
- schema:
- "$ref": "#/components/schemas/CommissionRate"
- '404':
- description: commission rate not found
+ description: resource types found
content:
application/json:
example:
- error:
- code: record_not_found
- message: Commission rate not found
+ data:
+ - resource_type: address
+ name: Addresses
+ - resource_type: category
+ name: Categories
+ - resource_type: claim
+ name: Claims
+ - resource_type: collection
+ name: Collections
+ - resource_type: credit_card
+ name: Credit Cards
+ - resource_type: customer
+ name: Customers
+ - resource_type: delivery_method
+ name: Delivery Methods
+ - resource_type: exchange
+ name: Exchanges
+ - resource_type: fulfillment
+ name: Fulfillments
+ - resource_type: gift_card
+ name: Gift Cards
+ - resource_type: line_item
+ name: Line Items
+ - resource_type: media
+ name: Media
+ - resource_type: newsletter_subscriber
+ name: Newsletter Subscribers
+ - resource_type: option_type
+ name: Option Types
+ - resource_type: option_value
+ name: Option Values
+ - resource_type: order
+ name: Orders
+ - resource_type: payment_method
+ name: Payment Methods
+ - resource_type: payment_source
+ name: Payment Sources
+ - resource_type: payment
+ name: Payments
+ - resource_type: product_type
+ name: Product Types
+ - resource_type: product
+ name: Products
+ - resource_type: promotion
+ name: Promotions
+ - resource_type: refund
+ name: Refunds
+ - resource_type: return
+ name: Returns
+ - resource_type: seller
+ name: Sellers
+ - resource_type: stock_level
+ name: Stock Levels
+ - resource_type: stock_transfer
+ name: Stock Transfers
+ - resource_type: store_credit
+ name: Store Credits
+ - resource_type: store
+ name: Stores
+ - resource_type: tax_rate
+ name: Tax Rates
+ - resource_type: variant
+ name: Variants
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
- one was: commission lines keep their own snapshot of the rate that
- applied.
-
-
- **Required scope:** `write_commissions` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // `rules` is the rate's whole targeting — what you send replaces what it holds.
- // `position` moves the rate: 1 is tried first, and the first match wins.
- //
- // Every rule has to hold, so this charges 15% only on camera sales worth 50 or
- // more. Call ruleTypes() for the kinds this marketplace has.
- const commissionRate = await client.commissionRates.update('crate_a1b2c3', {
- value: '15',
- position: 1,
- rules: [
- { type: 'category_rule', preferences: { category_ids: ['ctg_d4e5f6'] } },
- { type: 'item_total_rule', preferences: { min_amount: '50' } },
- ],
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /commission_rates/{id} -d '{"value":"15","position":1,"rules":[{"type":"category_rule","preferences":{"category_ids":["ctg_d4e5f6"]}},{"type":"item_total_rule","preferences":{"min_amount":"50"}}]}'
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ resource_type:
+ type: string
+ example: seller
+ name:
+ type: string
+ example: Sellers
+ "/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.
+
+ **Required scope:** `read_collections` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -36369,93 +40742,104 @@ paths:
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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: commission rate updated
+ description: custom fields found
content:
application/json:
example:
- id: crate_UkLWZg9DAJ
- name: Standard
- code:
- enabled: true
- position: 1
- kind: percentage
- tax_inclusive: false
- include_shipping: false
- metadata: {}
- deleted_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- value: '15'
- commission_tax_rate:
- amounts: {}
- bounds: {}
- global: true
- rules: []
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/CommissionRate"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Standard
- enabled:
- type: boolean
- example: true
- position:
- type: integer
- example: 1
- value:
- type: string
- example: '15.0'
- rules:
- type: array
- items:
- type: object
- properties:
- id:
- type: string
- type:
- type: string
- example: category_rule
- preferences:
- type: object
- example:
- category_ids:
- - ctg_a1b2c3
- product_ids:
- type: array
- items:
- type: string
- delete:
- summary: Delete a commission rate
+ 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:
- - Commission Rates
+ - Sellers
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_commissions` (for API-key authentication)."
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ description: |-
+ Returns the seller's custom field values.
- // Commission already charged is unaffected — the lines keep their own snapshot.
- await client.commissionRates.delete('crate_a1b2c3')
- - lang: bash
- label: Spree CLI
- source: spree api delete /commission_rates/{id}
+ **Required scope:** `read_sellers` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -36467,37 +40851,104 @@ paths:
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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
- '204':
- description: commission rate deleted
- "/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
+ '200':
+ description: custom fields found
+ content:
+ application/json:
+ example:
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ field_type: short_text
+ key: custom.title
+ value: wool
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ storefront_visible: true
+ custom_field_definition_id: cfdef_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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 company members
+ summary: List delivery profiles
tags:
- - Companies
+ - Delivery
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.
+ Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.
- **Required scope:** `read_customers` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -36509,11 +40960,27 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: members } = await client.companies.memberships.list('comp_86Rf07xd4z')
+ const profiles = await client.deliveryProfiles.list()
- lang: bash
label: Spree CLI
- source: spree api get /companies/{company_id}/memberships
+ source: spree api get /delivery_profiles
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
@@ -36528,34 +40995,51 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: CompanyMembership
+ table: DeliveryProfile
sortable:
- created_at
- id
+ - name
+ - position
- updated_at
responses:
'200':
- description: members found
+ description: delivery profiles found
content:
application/json:
example:
data:
- - id: cmem_UkLWZg9DAJ
- company_id: comp_UkLWZg9DAJ
- customer_id: cust_UkLWZg9DAJ
+ - id: fp_UkLWZg9DAJ
+ name: General
+ default: true
+ position: 1
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ kind: shipping
+ digital: false
+ offers_pickup: false
+ offers_shipping: false
+ stock_location_ids: []
+ origin_groups:
+ - id: og_UkLWZg9DAJ
+ name:
+ position: 1
+ stock_location_ids: []
+ products_count: 0
+ delivery_methods_count: 0
+ delivery_zones_count: 0
meta:
page: 1
limit: 25
@@ -36567,19 +41051,16 @@ paths:
previous:
next:
post:
- summary: Add a member by email
+ summary: Create a delivery profile
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- Adds a person to the node by email. An email matching an existing customer becomes a
- membership immediately (a `cmem_…` id); an unknown email becomes an invitation
- (a `cinv_…` id) and the invite email goes out.
-
+ 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.
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -36591,90 +41072,113 @@ paths:
secretKey: 'sk_xxx',
})
- // An existing customer becomes a member immediately; an unknown email
- // becomes an invitation (check the returned id prefix: cmem_ vs cinv_).
- const member = await client.companies.memberships.create('comp_86Rf07xd4z', {
- customer_email: '[email protected]',
+ const profile = await client.deliveryProfiles.create({
+ name: 'Oversized',
+ stock_location_ids: ['sloc_86Rf07xd4z'],
})
- lang: bash
label: Spree CLI
- source: spree api post /companies/{company_id}/memberships -d '{"customer_email":"[email protected]"}'
- parameters: []
+ source: spree api post /delivery_profiles -d '{"name":"Oversized","stock_location_ids":["sloc_86Rf07xd4z"]}'
+ 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: member added
+ description: delivery profile created
content:
application/json:
example:
- id: cmem_UkLWZg9DAJ
- company_id: comp_UkLWZg9DAJ
- customer_id: cust_UkLWZg9DAJ
+ id: fp_gbHJdmfrXB
+ name: Oversized 1768478400.0
+ default: false
+ position: 2
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ kind: shipping
+ digital: false
+ offers_pickup: false
+ offers_shipping: false
+ stock_location_ids: []
+ origin_groups:
+ - id: og_gbHJdmfrXB
+ name:
+ position: 1
+ stock_location_ids: []
+ products_count: 0
+ delivery_methods_count: 0
+ delivery_zones_count: 0
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - code: blank
+ message: can't be blank
+ specific: false
requestBody:
content:
application/json:
schema:
type: object
properties:
- customer_email:
+ name:
type: string
+ example: Oversized
+ kind:
+ type: string
+ example: shipping
+ 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:
- - customer_email
- "/api/v3/admin/companies/{company_id}/tax_exemption_certificates":
+ - name
+ "/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":
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
+ - name: delivery_profile_id
in: path
required: true
schema:
type: string
get:
- summary: List tax exemption certificates
+ summary: List origin groups
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a business's exemption evidence. `active` is the field that decides whether a certificate
- exempts a sale: a verified certificate stops counting once its expiry date passes, so the status
- alone does not answer it.
-
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: certificates } =
- await client.companies.taxExemptionCertificates.list('comp_UkLWZg9DAJ')
+ Returns the profile's origin groups: the sets of warehouses that each quote their own delivery rates.
- // `active` — not `status` — answers whether one exempts a sale: a verified
- // certificate stops counting once its expiry date passes.
- const applying = certificates.filter((certificate) => certificate.active)
- - lang: bash
- label: Spree CLI
- source: spree api get /companies/{company_id}/tax_exemption_certificates
+ **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
@@ -36689,83 +41193,83 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `certificate_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- | `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `reason_code` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `status` | One of `pending`, `verified`, `expired`, `revoked` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `certificate_number`, `created_at`, `expires_at`, `id`, `reason_code`, `status`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: TaxExemptionCertificate
+ table: DeliveryOriginGroup
sortable:
- - certificate_number
- created_at
- - expires_at
- id
- - reason_code
- - status
+ - name
+ - position
- updated_at
responses:
'200':
- description: certificates found
+ description: origin groups found
content:
application/json:
example:
data:
- - id: cert_UkLWZg9DAJ
- certificate_number: DE-RESALE-1
- reason_code: resale
- status: pending
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at:
+ - id: og_gbHJdmfrXB
+ name:
+ position: 1
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- company_id: comp_UkLWZg9DAJ
- country_code:
- state_code:
- active: false
- lapsed: false
- can_be_deleted: true
- document_filename:
- document_byte_size:
- document_url:
+ delivery_profile_id: fp_gbHJdmfrXB
+ stock_location_ids: []
+ delivery_zones_count: 0
+ delivery_methods_count: 0
+ - id: og_EfhxLZ9ck8
+ name: EU warehouse
+ position: 2
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivery_profile_id: fp_gbHJdmfrXB
+ stock_location_ids: []
+ delivery_zones_count: 0
+ delivery_methods_count: 0
meta:
page: 1
limit: 25
- count: 1
+ count: 2
pages: 1
from: 1
- to: 1
- in: 1
+ to: 2
+ in: 2
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/DeliveryOriginGroup"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Create a tax exemption certificate
+ summary: Create an origin group
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- Records exemption evidence against a business. Certificates start `pending` and exempt nothing
- 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`.
-
+ 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.
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -36777,139 +41281,74 @@ 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',
- },
- })
-
- const certificate = await client.companies.taxExemptionCertificates.create('comp_UkLWZg9DAJ', {
- certificate_number: 'DE-RESALE-7',
- reason_code: 'resale',
- country_code: 'DE',
- document: signed_id,
+ const originGroup = await client.deliveryProfiles.originGroups.create('fp_86Rf07xd4z', {
+ name: 'EU warehouse',
+ stock_location_ids: ['sloc_86Rf07xd4z'],
})
- lang: bash
label: Spree CLI
- source: spree api post /companies/{company_id}/tax_exemption_certificates
- -d '{ ... }'
- parameters: []
+ source: spree api post /delivery_profiles/{delivery_profile_id}/origin_groups
+ -d '{"name":"EU warehouse","stock_location_ids":["sloc_86Rf07xd4z"]}'
+ 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: certificate created
+ description: origin group created
content:
application/json:
example:
- id: cert_gbHJdmfrXB
- certificate_number: DE-RESALE-7
- reason_code: resale
- status: pending
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at:
+ id: og_EfhxLZ9ck8
+ name: EU warehouse
+ position: 2
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- company_id: comp_UkLWZg9DAJ
- country_code: DE
- state_code:
- active: false
- lapsed: false
- can_be_deleted: true
- document_filename: resale.pdf
- document_byte_size: 20
- document_url: "/api/v3/admin/companies/comp_UkLWZg9DAJ/tax_exemption_certificates/cert_gbHJdmfrXB/download"
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Certificate number can't be blank
- details:
- certificate_number:
- - code: blank
- message: can't be blank
- specific: false
+ delivery_profile_id: fp_gbHJdmfrXB
+ stock_location_ids:
+ - sloc_UkLWZg9DAJ
+ delivery_zones_count: 0
+ delivery_methods_count: 0
requestBody:
content:
application/json:
schema:
type: object
properties:
- certificate_number:
- type: string
- example: DE-RESALE-7
- reason_code:
- type: string
- description: Becomes the tax provider's entity use code.
- example: resale
- country_code:
- type: string
- nullable: true
- example: DE
- state_code:
- type: string
- nullable: true
- example: BE
- expires_at:
+ name:
type: string
- format: date-time
nullable: true
- issuing_authority:
- type: string
+ example: EU warehouse
+ position:
+ type: integer
nullable: true
- example: Finanzamt Berlin
- document:
- type: string
- description: ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.
- example: eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed
- required:
- - certificate_number
- - reason_code
- "/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":
+ stock_location_ids:
+ type: array
+ items:
+ type: string
+ description: Empty means every store location.
+ "/api/v3/admin/delivery_profiles/{id}":
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
+ summary: Update a delivery profile
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
- description: |-
- Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending
- certificate can be accepted — re-accepting a revoked one would restore evidence that was
- deliberately withdrawn. An installation that checks numbers against a registry, or requires a
- second approval, can refuse here, and the refusal is returned as a validation error.
-
-
- **Required scope:** `write_customers` (for API-key authentication).
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -36921,75 +41360,76 @@ paths:
secretKey: 'sk_xxx',
})
- // Accepting is what makes a certificate exempt sales. Only a pending one can
- // be accepted, and an installation's own checks can refuse here.
- const certificate = await client.companies.taxExemptionCertificates.verify(
- 'comp_UkLWZg9DAJ',
- 'cert_UkLWZg9DAJ',
- )
+ const profile = await client.deliveryProfiles.update('fp_86Rf07xd4z', {
+ name: 'Oversized freight',
+ stock_location_ids: [],
+ })
- lang: bash
label: Spree CLI
- source: spree api patch /companies/{company_id}/tax_exemption_certificates/{id}/verify
- -d '{ ... }'
+ source: spree api patch /delivery_profiles/{id} -d '{"name":"Oversized freight","stock_location_ids":[]}'
+ 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: certificate verified
+ description: delivery profile updated
content:
application/json:
example:
- id: cert_UkLWZg9DAJ
- certificate_number: DE-RESALE-1
- reason_code: resale
- status: verified
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at: '2026-01-15T12:00:00.000Z'
+ id: fp_gbHJdmfrXB
+ name: Bulky 1768478400.0
+ default: false
+ position: 2
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- company_id: comp_UkLWZg9DAJ
- country_code:
- state_code:
- active: true
- lapsed: false
- can_be_deleted: false
- document_filename:
- document_byte_size:
- document_url:
- "/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
+ kind: shipping
+ digital: false
+ offers_pickup: false
+ offers_shipping: false
+ stock_location_ids:
+ - sloc_UkLWZg9DAJ
+ origin_groups:
+ - id: og_gbHJdmfrXB
+ name:
+ position: 1
+ stock_location_ids:
+ - sloc_UkLWZg9DAJ
+ products_count: 0
+ delivery_methods_count: 0
+ delivery_zones_count: 0
+ 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:
- - Companies
+ - Delivery
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.
+ The default profile and profiles still referenced by products cannot be deleted.
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37001,121 +41441,36 @@ paths:
secretKey: 'sk_xxx',
})
- // A verified certificate cannot be deleted — how a sale was taxed has to stay
- // explainable — so revoking is the way out.
- const certificate = await client.companies.taxExemptionCertificates.revoke(
- 'comp_UkLWZg9DAJ',
- 'cert_UkLWZg9DAJ',
- )
+ await client.deliveryProfiles.delete('fp_86Rf07xd4z')
- lang: bash
label: Spree CLI
- source: spree api patch /companies/{company_id}/tax_exemption_certificates/{id}/revoke
- -d '{ ... }'
- responses:
- '200':
- description: certificate revoked
- content:
- application/json:
- example:
- id: cert_gbHJdmfrXB
- certificate_number: CERT-1
- reason_code: resale
- status: revoked
- issuing_authority:
- metadata: {}
- issued_at:
- expires_at:
- verified_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- company_id: comp_UkLWZg9DAJ
- country_code:
- state_code:
- active: false
- lapsed: false
- can_be_deleted: true
- document_filename:
- document_byte_size:
- document_url:
- "/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
- the same credentials apply to every read of a confidential document. Requires only read access.
-
-
- **Required scope:** `read_customers` (for API-key authentication).
+ source: spree api delete /delivery_profiles/{id}
+ 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: document streamed
- content:
- application/json: {}
- '422':
- description: no document attached
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Certificate has no attached document
- "/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
+ '204':
+ description: delivery profile deleted
+ "/api/v3/admin/delivery_methods":
get:
- summary: List company tax registrations
+ summary: List delivery methods
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the business's tax registrations, one per kind. A business registration takes precedence
- over the buyer's own when a sale is for that business, because the invoice is addressed to the
- entity rather than the person who placed the order.
-
+ Returns all delivery methods with calculator and zone configuration.
- **Required scope:** `read_customers` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37127,11 +41482,27 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: registrations } = await client.companies.taxIdentifiers.list('comp_UkLWZg9DAJ')
+ const { data: deliveryMethods } = await client.deliveryMethods.list()
- lang: bash
label: Spree CLI
- source: spree api get /companies/{company_id}/tax_identifiers
+ source: spree api get /delivery_methods
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
@@ -37146,41 +41517,81 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
+ | `available_to_sellers` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+
+ </Accordion>
+
+ **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: TaxIdentifier
+ table: DeliveryMethod
sortable:
+ - available_to_sellers
- created_at
- id
+ - name
+ - seller_id
+ - storefront_visible
- updated_at
responses:
'200':
- description: registrations found
+ description: delivery methods found
content:
application/json:
example:
data:
- - id: txi_UkLWZg9DAJ
- kind: eu_vat
- value: DE100000008
- validation_status:
- validation_evidence:
- source:
- validated_at:
+ - id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND_3
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ admin_name:
+ storefront_visible: true
+ tracking_url:
+ available_to_sellers: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- validatable: false
- customer_id:
- cart_id:
- order_id:
+ deleted_at:
+ markup_flat: '0.00'
+ markup_percent: '0'
+ seller_id:
+ seller_name:
+ services: []
+ rules: []
+ tax_category_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_origin_group_id: og_UkLWZg9DAJ
+ delivery_zone_id:
+ stock_location_ids: []
+ fulfillment_provider: manual
+ pickup_point_provider:
+ rate_provider:
+ calculator:
+ type: flat_rate
+ preferences:
+ amounts: {}
+ amount: '10.00'
+ currency: USD
meta:
page: 1
limit: 25
@@ -37192,19 +41603,16 @@ paths:
previous:
next:
post:
- summary: Create a company tax registration
+ summary: Create delivery method
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- Registers a tax number against the business. Verification against the relevant registry runs in
- the background where a validator is installed for the kind; a stock installation registers none,
- leaving the status unattempted.
-
+ Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37216,100 +41624,133 @@ paths:
secretKey: 'sk_xxx',
})
- // A business registration outranks the buyer's own when the sale is for that business.
- const registration = await client.companies.taxIdentifiers.create('comp_UkLWZg9DAJ', {
- kind: 'eu_vat',
- value: 'DE123456789',
+ const deliveryMethod = await client.deliveryMethods.create({
+ name: 'Express',
+ storefront_visible: true,
+ calculator: { type: 'flat_rate', preferences: { amount: '12.50' } },
})
- lang: bash
label: Spree CLI
- source: spree api post /companies/{company_id}/tax_identifiers -d '{"kind":"eu_vat","value":"DE123456789"}'
- parameters: []
+ source: spree api post /delivery_methods -d '{"name":"Express","storefront_visible":true,"calculator":{"type":"flat_rate","preferences":{"amount":"12.50"}}}'
+ 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: registration created
+ description: delivery method created
content:
application/json:
example:
- id: txi_gbHJdmfrXB
- kind: gb_vat
- value: GB123456789
- validation_status:
- validation_evidence:
- source:
- validated_at:
+ id: dm_UkLWZg9DAJ
+ name: Express
+ code:
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ admin_name:
+ storefront_visible: true
+ tracking_url:
+ available_to_sellers: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- validatable: false
- customer_id:
- cart_id:
- order_id:
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Registration type has already been taken
- details:
- kind:
- - value: eu_vat
- code: taken
- message: has already been taken
- specific: false
+ deleted_at:
+ markup_flat: '0.00'
+ markup_percent: '0'
+ seller_id:
+ seller_name:
+ services: []
+ rules: []
+ tax_category_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_origin_group_id: og_UkLWZg9DAJ
+ delivery_zone_id:
+ stock_location_ids: []
+ fulfillment_provider: manual
+ pickup_point_provider:
+ rate_provider:
+ calculator:
+ type: flat_rate
+ preferences:
+ amounts: {}
+ amount: '12.50'
+ currency: USD
requestBody:
content:
application/json:
schema:
type: object
properties:
- kind:
+ name:
type: string
- description: The regime the number belongs to.
- example: gb_vat
- value:
+ example: Express
+ admin_name:
type: string
- example: GB123456789
+ nullable: true
+ code:
+ type: string
+ nullable: true
+ fulfillment_provider:
+ type: string
+ nullable: true
+ example: manual
+ delivery_profile_id:
+ type: string
+ nullable: true
+ example: fp_86Rf07xd4z
+ storefront_visible:
+ type: boolean
+ example: true
+ 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
+ example: flat_rate
+ preferences:
+ type: object
+ example:
+ amount: '12.5'
+ delivery_zone_id:
+ type: string
+ nullable: true
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
+ - name
+ "/api/v3/admin/delivery_methods/calculators":
+ get:
+ summary: List delivery calculators
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- Asks the registry again. Manual because a registry answers only "valid now" — a number verified
- last year may have been deregistered since — and because a check that came back unavailable
- cannot otherwise be retried without editing the number.
-
+ Registered delivery calculator classes with preference schemas for building configuration forms.
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37321,53 +41762,176 @@ paths:
secretKey: 'sk_xxx',
})
- // A registry answers only "valid now", so a number verified last year may
- // have been deregistered since. The check is queued; poll for the verdict.
- const registration = await client.companies.taxIdentifiers.validate(
- 'comp_UkLWZg9DAJ',
- 'txi_UkLWZg9DAJ',
- )
+ const { data: calculators } = await client.deliveryMethods.calculators()
- lang: bash
label: Spree CLI
- source: spree api post /companies/{company_id}/tax_identifiers/{id}/validate
- -d '{ ... }'
+ source: spree api get /delivery_methods/calculators
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
responses:
- '422':
- description: no validator installed for this kind
+ '200':
+ description: calculators found
content:
application/json:
example:
- error:
- code: tax_id_not_validatable
- message: No registry validator is installed for tax identifier kind
- 'eu_vat'
- "/api/v3/admin/companies":
+ data:
+ - type: flat_percent_item_total
+ name: Flat Percent
+ schema:
+ type: object
+ properties:
+ flat_percent:
+ type: string
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: '0'
+ additionalProperties: false
+ - type: flat_rate
+ name: Flat rate
+ schema:
+ type: object
+ properties:
+ amounts:
+ type: object
+ propertyNames:
+ type: string
+ format: currency
+ pattern: "^[A-Z]{3}$"
+ additionalProperties:
+ type: string
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: {}
+ amount:
+ type: string
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: '0'
+ currency:
+ type: string
+ format: currency
+ pattern: "^[A-Z]{3}$"
+ additionalProperties: false
+ - type: flexi_rate
+ name: Flexible Rate per package item
+ schema:
+ 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
+ - type: per_item
+ name: Flat rate per package item
+ schema:
+ type: object
+ properties:
+ amounts:
+ type: object
+ propertyNames:
+ type: string
+ format: currency
+ pattern: "^[A-Z]{3}$"
+ additionalProperties:
+ type: string
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: {}
+ amount:
+ type: string
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: '0'
+ currency:
+ type: string
+ format: currency
+ pattern: "^[A-Z]{3}$"
+ additionalProperties: false
+ - type: price_sack
+ name: Price sack
+ schema:
+ 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
+ - type: digital_delivery
+ name: Digital Delivery
+ schema:
+ type: object
+ properties:
+ amounts:
+ type: object
+ propertyNames:
+ type: string
+ format: currency
+ pattern: "^[A-Z]{3}$"
+ additionalProperties:
+ type: string
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: {}
+ amount:
+ type: string
+ format: money
+ pattern: "^-?\\d+(\\.\\d+)?$"
+ default: '0'
+ currency:
+ type: string
+ format: currency
+ pattern: "^[A-Z]{3}$"
+ additionalProperties: false
+ "/api/v3/admin/delivery_zones":
get:
- summary: List companies
+ summary: List delivery zones
tags:
- - Companies
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the business customers of the current store.
-
- **Required scope:** `read_customers` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Returns the areas delivery methods ship to, each made of countries, states or postal code ranges.
- const { data: companies } = await client.companies.list({ search: 'Acme' })
- - lang: bash
- label: Spree CLI
- source: spree api get /companies -d '{"search":"Acme"}'
+ **Required scope:** `read_settings` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -37379,12 +41943,6 @@ paths:
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
@@ -37404,61 +41962,35 @@ paths:
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `delivery_profile_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `kind` | One of `company`, `division` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
| `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `parent_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `po_number_required` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[children_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `children_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |
- | `children_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |
- | `children_memberships_` | `created_at`, `id`, `updated_at` |
- | `external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |
- | `memberships_` | `created_at`, `id`, `updated_at` |
- | `parent_` | `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at` |
- | `parent_external_references_` | `created_at`, `external_id`, `id`, `resource_type`, `system`, `updated_at` |
- | `parent_memberships_` | `created_at`, `id`, `updated_at` |
-
- </Accordion>
-
- **Sort by:** `created_at`, `id`, `kind`, `name`, `parent_id`, `po_number_required`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `delivery_profile_id`, `id`, `name`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: Company
+ table: DeliveryZone
sortable:
- created_at
+ - delivery_profile_id
- id
- - kind
- name
- - parent_id
- - po_number_required
- updated_at
responses:
'200':
- description: companies found
+ description: delivery zones found
content:
application/json:
example:
data:
- - id: comp_UkLWZg9DAJ
- name: Acme Industrial
- kind: company
- po_number_required: false
- parent_id:
- ancestors: []
- external_references:
- erp: ACME-1
- metadata: {}
+ - id: dz_UkLWZg9DAJ
+ name: US North-East
+ description: Natus fugiat numquam perferendis sint reiciendis.
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- children_count: 0
- members_count: 0
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_origin_group_id: og_UkLWZg9DAJ
+ delivery_method_ids: []
meta:
page: 1
limit: 25
@@ -37469,17 +42001,29 @@ paths:
in: 1
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/DeliveryZone"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Create a company
+ summary: Create delivery zone
tags:
- - Companies
+ - Delivery
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.
+ Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).
- **Required scope:** `write_customers` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37491,13 +42035,16 @@ paths:
secretKey: 'sk_xxx',
})
- const company = await client.companies.create({
- name: 'Globex Corporation',
- external_references: { erp: 'GLBX-42' },
+ const deliveryZone = await client.deliveryZones.create({
+ name: 'US North-East',
+ members: [
+ { member_type: 'country', country_code: 'US' },
+ { member_type: 'postal_code', country_code: 'US', postal_code_prefix: '10' },
+ ],
})
- lang: bash
label: Spree CLI
- source: spree api post /companies -d '{"name":"Globex Corporation","external_references":{"erp":"GLBX-42"}}'
+ source: spree api post /delivery_zones -d '{"name":"US North-East","members":[{"member_type":"country","country_code":"US"},{"member_type":"postal_code","country_code":"US","postal_code_prefix":"10"}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -37509,38 +42056,49 @@ paths:
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: company created
+ description: delivery zone created
content:
application/json:
example:
- id: comp_gbHJdmfrXB
- name: Globex Corporation
- kind: company
- po_number_required: false
- parent_id:
- ancestors: []
- external_references:
- erp: GLBX-42
- metadata: {}
+ id: dz_UkLWZg9DAJ
+ name: US North-East
+ description:
+ members:
+ - id: dzm_UkLWZg9DAJ
+ member_type: country
+ country_code: US
+ state_code:
+ postal_code_prefix:
+ postal_code_from:
+ postal_code_to:
+ country_name: United States
+ state_name:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: dzm_gbHJdmfrXB
+ member_type: postal_code
+ country_code: US
+ state_code:
+ postal_code_prefix: '10'
+ postal_code_from:
+ postal_code_to:
+ country_name: United States
+ state_name:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- children_count: 0
- members_count: 0
- '422':
- description: invalid request
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_origin_group_id: og_UkLWZg9DAJ
+ delivery_method_ids: []
requestBody:
content:
application/json:
@@ -37549,78 +42107,53 @@ paths:
properties:
name:
type: string
- example: Globex Corporation
- kind:
- type: string
- enum:
- - company
- - division
- description: company = legal entity (may hold tax registrations),
- division = organizational unit. Roots must be company.
- example: company
- parent_id:
+ example: US North-East
+ description:
type: string
nullable: true
- description: The parent node. Omit for a root.
- example: comp_86Rf07xd4z
- external_references:
+ members:
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:
+ member_type:
type: string
- example: erp
- external_id:
+ enum:
+ - country
+ - state
+ - postal_code
+ country_code:
type: string
- example: GLBX-42
+ nullable: true
+ example: US
+ 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:
- - system
- - external_id
+ - member_type
required:
- name
- "/api/v3/admin/custom_field_definitions/resource_types":
+ "/api/v3/admin/delivery_methods/{delivery_method_id}/rules":
get:
- summary: List what custom fields can be attached to
+ summary: List delivery method rules
tags:
- - Custom Field Definitions
+ - Delivery
security:
- api_key: []
bearer_auth: []
description: |-
- The resources a definition can describe, from the server's own
- registry (`Spree.custom_fields.enabled_resources`).
-
- Read this rather than carrying a list: a resource an extension
- registers appears here without a client release, and a `resource_type`
- that is not listed is refused on create.
-
- `resource_type` is the value to send; `name` is what a merchant calls
- it — send the value back verbatim rather than deriving it from the name.
-
+ Returns the conditions a delivery method must meet to be offered at checkout, such as an order total or weight range.
**Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- // What a definition can be attached to. Comes from the server's registry, so
- // a resource an extension adds shows up here without a client release.
- const { data: resourceTypes } = await client.customFieldDefinitions.resourceTypes()
- - lang: bash
- label: Spree CLI
- source: spree api get /custom_field_definitions/resource_types
parameters:
- name: x-spree-api-key
in: header
@@ -37632,101 +42165,90 @@ paths:
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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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: resource types found
+ description: rules found
content:
application/json:
example:
data:
- - resource_type: address
- name: Addresses
- - resource_type: category
- name: Categories
- - resource_type: claim
- name: Claims
- - resource_type: collection
- name: Collections
- - resource_type: credit_card
- name: Credit Cards
- - resource_type: customer
- name: Customers
- - resource_type: delivery_method
- name: Delivery Methods
- - resource_type: exchange
- name: Exchanges
- - resource_type: fulfillment
- name: Fulfillments
- - resource_type: gift_card
- name: Gift Cards
- - resource_type: line_item
- name: Line Items
- - resource_type: media
- name: Media
- - resource_type: newsletter_subscriber
- name: Newsletter Subscribers
- - resource_type: option_type
- name: Option Types
- - resource_type: option_value
- name: Option Values
- - resource_type: order
- name: Orders
- - resource_type: payment_method
- name: Payment Methods
- - resource_type: payment_source
- name: Payment Sources
- - resource_type: payment
- name: Payments
- - resource_type: product_type
- name: Product Types
- - resource_type: product
- name: Products
- - resource_type: promotion
- name: Promotions
- - resource_type: refund
- name: Refunds
- - resource_type: return
- name: Returns
- - resource_type: seller
- name: Sellers
- - resource_type: stock_level
- name: Stock Levels
- - resource_type: stock_transfer
- name: Stock Transfers
- - resource_type: store_credit
- name: Store Credits
- - resource_type: store
- name: Stores
- - resource_type: tax_rate
- name: Tax Rates
- - resource_type: variant
- name: Variants
+ - id: dmrule_UkLWZg9DAJ
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: item_total_rule
+ preferences:
+ minimum_amount: '25'
+ maximum_amount:
+ product_ids: []
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
type: object
properties:
data:
type: array
items:
- type: object
- properties:
- resource_type:
- type: string
- example: seller
- name:
- type: string
- example: Sellers
- "/api/v3/admin/delivery_profiles":
+ "$ref": "#/components/schemas/DeliveryMethodRule"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ "/api/v3/admin/integrations":
get:
- summary: List delivery profiles
+ summary: List integrations
tags:
- - Delivery
+ - Integrations
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.
+ Returns the integrations connected to the current store. Secret preference values are masked.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_integrations` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37738,10 +42260,10 @@ paths:
secretKey: 'sk_xxx',
})
- const profiles = await client.deliveryProfiles.list()
+ const { data: integrations } = await client.integrations.list()
- lang: bash
label: Spree CLI
- source: spree api get /delivery_profiles
+ source: spree api get /integrations
parameters:
- name: x-spree-api-key
in: header
@@ -37753,12 +42275,6 @@ paths:
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
@@ -37773,51 +42289,38 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `name`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: DeliveryProfile
+ table: Integration
sortable:
- created_at
- id
- - name
- - position
- updated_at
responses:
'200':
- description: delivery profiles found
+ description: integrations found
content:
application/json:
example:
data:
- - id: fp_UkLWZg9DAJ
- name: General
- default: true
- position: 1
+ - id: int_UkLWZg9DAJ
+ name: Carrier
+ active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- kind: shipping
- digital: false
- offers_pickup: false
- offers_shipping: false
- stock_location_ids: []
- origin_groups:
- - id: og_UkLWZg9DAJ
- name:
- position: 1
- stock_location_ids: []
- products_count: 0
- delivery_methods_count: 0
- delivery_zones_count: 0
+ type: carrier
+ group: shipping
+ preferences:
+ api_key: "•••••cret"
+ account_number: '42'
meta:
page: 1
limit: 25
@@ -37829,16 +42332,16 @@ paths:
previous:
next:
post:
- summary: Create a delivery profile
+ summary: Connect integration
tags:
- - Delivery
+ - Integrations
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.
+ 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.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_integrations` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37850,13 +42353,13 @@ paths:
secretKey: 'sk_xxx',
})
- const profile = await client.deliveryProfiles.create({
- name: 'Oversized',
- stock_location_ids: ['sloc_86Rf07xd4z'],
+ const integration = await client.integrations.create({
+ type: 'carrier',
+ preferences: { api_key: 'sk-secret', account_number: '42' },
})
- lang: bash
label: Spree CLI
- source: spree api post /delivery_profiles -d '{"name":"Oversized","stock_location_ids":["sloc_86Rf07xd4z"]}'
+ source: spree api post /integrations -d '{"type":"carrier","preferences":{"api_key":"sk-secret","account_number":"42"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -37870,82 +42373,52 @@ paths:
type: string
responses:
'201':
- description: delivery profile created
+ description: integration connected
content:
application/json:
example:
- id: fp_gbHJdmfrXB
- name: Oversized 1768478400.0
- default: false
- position: 2
+ id: int_UkLWZg9DAJ
+ name: Carrier
+ active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- kind: shipping
- digital: false
- offers_pickup: false
- offers_shipping: false
- stock_location_ids: []
- origin_groups:
- - id: og_gbHJdmfrXB
- name:
- position: 1
- stock_location_ids: []
- products_count: 0
- delivery_methods_count: 0
- delivery_zones_count: 0
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - code: blank
- message: can't be blank
- specific: false
+ type: carrier
+ group: shipping
+ preferences:
+ api_key: "•••••cret"
+ account_number:
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Oversized
- kind:
+ type:
type: string
- example: shipping
- description: Registered profile kind; defaults to shipping.
- default:
+ example: carrier
+ description: Wire shorthand from GET /integrations/types
+ active:
type: boolean
- stock_location_ids:
- type: array
- items:
- type: string
- description: Empty means every store location.
+ example: false
+ preferences:
+ type: object
+ example:
+ api_key: sk-secret
+ account_number: '42'
required:
- - name
- "/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":
- parameters:
- - name: delivery_profile_id
- in: path
- required: true
- schema:
- type: string
- post:
- summary: Create an origin group
+ - type
+ "/api/v3/admin/integrations/types":
+ get:
+ summary: List integration types
tags:
- - Delivery
+ - Integrations
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.
+ Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `read_integrations` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -37957,14 +42430,10 @@ paths:
secretKey: 'sk_xxx',
})
- const originGroup = await client.deliveryProfiles.originGroups.create('fp_86Rf07xd4z', {
- name: 'EU warehouse',
- stock_location_ids: ['sloc_86Rf07xd4z'],
- })
+ const { data: integrationTypes } = await client.integrations.types()
- lang: bash
label: Spree CLI
- source: spree api post /delivery_profiles/{delivery_profile_id}/origin_groups
- -d '{"name":"EU warehouse","stock_location_ids":["sloc_86Rf07xd4z"]}'
+ source: spree api get /integrations/types
parameters:
- name: x-spree-api-key
in: header
@@ -37977,54 +42446,43 @@ paths:
schema:
type: string
responses:
- '201':
- description: origin group created
+ '200':
+ description: integration types found
content:
application/json:
example:
- id: og_EfhxLZ9ck8
- name: EU warehouse
- position: 2
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- delivery_profile_id: fp_gbHJdmfrXB
- stock_location_ids:
- - sloc_UkLWZg9DAJ
- delivery_zones_count: 0
- delivery_methods_count: 0
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- nullable: true
- example: EU warehouse
- 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
+ data:
+ - type: carrier
+ name: Carrier
+ group: shipping
+ description:
+ logo_url:
+ docs_url:
+ schema:
+ type: object
+ properties:
+ api_key:
+ type:
+ - string
+ - 'null'
+ x-spree-secret: true
+ account_number:
+ type:
+ - string
+ - 'null'
+ additionalProperties: false
+ "/api/v3/admin/integrations/{id}/test":
+ post:
+ summary: Test integration connection
tags:
- - Delivery
+ - Integrations
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_settings` (for API-key authentication)."
+ description: |-
+ Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.
+
+ **Required scope:** `write_integrations` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -38036,13 +42494,10 @@ paths:
secretKey: 'sk_xxx',
})
- const profile = await client.deliveryProfiles.update('fp_86Rf07xd4z', {
- name: 'Oversized freight',
- stock_location_ids: [],
- })
+ const result = await client.integrations.test('int_abc123')
- lang: bash
label: Spree CLI
- source: spree api patch /delivery_profiles/{id} -d '{"name":"Oversized freight","stock_location_ids":[]}'
+ source: spree api post /integrations/{id}/test -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -38054,114 +42509,35 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: delivery profile updated
+ description: connection checked
content:
application/json:
example:
- id: fp_gbHJdmfrXB
- name: Bulky 1768478400.0
- default: false
- position: 2
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- kind: shipping
- digital: false
- offers_pickup: false
- offers_shipping: false
- stock_location_ids:
- - sloc_UkLWZg9DAJ
- origin_groups:
- - id: og_gbHJdmfrXB
- name:
- position: 1
- stock_location_ids:
- - sloc_UkLWZg9DAJ
- products_count: 0
- delivery_methods_count: 0
- delivery_zones_count: 0
- 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.
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- await client.deliveryProfiles.delete('fp_86Rf07xd4z')
- - lang: bash
- label: Spree CLI
- source: spree api delete /delivery_profiles/{id}
- 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":
+ connected: true
+ error_message:
+ "/api/v3/admin/media":
get:
- summary: List delivery methods
+ summary: List media
tags:
- - Delivery
+ - Media
security:
- api_key: []
bearer_auth: []
description: |-
- Returns all delivery methods with calculator and zone configuration.
-
- **Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Returns every file in the store's media library, whether or not it has
+ been placed on a product. Filter with `q[unattached]=true` for files not
+ yet in use, `q[media_type_eq]` for images or video, and
+ `q[filename_cont]` to search by file name.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const { data: deliveryMethods } = await client.deliveryMethods.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /delivery_methods
+ **Required scope:** `read_media` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -38171,14 +42547,39 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: q[search]
+ - 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: Matches any of name (partial, case-insensitive).
+ 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
@@ -38193,81 +42594,67 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
- | `available_to_sellers` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
- | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
- | `storefront_visible` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- <Accordion title="Filters through associations">
-
- Prefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.
-
- | Prefix | Attributes |
- |---|---|
- | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
-
- </Accordion>
-
- **Sort by:** `available_to_sellers`, `created_at`, `id`, `name`, `seller_id`, `storefront_visible`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: DeliveryMethod
+ table: Media
sortable:
- - available_to_sellers
+ - alt
- created_at
- id
- - name
- - seller_id
- - storefront_visible
+ - media_type
+ - position
- updated_at
responses:
'200':
- description: delivery methods found
+ description: media found
content:
application/json:
example:
data:
- - id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND_1
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- admin_name:
- storefront_visible: true
- tracking_url:
- available_to_sellers: false
+ - id: media_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ variant_ids: []
+ position: 1
+ alt: Front view
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ video_provider:
+ 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
+ external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- deleted_at:
- markup_flat: '0.00'
- markup_percent: '0'
- seller_id:
- seller_name:
- services: []
- rules: []
- tax_category_id:
- delivery_profile_id: fp_UkLWZg9DAJ
- delivery_origin_group_id: og_UkLWZg9DAJ
- delivery_zone_id:
- stock_location_ids: []
- fulfillment_provider: manual
- pickup_point_provider:
- rate_provider:
- calculator:
- type: flat_rate
- preferences:
- amounts: {}
- amount: '10.00'
- currency: USD
+ attached: true
+ filename: thinking-cat.jpg
+ content_type: image/jpeg
+ byte_size: 18090
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e
+ viewable_id: prod_UkLWZg9DAJ
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment
+ metadata: {}
+ viewable_type: product
meta:
page: 1
limit: 25
@@ -38278,36 +42665,33 @@ paths:
in: 1
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Media"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Create delivery method
+ summary: Upload a file to the library
tags:
- - Delivery
+ - Media
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.
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ 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
+ here. Put the file on a product by posting to that product's media with
+ this record's id as `source_media_id`.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const deliveryMethod = await client.deliveryMethods.create({
- name: 'Express',
- storefront_visible: true,
- calculator: { type: 'flat_rate', preferences: { amount: '12.50' } },
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /delivery_methods -d '{"name":"Express","storefront_visible":true,"calculator":{"type":"flat_rate","preferences":{"amount":"12.50"}}}'
+ **Required scope:** `write_media` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -38317,318 +42701,99 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: delivery method created
+ description: file added
content:
application/json:
example:
- id: dm_UkLWZg9DAJ
- name: Express
- code:
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- admin_name:
- storefront_visible: true
- tracking_url:
- available_to_sellers: false
+ id: media_gbHJdmfrXB
+ product_id:
+ variant_ids: []
+ position: 1
+ alt: Folded on a table
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ video_provider:
+ 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
+ external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- deleted_at:
- markup_flat: '0.00'
- markup_percent: '0'
- seller_id:
- seller_name:
- services: []
- rules: []
- tax_category_id:
- delivery_profile_id: fp_UkLWZg9DAJ
- delivery_origin_group_id: og_UkLWZg9DAJ
- delivery_zone_id:
- stock_location_ids: []
- fulfillment_provider: manual
- pickup_point_provider:
- rate_provider:
- calculator:
- type: flat_rate
- preferences:
- amounts: {}
- amount: '12.50'
- currency: USD
+ attached: false
+ filename: library-upload.jpg
+ content_type: image/jpeg
+ byte_size: 18090
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/library-upload.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b
+ viewable_id:
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/library-upload.jpg?disposition=attachment
+ metadata: {}
+ viewable_type:
+ schema:
+ "$ref": "#/components/schemas/Media"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Express
- admin_name:
- type: string
- nullable: true
- code:
- type: string
- nullable: true
- fulfillment_provider:
- type: string
- nullable: true
- example: manual
- delivery_profile_id:
+ signed_id:
type: string
- nullable: true
- example: fp_86Rf07xd4z
- storefront_visible:
- type: boolean
- example: true
- tracking_url:
+ description: Direct-upload signed id for the file.
+ alt:
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:
+ example: Folded on a table
+ media_type:
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
- example: flat_rate
- preferences:
- type: object
- example:
- amount: '12.5'
- delivery_zone_id:
+ enum:
+ - image
+ - video
+ - external_video
+ example: image
+ external_video_url:
type: string
- nullable: true
- required:
- - name
- "/api/v3/admin/delivery_methods/calculators":
+ 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: List delivery calculators
- tags:
- - Delivery
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Registered delivery calculator classes with preference schemas for building configuration forms.
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: calculators } = await client.deliveryMethods.calculators()
- - lang: bash
- label: Spree CLI
- source: spree api get /delivery_methods/calculators
- 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:
- example:
- data:
- - type: flat_percent_item_total
- name: Flat Percent
- schema:
- type: object
- properties:
- flat_percent:
- type: string
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: '0'
- additionalProperties: false
- - type: flat_rate
- name: Flat rate
- schema:
- type: object
- properties:
- amounts:
- type: object
- propertyNames:
- type: string
- format: currency
- pattern: "^[A-Z]{3}$"
- additionalProperties:
- type: string
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: {}
- amount:
- type: string
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: '0'
- currency:
- type: string
- format: currency
- pattern: "^[A-Z]{3}$"
- additionalProperties: false
- - type: flexi_rate
- name: Flexible Rate per package item
- schema:
- 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
- - type: per_item
- name: Flat rate per package item
- schema:
- type: object
- properties:
- amounts:
- type: object
- propertyNames:
- type: string
- format: currency
- pattern: "^[A-Z]{3}$"
- additionalProperties:
- type: string
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: {}
- amount:
- type: string
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: '0'
- currency:
- type: string
- format: currency
- pattern: "^[A-Z]{3}$"
- additionalProperties: false
- - type: price_sack
- name: Price sack
- schema:
- 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
- - type: digital_delivery
- name: Digital Delivery
- schema:
- type: object
- properties:
- amounts:
- type: object
- propertyNames:
- type: string
- format: currency
- pattern: "^[A-Z]{3}$"
- additionalProperties:
- type: string
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: {}
- amount:
- type: string
- format: money
- pattern: "^-?\\d+(\\.\\d+)?$"
- default: '0'
- currency:
- type: string
- format: currency
- pattern: "^[A-Z]{3}$"
- additionalProperties: false
- "/api/v3/admin/delivery_zones":
- post:
- summary: Create delivery zone
+ summary: Where a file is used
tags:
- - Delivery
+ - Media
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).
+ Lists everywhere this file appears: products it is placed on, image
+ fields that picked it, and descriptions embedding it. Reusing a file
+ shares it rather than copying it, so deleting one placement can leave
+ others pointing at the same file — check this first.
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Description matches are best-effort: an embedded image is a plain URL
+ with nothing recording it, so treat an empty result as "nothing found",
+ not proof the file is unused.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const deliveryZone = await client.deliveryZones.create({
- name: 'US North-East',
- members: [
- { member_type: 'country', country_code: 'US' },
- { member_type: 'postal_code', country_code: 'US', postal_code_prefix: '10' },
- ],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /delivery_zones -d '{"name":"US North-East","members":[{"member_type":"country","country_code":"US"},{"member_type":"postal_code","country_code":"US","postal_code_prefix":"10"}]}'
+ **Required scope:** `read_media` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -38638,121 +42803,65 @@ paths:
- name: Authorization
in: header
required: true
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to embed, e.g. `members`
+ description: Bearer token for admin authentication
schema:
type: string
responses:
- '201':
- description: delivery zone created
+ '200':
+ description: usage found
content:
application/json:
example:
- id: dz_UkLWZg9DAJ
- name: US North-East
- description:
- members:
- - id: dzm_UkLWZg9DAJ
- member_type: country
- country_code: US
- state_code:
- postal_code_prefix:
- postal_code_from:
- postal_code_to:
- country_name: United States
- state_name:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- - id: dzm_gbHJdmfrXB
- member_type: postal_code
- country_code: US
- state_code:
- postal_code_prefix: '10'
- postal_code_from:
- postal_code_to:
- country_name: United States
- state_name:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- delivery_profile_id: fp_UkLWZg9DAJ
- delivery_origin_group_id: og_UkLWZg9DAJ
- delivery_method_ids: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: US North-East
- 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
- example: US
- 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/integrations":
+ data:
+ - kind: media
+ name: Product 253397
+ owner_type: product
+ owner_id: prod_UkLWZg9DAJ
+ field: attachment
+ 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 integrations
+ summary: List product media
tags:
- - Integrations
+ - Media
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the integrations connected to the current store. Secret preference values are masked.
-
- **Required scope:** `read_integrations` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Returns the files placed on a product, in their display order.
- const { data: integrations } = await client.integrations.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /integrations
+ **Required scope:** `read_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -38762,8 +42871,39 @@ paths:
- 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
@@ -38778,38 +42918,67 @@ paths:
content: |-
## Filters
- Filter 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).
+ Filter 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).
| Attribute | Kind | Predicates |
|---|---|---|
+ | `alt` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
| `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `media_type` | One of `image`, `video`, `external_video` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `position` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
| `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
- **Sort by:** `created_at`, `id`, `updated_at`. Prefix a field with `-` to sort descending.
+ **Sort by:** `alt`, `created_at`, `id`, `media_type`, `position`, `updated_at`. Prefix a field with `-` to sort descending.
x-spree-filters:
- table: Integration
+ table: Media
sortable:
+ - alt
- created_at
- id
+ - media_type
+ - position
- updated_at
responses:
'200':
- description: integrations found
+ description: media found
content:
application/json:
example:
data:
- - id: int_UkLWZg9DAJ
- name: Carrier
- active: false
+ - id: media_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ variant_ids: []
+ position: 1
+ alt: Front view
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ video_provider:
+ 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
+ external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- type: carrier
- group: shipping
- preferences:
- api_key: "•••••cret"
- account_number: '42'
+ attached: true
+ filename: thinking-cat.jpg
+ content_type: image/jpeg
+ byte_size: 18090
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e
+ viewable_id: prod_UkLWZg9DAJ
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment
+ metadata: {}
+ viewable_type: product
meta:
page: 1
limit: 25
@@ -38820,35 +42989,33 @@ paths:
in: 1
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Media"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Connect integration
+ summary: Place a library file on a product
tags:
- - Integrations
+ - Media
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.
-
- **Required scope:** `write_integrations` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Puts a file that is already in the library onto this product. The new
+ record shares the source's file rather than copying it, so nothing is
+ uploaded and no image is reprocessed; it carries its own alt text,
+ position and variant links from here on.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const integration = await client.integrations.create({
- type: 'carrier',
- preferences: { api_key: 'sk-secret', account_number: '42' },
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /integrations -d '{"type":"carrier","preferences":{"api_key":"sk-secret","account_number":"42"}}'
+ **Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -38858,175 +43025,92 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: integration connected
+ description: file placed
content:
application/json:
example:
- id: int_UkLWZg9DAJ
- name: Carrier
- active: false
+ id: media_gbHJdmfrXB
+ product_id: prod_gbHJdmfrXB
+ variant_ids: []
+ position: 1
+ alt: Front view
+ media_type: image
+ focal_point_x:
+ focal_point_y:
+ external_video_url:
+ video_provider:
+ 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
+ external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- type: carrier
- group: shipping
- preferences:
- api_key: "•••••cret"
- account_number:
+ attached: true
+ filename: thinking-cat.jpg
+ content_type: image/jpeg
+ byte_size: 18090
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e
+ viewable_id: prod_gbHJdmfrXB
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment
+ metadata: {}
+ viewable_type: product
+ schema:
+ "$ref": "#/components/schemas/Media"
requestBody:
content:
application/json:
schema:
type: object
properties:
- type:
+ source_media_id:
type: string
- example: carrier
- description: Wire shorthand from GET /integrations/types
- active:
- type: boolean
- example: false
- preferences:
- type: object
- example:
- api_key: sk-secret
- account_number: '42'
+ description: A media record already in the library.
+ alt:
+ type: string
+ example: Front view
+ position:
+ type: integer
+ example: 1
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.
-
- **Required scope:** `read_integrations` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const { data: integrationTypes } = await client.integrations.types()
- - lang: bash
- label: Spree CLI
- source: spree api get /integrations/types
- 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:
- example:
- data:
- - type: carrier
- name: Carrier
- group: shipping
- description:
- logo_url:
- docs_url:
- schema:
- type: object
- properties:
- api_key:
- type:
- - string
- - 'null'
- x-spree-secret: true
- account_number:
- type:
- - string
- - 'null'
- additionalProperties: false
- "/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.
-
- **Required scope:** `write_integrations` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const result = await client.integrations.test('int_abc123')
- - lang: bash
- label: Spree CLI
- source: spree api post /integrations/{id}/test -d '{ ... }'
- 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:
- example:
- connected: true
- error_message:
- "/api/v3/admin/media":
+ - 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 media
+ summary: List variant media
tags:
- Media
security:
- api_key: []
bearer_auth: []
description: |-
- Returns every file in the store's media library, whether or not it has
- been placed on a product. Filter with `q[unattached]=true` for files not
- yet in use, `q[media_type_eq]` for images or video, and
- `q[filename_cont]` to search by file name.
+ Returns the files placed on one of a product's variants, in their display order.
-
- **Required scope:** `read_media` (for API-key authentication).
+ **Required scope:** `read_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -39111,11 +43195,12 @@ paths:
application/json:
example:
data:
- - id: media_UkLWZg9DAJ
+ - id: media_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- variant_ids: []
+ variant_ids:
+ - variant_gbHJdmfrXB
position: 1
- alt: Front view
+ alt: Variant view
media_type: image
focal_point_x:
focal_point_y:
@@ -39124,13 +43209,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/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
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -39138,12 +43223,12 @@ paths:
filename: thinking-cat.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e
- viewable_id: prod_UkLWZg9DAJ
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b
+ viewable_id: variant_gbHJdmfrXB
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/thinking-cat.jpg?disposition=attachment
metadata: {}
- viewable_type: product
+ viewable_type: variant
meta:
page: 1
limit: 25
@@ -39166,265 +43251,6 @@ paths:
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
- file first through the direct-upload endpoint, then send the signed id
- here. Put the file on a product by posting to that product's media with
- this record's id as `source_media_id`.
-
-
- **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:
- example:
- id: media_gbHJdmfrXB
- product_id:
- variant_ids: []
- position: 1
- alt: Folded on a table
- media_type: image
- focal_point_x:
- focal_point_y:
- external_video_url:
- video_provider:
- 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
- external_references: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- attached: false
- filename: library-upload.jpg
- content_type: image/jpeg
- byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/library-upload.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b
- viewable_id:
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--053fbe076a2bcf4877e00bbba79c444e9958db0b/library-upload.jpg?disposition=attachment
- metadata: {}
- viewable_type:
- 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
- example: Folded on a table
- media_type:
- type: string
- enum:
- - image
- - video
- - external_video
- example: image
- 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
- fields that picked it, and descriptions embedding it. Reusing a file
- shares it rather than copying it, so deleting one placement can leave
- others pointing at the same file — check this first.
-
- Description matches are best-effort: an embedded image is a plain URL
- with nothing recording it, so treat an empty result as "nothing found",
- not proof the file is unused.
-
-
- **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:
- example:
- data:
- - kind: media
- name: Product 193397
- owner_type: product
- owner_id: prod_UkLWZg9DAJ
- field: attachment
- 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
- 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
- record shares the source's file rather than copying it, so nothing is
- uploaded and no image is reprocessed; it carries its own alt text,
- position and variant links from here on.
-
-
- **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:
- example:
- id: media_gbHJdmfrXB
- product_id: prod_gbHJdmfrXB
- variant_ids: []
- position: 1
- alt: Front view
- media_type: image
- focal_point_x:
- focal_point_y:
- external_video_url:
- video_provider:
- 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
- external_references: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- attached: true
- filename: thinking-cat.jpg
- content_type: image/jpeg
- byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--bfaa926e6a7d26eacf8d3a020e87bcd9c7eb548f/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e
- viewable_id: prod_gbHJdmfrXB
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--af56ca8eaae24da2ded09307646bc7e0eb2e0c3e/thinking-cat.jpg?disposition=attachment
- metadata: {}
- viewable_type: product
- 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
- example: Front view
- position:
- type: integer
- example: 1
- required:
- - source_media_id
"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":
get:
summary: List deliveries
@@ -41130,12 +44956,12 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 783365
+ name: Product 873365
thumbnail_url:
price_list_variants:
- id: variant_UkLWZg9DAJ
label:
- sku: SKU-85
+ sku: SKU-98
currency: USD
source: base
break_count: 1
@@ -42161,8 +45987,8 @@ paths:
purchase_order_id: po_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- variant_name: Product 1259018
- variant_sku: SKU-148
+ variant_name: Product 1359018
+ variant_sku: SKU-162
options_text: 'Size: S'
thumbnail_url:
supplier:
@@ -42782,6 +46608,111 @@ paths:
reason:
type: string
example: Supplier went under
+ "/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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `name` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `seeded` | True or false | `eq` `not_eq` `in` `not_in` `true` `false` `null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: sq_UkLWZg9DAJ
+ name: Sales by channel
+ description:
+ query:
+ metrics:
+ - total_sales
+ - orders
+ dimensions:
+ - channel
+ seeded: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ user_id:
+ author_name:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -44794,6 +48725,429 @@ paths:
message: This seller has nothing to settle right now.
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `reviewed_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `status` | One of `pending`, `accepted`, `rejected`, `waived` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[requirement_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `requirement_` | `created_at`, `id`, `name`, `position`, `updated_at` |
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: selsub_UkLWZg9DAJ
+ status: pending
+ note:
+ review_note:
+ reference:
+ metadata: {}
+ reviewed_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ seller_id: sel_UkLWZg9DAJ
+ requirement_id: selreq_UkLWZg9DAJ
+ requirement_name: Confirm something 1
+ file_url:
+ file_name:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
+ reversals. Read-only, since fulfilment and refunds write it.
+
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `kind` | One of `earning`, `refund_reversal` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `payout_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `provider` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `status` | One of `pending`, `processing`, `completed`, `failed`, `unresolved` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[payout_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `payout_` | `amount`, `created_at`, `currency`, `id`, `period_end`, `period_start`, `provider`, `reference`, `seller_id`, `status`, `updated_at` |
+ | `payout_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `refund_` | `created_at`, `id`, `updated_at` |
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: vtr_UkLWZg9DAJ
+ kind: earning
+ status: completed
+ currency: USD
+ reference:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '40.00'
+ settled_amount: '40.00'
+ settled_currency: USD
+ converted: false
+ seller_id: sel_UkLWZg9DAJ
+ order_id: or_UkLWZg9DAJ
+ payout_id:
+ reversed_from_id:
+ refund_id:
+ seller_name: Sparks Audio
+ order_number: R1001
+ provider: system
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
+ accumulated since the last. `pending` and `processing` payouts are
+ still owed; `completed` ones reached the seller.
+
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `amount` | Amount | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `currency` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `period_end` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `period_start` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `provider` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `reference` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `status` | One of `pending`, `processing`, `completed`, `failed`, `unresolved` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[seller_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: vpo_UkLWZg9DAJ
+ status: pending
+ currency: USD
+ reference:
+ metadata: {}
+ period_start:
+ period_end:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '40.00'
+ seller_id: sel_UkLWZg9DAJ
+ seller_name: Sparks Audio
+ transfers_count: 0
+ provider: system
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -45034,8 +49388,8 @@ paths:
reserved_count: 0
incoming_count: 0
purchasable_count: 0
- variant_name: Product 1365410
- variant_sku: SKU-168
+ variant_name: Product 1505410
+ variant_sku: SKU-186
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_name: Jong Schamberger
@@ -45054,8 +49408,8 @@ paths:
reserved_count: 0
incoming_count: 0
purchasable_count: 0
- variant_name: Product 1365410
- variant_sku: SKU-169
+ variant_name: Product 1505410
+ variant_sku: SKU-187
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_name: Jong Schamberger
@@ -45074,8 +49428,8 @@ paths:
reserved_count: 2
incoming_count: 20
purchasable_count: 35
- variant_name: Product 1365410
- variant_sku: SKU-169
+ variant_name: Product 1505410
+ variant_sku: SKU-187
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
stock_location_name: Pilar Stokes
@@ -45379,8 +49733,8 @@ paths:
stock_location_id: sloc_UkLWZg9DAJ
stock_location_name: Mona Hegmann
variant_id: variant_gbHJdmfrXB
- variant_name: Product 1398513
- variant_sku: SKU-174
+ variant_name: Product 1538513
+ variant_sku: SKU-192
order_id:
fulfillment_id:
return_id:
@@ -45494,8 +49848,8 @@ paths:
stock_location_id: sloc_UkLWZg9DAJ
stock_location_name: Chrystal Sauer
variant_id: variant_gbHJdmfrXB
- variant_name: Product 1412954
- variant_sku: SKU-178
+ variant_name: Product 1552954
+ variant_sku: SKU-196
order_id:
fulfillment_id:
return_id:
@@ -45521,6 +49875,151 @@ paths:
message: Stock movement not found
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.
+
+ **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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `expires_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `line_item_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `order_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `quantity` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `stock_level_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ <Accordion title="Filters through associations">
+
+ Prefix an associated record's attribute with the association, as in `q[line_item_id_eq]`. The same predicates apply.
+
+ | Prefix | Attributes |
+ |---|---|
+ | `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` |
+ | `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` |
+ | `line_item_tax_category_` | `created_at`, `id`, `is_default`, `name`, `tax_code`, `updated_at` |
+ | `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` |
+ | `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` |
+ | `order_bill_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_channel_` | `active`, `code`, `created_at`, `default`, `id`, `name`, `store_id`, `updated_at` |
+ | `order_customer_` | `accepts_email_marketing`, `created_at`, `email`, `first_name`, `id`, `last_name`, `phone`, `updated_at` |
+ | `order_fulfillments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `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` |
+ | `order_order_group_` | `created_at`, `currency`, `email`, `id`, `number`, `updated_at` |
+ | `order_promotions_` | `code`, `created_at`, `expires_at`, `id`, `kind`, `name`, `path`, `promotion_category_id`, `starts_at`, `updated_at` |
+ | `order_seller_` | `contact_email`, `created_at`, `id`, `name`, `status`, `updated_at` |
+ | `order_ship_address_` | `address1`, `address2`, `city`, `company`, `country_code`, `created_at`, `first_name`, `id`, `last_name`, `phone`, `postal_code`, `state_code`, `updated_at` |
+ | `order_shipments_` | `created_at`, `id`, `number`, `updated_at` |
+ | `order_store_` | `created_at`, `id`, `name`, `updated_at` |
+ | `order_tags_` | `created_at`, `id`, `name`, `updated_at` |
+ | `stock_level_` | `allocated_count`, `count_on_hand`, `created_at`, `id`, `incoming_count`, `reserved_count`, `stock_location_id`, `updated_at`, `variant_id` |
+ | `stock_level_stock_location_` | `active`, `country_code`, `created_at`, `default`, `id`, `kind`, `name`, `pickup_enabled`, `returns_enabled`, `seller_id`, `state_code`, `updated_at` |
+ | `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` |
+
+ </Accordion>
+
+ **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:
+ example:
+ data:
+ - id: res_UkLWZg9DAJ
+ stock_level_id: sl_UkLWZg9DAJ
+ line_item_id: li_UkLWZg9DAJ
+ order_id: or_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ quantity: 1
+ expires_at: '2026-01-15T12:10:00.000Z'
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
@@ -45922,8 +50421,8 @@ paths:
stock_transfer_id: st_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- variant_name: Product 1472176
- variant_sku: SKU-190
+ variant_name: Product 1622176
+ variant_sku: SKU-209
options_text: 'Size: S'
thumbnail_url:
source_location:
@@ -48878,13 +53377,19 @@ components:
preferences:
"$ref": "#/components/schemas/CommissionRulePreferences"
product_ids:
- type: object
+ type: array
+ items:
+ type: string
nullable: true
seller_ids:
- type: object
+ type: array
+ items:
+ type: string
nullable: true
category_ids:
- type: object
+ type: array
+ items:
+ type: string
nullable: true
sellers:
type: array
@@ -48987,7 +53492,9 @@ components:
type: string
nullable: true
ancestors:
- type: object
+ type: array
+ items:
+ type: object
external_references:
type: object
metadata:
@@ -49060,7 +53567,9 @@ components:
type: string
nullable: true
documents:
- type: object
+ type: array
+ items:
+ type: object
required:
- id
- purpose
@@ -49245,8 +53754,7 @@ components:
- json
key:
type: string
- value:
- type: object
+ value: {}
created_at:
type: string
updated_at:
@@ -49759,7 +54267,9 @@ components:
items:
type: string
origin_groups:
- type: object
+ type: array
+ items:
+ type: object
products_count:
type: number
delivery_methods_count:
@@ -50803,7 +55313,9 @@ components:
type: string
nullable: true
documents:
- type: object
+ type: array
+ items:
+ type: object
labels:
type: array
items:
@@ -53768,7 +58280,9 @@ components:
items:
"$ref": "#/components/schemas/Refund"
documents:
- type: object
+ type: array
+ items:
+ type: object
labels:
type: array
items:
@@ -57204,6 +61718,24 @@ components:
associations: {}
scopes:
search: text
+ Claim:
+ attributes:
+ created_at: datetime
+ id: id
+ number: text
+ status:
+ enum:
+ - open
+ - approved
+ - resolved
+ - denied
+ - canceled
+ updated_at: datetime
+ associations:
+ order: Order
+ reason: ClaimReason
+ scopes:
+ search: text
ClaimReason:
attributes:
active: boolean
@@ -57301,6 +61833,14 @@ components:
parent: Company
scopes:
search: text
+ CompanyInvitation:
+ attributes:
+ created_at: datetime
+ email: text
+ id: id
+ updated_at: datetime
+ associations: {}
+ scopes: {}
CompanyMembership:
attributes:
created_at: datetime
@@ -57308,6 +61848,28 @@ components:
updated_at: datetime
associations: {}
scopes: {}
+ ConsentRecord:
+ attributes:
+ accepted: boolean
+ created_at: datetime
+ email: text
+ id: id
+ purpose: text
+ recorded_at: datetime
+ source:
+ enum:
+ - checkout
+ - registration
+ - account
+ - admin
+ - newsletter
+ - anonymization
+ - unknown
+ - import
+ - storefront
+ updated_at: datetime
+ associations: {}
+ scopes: {}
CouponCode:
attributes:
code: text
@@ -57386,6 +61948,30 @@ components:
associations: {}
scopes:
search: text
+ DataRequest:
+ attributes:
+ completed_at: datetime
+ created_at: datetime
+ email: text
+ id: id
+ kind:
+ enum:
+ - access
+ - erasure
+ number: text
+ requested_at: datetime
+ status:
+ enum:
+ - pending
+ - processing
+ - completed
+ - failed
+ updated_at: datetime
+ associations: {}
+ scopes:
+ access: boolean
+ erasure: boolean
+ in_progress: boolean
Delivery:
attributes:
carrier: text
@@ -57419,6 +62005,22 @@ components:
seller: Seller
scopes:
search: text
+ DeliveryMethodRule:
+ attributes:
+ created_at: datetime
+ id: id
+ updated_at: datetime
+ associations: {}
+ scopes: {}
+ DeliveryOriginGroup:
+ attributes:
+ created_at: datetime
+ id: id
+ name: text
+ position: integer
+ updated_at: datetime
+ associations: {}
+ scopes: {}
DeliveryProfile:
attributes:
created_at: datetime
@@ -57429,6 +62031,29 @@ components:
associations: {}
scopes:
search: text
+ DeliveryZone:
+ attributes:
+ created_at: datetime
+ delivery_profile_id: id
+ id: id
+ name: text
+ updated_at: datetime
+ associations: {}
+ scopes: {}
+ DigitalAsset:
+ attributes:
+ created_at: datetime
+ id: id
+ updated_at: datetime
+ associations: {}
+ scopes: {}
+ DigitalLink:
+ attributes:
+ created_at: datetime
+ id: id
+ updated_at: datetime
+ associations: {}
+ scopes: {}
Discount:
attributes:
created_at: datetime
@@ -57442,6 +62067,24 @@ components:
id: id
associations: {}
scopes: {}
+ Exchange:
+ attributes:
+ created_at: datetime
+ id: id
+ number: text
+ status:
+ enum:
+ - requested
+ - approved
+ - received
+ - fulfilled
+ - canceled
+ updated_at: datetime
+ associations:
+ order: Order
+ reason: ReturnReason
+ scopes:
+ search: text
Export:
attributes:
created_at: datetime
@@ -57466,6 +62109,13 @@ components:
updated_at: datetime
associations: {}
scopes: {}
+ Fee:
+ attributes:
+ created_at: datetime
+ id: id
+ updated_at: datetime
+ associations: {}
+ scopes: {}
Fulfillment:
attributes:
created_at: datetime
@@ -58052,6 +62702,24 @@ components:
updated_at: datetime
associations: {}
scopes: {}
+ Return:
+ attributes:
+ created_at: datetime
+ id: id
+ number: text
+ status:
+ enum:
+ - requested
+ - approved
+ - received
+ - refunded
+ - canceled
+ updated_at: datetime
+ associations:
+ order: Order
+ reason: ReturnReason
+ scopes:
+ search: text
ReturnReason:
attributes:
active: boolean
@@ -58069,6 +62737,16 @@ components:
updated_at: datetime
associations: {}
scopes: {}
+ SavedReport:
+ attributes:
+ created_at: datetime
+ id: id
+ name: text
+ seeded: boolean
+ updated_at: datetime
+ associations: {}
+ scopes:
+ search: text
Seller:
attributes:
contact_email: text
@@ -58089,6 +62767,29 @@ components:
associations: {}
scopes:
search: text
+ SellerPayout:
+ attributes:
+ amount: decimal
+ created_at: datetime
+ currency: text
+ id: id
+ period_end: datetime
+ period_start: datetime
+ provider: text
+ reference: text
+ seller_id: id
+ status:
+ enum:
+ - pending
+ - processing
+ - completed
+ - failed
+ - unresolved
+ updated_at: datetime
+ associations:
+ seller: Seller
+ scopes:
+ search: text
SellerRequirement:
attributes:
created_at: datetime
@@ -58099,6 +62800,51 @@ components:
associations: {}
scopes:
search: text
+ SellerRequirementSubmission:
+ attributes:
+ created_at: datetime
+ id: id
+ reviewed_at: datetime
+ status:
+ enum:
+ - pending
+ - accepted
+ - rejected
+ - waived
+ updated_at: datetime
+ associations:
+ requirement: SellerRequirement
+ seller: Seller
+ scopes: {}
+ SellerTransfer:
+ attributes:
+ amount: decimal
+ created_at: datetime
+ currency: text
+ id: id
+ kind:
+ enum:
+ - earning
+ - refund_reversal
+ order_id: id
+ payout_id: id
+ provider: text
+ reference: text
+ seller_id: id
+ status:
+ enum:
+ - pending
+ - processing
+ - completed
+ - failed
+ - unresolved
+ updated_at: datetime
+ associations:
+ payout: SellerPayout
+ refund: Refund
+ seller: Seller
+ scopes:
+ search: text
ShippingLabel:
attributes:
carrier: text
@@ -58194,6 +62940,22 @@ components:
updated_at: datetime
associations: {}
scopes: {}
+ StockReservation:
+ attributes:
+ created_at: datetime
+ expires_at: datetime
+ id: id
+ line_item_id: id
+ order_id: id
+ quantity: integer
+ stock_item_id: id
+ stock_level_id: id
+ updated_at: datetime
+ associations:
+ line_item: LineItem
+ order: Order
+ stock_level: StockLevel
+ scopes: {}
StockTransfer:
attributes:
closed_short_at: datetime
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yaml
index 9148ef9207..52a2ed33fd 100644
--- a/docs/api-reference/seller.yaml
+++ b/docs/api-reference/seller.yaml
@@ -94,7 +94,7 @@ paths:
selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
- name: Seller 1
+ name: Seller 2
status: approved
schema:
"$ref": "#/components/schemas/AuthResponse"
@@ -161,7 +161,7 @@ paths:
selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
- name: Seller 3
+ name: Seller 4
status: approved
schema:
"$ref": "#/components/schemas/AuthResponse"
@@ -306,7 +306,7 @@ paths:
selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
- name: Seller 44
+ name: Seller 50
status: approved
schema:
"$ref": "#/components/schemas/AuthResponse"
@@ -423,7 +423,7 @@ paths:
selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
- name: Seller 81
+ name: Seller 87
status: approved
schema:
"$ref": "#/components/schemas/AuthResponse"
@@ -493,8 +493,8 @@ paths:
selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
- name: Seller 54
- slug: seller-54
+ name: Seller 60
+ slug: seller-60
status: approved
permissions:
- allow: true
@@ -748,8 +748,8 @@ paths:
selected_locale:
sellers:
- id: sel_UkLWZg9DAJ
- name: Seller 56
- slug: seller-56
+ name: Seller 62
+ slug: seller-62
status: approved
permissions: []
permission_keys: []
@@ -12469,7 +12469,7 @@ paths:
data:
- id: dm_UkLWZg9DAJ
name: My courier
- code: UPS_GROUND_73
+ code: UPS_GROUND_85
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -12492,7 +12492,7 @@ paths:
currency: USD
- id: dm_gbHJdmfrXB
name: Marketplace post
- code: UPS_GROUND_74
+ code: UPS_GROUND_86
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -12681,7 +12681,7 @@ paths:
example:
id: dm_UkLWZg9DAJ
name: My courier
- code: UPS_GROUND_79
+ code: UPS_GROUND_91
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -12721,7 +12721,7 @@ paths:
example:
id: dm_UkLWZg9DAJ
name: My express courier
- code: UPS_GROUND_81
+ code: UPS_GROUND_93
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -14097,8 +14097,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 2053250
- slug: product-2053250
+ name: Product 2233250
+ slug: product-2233250
meta_title:
meta_description:
meta_keywords:
@@ -14333,8 +14333,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 2086710
- slug: product-2086710
+ name: Product 2266710
+ slug: product-2266710
meta_title:
meta_description:
meta_keywords:
@@ -14409,7 +14409,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Hand-thrown mug, large
- slug: product-2118212
+ slug: product-2298212
meta_title:
meta_description:
meta_keywords:
@@ -14518,8 +14518,8 @@ paths:
application/json:
example:
id: sel_UkLWZg9DAJ
- name: Seller 101
- slug: seller-101
+ name: Seller 107
+ slug: seller-107
about: ''
about_html: ''
logo_url:
@@ -14592,7 +14592,7 @@ paths:
example:
id: sel_UkLWZg9DAJ
name: Acme Supplies
- slug: seller-103
+ slug: seller-109
about: ''
about_html: ''
logo_url:
@@ -16404,7 +16404,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 81
+ delivery_method_name: UPS Ground 93
stock_location_name: Vernie Lehner
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -16412,13 +16412,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1869315
- sku: SKU-252
+ name: Product 2029315
+ sku: SKU-273
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 81
+ name: UPS Ground 93
selected: true
cost: '10.00'
total: '10.00'
@@ -16510,7 +16510,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 82
+ delivery_method_name: UPS Ground 94
stock_location_name: Mirta Herman
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -16518,13 +16518,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 187961
- sku: SKU-253
+ name: Product 203961
+ sku: SKU-274
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 82
+ name: UPS Ground 94
selected: true
cost: '10.00'
total: '10.00'
@@ -16623,7 +16623,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 83
+ delivery_method_name: UPS Ground 95
stock_location_name: Eugena Schultz
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -16631,13 +16631,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1883170
- sku: SKU-254
+ name: Product 2043170
+ sku: SKU-275
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 83
+ name: UPS Ground 95
selected: true
cost: '10.00'
total: '10.00'
@@ -16716,7 +16716,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 84
+ delivery_method_name: UPS Ground 96
stock_location_name: Karyn Moore
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -16724,13 +16724,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1897276
- sku: SKU-255
+ name: Product 2057276
+ sku: SKU-276
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 84
+ name: UPS Ground 96
selected: true
cost: '10.00'
total: '10.00'
@@ -16754,6 +16754,248 @@ paths:
labels: []
schema:
"$ref": "#/components/schemas/Fulfillment"
+ "/api/v3/seller/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":
+ parameters:
+ - name: order_id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ description: Prefixed fulfillment ID
+ required: true
+ schema:
+ type: string
+ get:
+ summary: List deliveries
+ tags:
+ - Fulfillments
+ security:
+ - bearer_auth: []
+ description: The consignments of one of this seller's parcels, one per tracking
+ number, with each carrier status.
+ parameters:
+ - name: X-Spree-Seller-Id
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `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` |
+ | `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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 listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Delivery"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ "/api/v3/seller/orders/{order_id}/fulfillments/{fulfillment_id}/labels":
+ parameters:
+ - name: order_id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
+ - name: fulfillment_id
+ in: path
+ description: Prefixed fulfillment ID
+ required: true
+ schema:
+ type: string
+ get:
+ summary: List shipping labels
+ tags:
+ - Fulfillments
+ security:
+ - bearer_auth: []
+ description: Every label bought or uploaded for one of this seller's parcels,
+ refunded ones included.
+ parameters:
+ - name: X-Spree-Seller-Id
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `carrier` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `source` | One of `purchased`, `uploaded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `status` | One of `purchased`, `refund_requested`, `refunded` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `tracking_number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: purchased
+ carrier: ups
+ carrier_name: UPS
+ service: Ground
+ tracking_number: 1Z879E930346830007
+ currency: USD
+ format: pdf
+ external_id: shp_4
+ metadata: {}
+ refunded_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ owner_id: ful_UkLWZg9DAJ
+ owner_type: fulfillment
+ cost: '7.25'
+ integration_id:
+ file_pending: false
+ download_url:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/ShippingLabel"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
"/api/v3/seller/tracking_carriers":
get:
summary: List tracking carriers
@@ -16826,6 +17068,372 @@ paths:
- name
required:
- data
+ "/api/v3/seller/imports":
+ get:
+ summary: List imports
+ tags:
+ - Imports
+ security:
+ - bearer_auth: []
+ description: This seller's product CSV imports, queued or finished. Another
+ seller's imports are never listed.
+ parameters:
+ - name: X-Spree-Seller-Id
+ 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: 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `seller_id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `status` | One of `pending`, `mapping`, `completed_mapping`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `type` | Type | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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 listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: imp_UkLWZg9DAJ
+ number: IM1001
+ rows_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: products
+ status: pending
+ store_id: store_UkLWZg9DAJ
+ seller_id: sel_UkLWZg9DAJ
+ owner_type: seller
+ owner_id: sel_UkLWZg9DAJ
+ user_id: adm_UkLWZg9DAJ
+ processing_errors:
+ delimiter: ","
+ original_filename: products_import.csv
+ original_byte_size: 3627
+ original_file_url: "/api/v3/seller/imports/imp_UkLWZg9DAJ/download"
+ completed_rows_count: 0
+ failed_rows_count: 0
+ schema_fields:
+ - name: slug
+ label: Slug
+ required: true
+ - name: sku
+ label: SKU
+ required: true
+ - name: name
+ label: Name
+ required: true
+ - name: price
+ label: Price
+ required: true
+ - name: status
+ label: Status
+ required: false
+ - name: description
+ label: Description
+ required: false
+ - name: meta_title
+ label: Meta Title
+ required: false
+ - name: meta_description
+ label: Meta Description
+ required: false
+ - name: meta_keywords
+ label: Meta Keywords
+ required: false
+ - name: tags
+ label: Tags
+ required: false
+ - name: compare_at_price
+ label: Compare at Price
+ required: false
+ - name: currency
+ label: Currency
+ required: false
+ - name: width
+ label: Width
+ required: false
+ - name: height
+ label: Height
+ required: false
+ - name: depth
+ label: Depth
+ required: false
+ - name: dimensions_unit
+ label: Dimensions Unit
+ required: false
+ - name: weight
+ label: Weight
+ required: false
+ - name: weight_unit
+ label: Weight Unit
+ required: false
+ - name: available_on
+ label: Available On
+ required: false
+ - name: discontinue_on
+ label: Discontinue On
+ required: false
+ - name: track_inventory
+ label: Track Inventory
+ required: false
+ - name: inventory_count
+ label: Inventory Count
+ required: false
+ - name: inventory_backorderable
+ label: Inventory Backorderable
+ required: false
+ - name: stock_location
+ label: Stock Location
+ required: false
+ - name: tax_category
+ label: Tax Category
+ required: false
+ - name: product_type
+ label: Product Type
+ required: false
+ - name: hs_code
+ label: HS Code
+ required: false
+ - name: country_of_origin
+ label: Country of Origin
+ required: false
+ - name: customs_description
+ label: Customs Description
+ required: false
+ - name: carton
+ label: Carton
+ required: false
+ - name: units_per_carton
+ label: Units per Carton
+ required: false
+ - name: carton_weight
+ label: Carton Weight
+ required: false
+ - name: cartons_per_pallet
+ label: Cartons per Pallet
+ required: false
+ - name: image1_src
+ label: Image 1 URL
+ required: false
+ - name: image2_src
+ label: Image 2 URL
+ required: false
+ - name: image3_src
+ label: Image 3 URL
+ required: false
+ - name: option1_name
+ label: Option 1 Name
+ required: false
+ - name: option1_value
+ label: Option 1 Value
+ required: false
+ - name: option2_name
+ label: Option 2 Name
+ required: false
+ - name: option2_value
+ label: Option 2 Value
+ required: false
+ - name: option3_name
+ label: Option 3 Name
+ required: false
+ - name: option3_value
+ label: Option 3 Value
+ required: false
+ - name: category1
+ label: Category 1
+ required: false
+ - name: category2
+ label: Category 2
+ required: false
+ - name: category3
+ label: Category 3
+ required: false
+ csv_headers: []
+ sample_row: {}
+ mappings: []
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Import"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ "/api/v3/seller/imports/{import_id}/rows":
+ parameters:
+ - name: import_id
+ in: path
+ required: true
+ description: Import prefixed ID
+ schema:
+ type: string
+ get:
+ summary: List import rows
+ tags:
+ - Imports
+ security:
+ - bearer_auth: []
+ description: The rows of one of this seller's imports, each with its status
+ and any validation errors.
+ parameters:
+ - name: X-Spree-Seller-Id
+ 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
+
+ Filter 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).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `row_number` | Number | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `status` | One of `pending`, `processing`, `completed`, `failed` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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 listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: imrow_UkLWZg9DAJ
+ row_number: 1
+ status: pending
+ validation_errors:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ import_id: imp_UkLWZg9DAJ
+ item_type:
+ item_id:
+ data:
+ slug: test-product
+ name: Test Product
+ price: '10.00'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/ImportRow"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
"/api/v3/seller/orders":
get:
summary: List orders
@@ -16990,7 +17598,7 @@ paths:
cancel_note:
items:
- id: li_UkLWZg9DAJ
- name: Product 19195
+ name: Product 20995
options_text: ''
quantity: 1
currency: USD
@@ -16999,7 +17607,7 @@ paths:
additional_tax_total: '0.00'
total: '10.00'
variant_id: variant_UkLWZg9DAJ
- sku: SKU-257
+ sku: SKU-280
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -17012,7 +17620,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 86
+ delivery_method_name: UPS Ground 100
stock_location_name: Roseline Roberts
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -17020,13 +17628,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 19195
- sku: SKU-257
+ name: Product 20995
+ sku: SKU-280
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 86
+ name: UPS Ground 100
selected: true
cost: '10.00'
total: '10.00'
@@ -17054,7 +17662,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 168 Lovely Street
+ address1: 196 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17076,7 +17684,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 167 Lovely Street
+ address1: 195 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17177,7 +17785,7 @@ paths:
cancel_note:
items:
- id: li_UkLWZg9DAJ
- name: Product 1929755
+ name: Product 2109755
options_text: ''
quantity: 1
currency: USD
@@ -17186,7 +17794,7 @@ paths:
additional_tax_total: '0.00'
total: '10.00'
variant_id: variant_UkLWZg9DAJ
- sku: SKU-258
+ sku: SKU-281
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -17199,7 +17807,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 87
+ delivery_method_name: UPS Ground 101
stock_location_name: Woodrow Hand
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -17207,13 +17815,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1929755
- sku: SKU-258
+ name: Product 2109755
+ sku: SKU-281
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 87
+ name: UPS Ground 101
selected: true
cost: '10.00'
total: '10.00'
@@ -17241,7 +17849,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 170 Lovely Street
+ address1: 198 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17263,7 +17871,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 169 Lovely Street
+ address1: 197 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17360,7 +17968,7 @@ paths:
cancel_note:
items:
- id: li_UkLWZg9DAJ
- name: Product 1956554
+ name: Product 2136554
options_text: ''
quantity: 1
currency: USD
@@ -17369,7 +17977,7 @@ paths:
additional_tax_total: '0.00'
total: '10.00'
variant_id: variant_UkLWZg9DAJ
- sku: SKU-261
+ sku: SKU-284
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -17382,7 +17990,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 90
+ delivery_method_name: UPS Ground 104
stock_location_name: Ricky Kutch
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -17390,13 +17998,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1956554
- sku: SKU-261
+ name: Product 2136554
+ sku: SKU-284
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 90
+ name: UPS Ground 104
selected: true
cost: '10.00'
total: '10.00'
@@ -17424,7 +18032,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 176 Lovely Street
+ address1: 204 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17446,7 +18054,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 175 Lovely Street
+ address1: 203 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17550,7 +18158,7 @@ paths:
cancel_note:
items:
- id: li_UkLWZg9DAJ
- name: Product 1965038
+ name: Product 2145038
options_text: ''
quantity: 1
currency: USD
@@ -17559,7 +18167,7 @@ paths:
additional_tax_total: '0.00'
total: '10.00'
variant_id: variant_UkLWZg9DAJ
- sku: SKU-262
+ sku: SKU-285
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -17572,7 +18180,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 91
+ delivery_method_name: UPS Ground 105
stock_location_name: Rudy Mosciski
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -17580,13 +18188,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1965038
- sku: SKU-262
+ name: Product 2145038
+ sku: SKU-285
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 91
+ name: UPS Ground 105
selected: true
cost: '10.00'
total: '10.00'
@@ -17636,7 +18244,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 177 Lovely Street
+ address1: 205 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17803,7 +18411,7 @@ paths:
cancel_note:
items:
- id: li_UkLWZg9DAJ
- name: Product 1983962
+ name: Product 2163962
options_text: ''
quantity: 1
currency: USD
@@ -17812,7 +18420,7 @@ paths:
additional_tax_total: '0.00'
total: '10.00'
variant_id: variant_UkLWZg9DAJ
- sku: SKU-264
+ sku: SKU-287
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -17825,7 +18433,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 93
+ delivery_method_name: UPS Ground 107
stock_location_name: Kecia Pollich
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -17833,13 +18441,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1983962
- sku: SKU-264
+ name: Product 2163962
+ sku: SKU-287
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 93
+ name: UPS Ground 107
selected: true
cost: '10.00'
total: '10.00'
@@ -17867,7 +18475,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 182 Lovely Street
+ address1: 210 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17889,7 +18497,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 181 Lovely Street
+ address1: 209 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -17962,7 +18570,7 @@ paths:
cancel_note:
items:
- id: li_UkLWZg9DAJ
- name: Product 1995749
+ name: Product 2175749
options_text: ''
quantity: 1
currency: USD
@@ -17971,7 +18579,7 @@ paths:
additional_tax_total: '0.00'
total: '10.00'
variant_id: variant_UkLWZg9DAJ
- sku: SKU-265
+ sku: SKU-288
thumbnail_url:
fulfillments:
- id: ful_UkLWZg9DAJ
@@ -17984,7 +18592,7 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
fulfillment_type: shipping
- delivery_method_name: UPS Ground 94
+ delivery_method_name: UPS Ground 108
stock_location_name: Ophelia Hartmann
stock_location_id: sloc_UkLWZg9DAJ
fulfillment_items:
@@ -17992,13 +18600,13 @@ paths:
quantity: 1
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
- name: Product 1995749
- sku: SKU-265
+ name: Product 2175749
+ sku: SKU-288
options_text: ''
selected_delivery_rate_id: dr_gbHJdmfrXB
delivery_rates:
- id: dr_gbHJdmfrXB
- name: UPS Ground 94
+ name: UPS Ground 108
selected: true
cost: '10.00'
total: '10.00'
@@ -18026,7 +18634,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 184 Lovely Street
+ address1: 212 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -18048,7 +18656,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 183 Lovely Street
+ address1: 211 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -18912,7 +19520,7 @@ paths:
example:
error:
code: processing_error
- message: Only 1 of Product 2157120 can be returned
+ message: Only 1 of Product 2337120 can be returned
requestBody:
content:
application/json:
@@ -20365,8 +20973,7 @@ components:
- json
key:
type: string
- value:
- type: object
+ value: {}
required:
- id
- label
@@ -22200,8 +22807,7 @@ components:
- number
- boolean
- json
- value:
- type: object
+ value: {}
required:
- id
- key
@@ -23278,6 +23884,26 @@ components:
updated_at: datetime
associations: {}
scopes: {}
+ Delivery:
+ attributes:
+ carrier: text
+ created_at: datetime
+ id: id
+ status:
+ enum:
+ - pending
+ - pre_transit
+ - in_transit
+ - out_for_delivery
+ - available_for_pickup
+ - delivered
+ - return_to_sender
+ - failure
+ - unknown
+ tracking_number: text
+ updated_at: datetime
+ associations: {}
+ scopes: {}
DeliveryMethod:
attributes:
available_to_sellers: boolean
@@ -23333,6 +23959,39 @@ components:
updated_at: datetime
associations: {}
scopes: {}
+ Import:
+ attributes:
+ created_at: datetime
+ id: id
+ number: text
+ seller_id: id
+ status:
+ enum:
+ - pending
+ - mapping
+ - completed_mapping
+ - processing
+ - completed
+ - failed
+ type: type
+ updated_at: datetime
+ associations: {}
+ scopes:
+ search: text
+ ImportRow:
+ attributes:
+ created_at: datetime
+ id: id
+ row_number: integer
+ status:
+ enum:
+ - pending
+ - processing
+ - completed
+ - failed
+ updated_at: datetime
+ associations: {}
+ scopes: {}
Order:
attributes:
channel_id: id
@@ -23571,6 +24230,24 @@ components:
associations: {}
scopes:
search: text
+ ShippingLabel:
+ attributes:
+ carrier: text
+ created_at: datetime
+ id: id
+ source:
+ enum:
+ - purchased
+ - uploaded
+ status:
+ enum:
+ - purchased
+ - refund_requested
+ - refunded
+ tracking_number: text
+ updated_at: datetime
+ associations: {}
+ scopes: {}
StockLocation:
attributes:
active: boolean
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 1b694b5d66..65ea252a69 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -575,8 +575,8 @@ paths:
is_child: false
is_leaf: false
- id: ctg_gbHJdmfrXB
- name: category_3
- permalink: catalog/category-3
+ name: category_4
+ permalink: catalog/category-4
position: 0
depth: 1
meta_title:
@@ -592,8 +592,8 @@ paths:
is_child: true
is_leaf: false
- id: ctg_EfhxLZ9ck8
- name: category_4
- permalink: catalog/category-3/category-4
+ name: category_5
+ permalink: catalog/category-4/category-5
position: 0
depth: 2
meta_title:
@@ -692,8 +692,8 @@ paths:
application/json:
example:
id: ctg_gbHJdmfrXB
- name: category_12
- permalink: catalog/category-12
+ name: category_13
+ permalink: catalog/category-13
position: 0
depth: 1
meta_title:
@@ -1128,8 +1128,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 2516979
- slug: product-2516979
+ name: Product 2706979
+ slug: product-2706979
meta_title:
meta_description:
meta_keywords:
@@ -1419,8 +1419,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 2989085
- slug: product-2989085
+ name: Product 3189085
+ slug: product-3189085
meta_title:
meta_description:
meta_keywords:
@@ -1449,8 +1449,8 @@ paths:
original_price:
seller_id:
- id: prod_gbHJdmfrXB
- name: Product 2998209
- slug: product-2998209
+ name: Product 3198209
+ slug: product-3198209
meta_title:
meta_description:
meta_keywords:
@@ -1577,8 +1577,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 3266885
- slug: product-3266885
+ name: Product 3466885
+ slug: product-3466885
meta_title:
meta_description:
meta_keywords:
@@ -1865,7 +1865,7 @@ paths:
options:
- id: ctg_gbHJdmfrXB
name: Shirts
- permalink: category-34/shirts
+ permalink: category-35/shirts
count: 2
sort_options:
- id: manual
@@ -2162,8 +2162,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 225715
- slug: product-225715
+ name: Product 243715
+ slug: product-243715
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -2283,8 +2283,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2262171
- slug: product-2262171
+ name: Product 2442171
+ slug: product-2442171
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -2596,7 +2596,7 @@ paths:
total_quantity: 0
warnings:
- code: line_item_removed
- message: Product 230307 was removed because it was sold out
+ message: Product 248307 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
coupon_code:
@@ -2838,8 +2838,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2313263
- slug: product-2313263
+ name: Product 2493263
+ slug: product-2493263
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -3126,8 +3126,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2338992
- slug: product-2338992
+ name: Product 2518992
+ slug: product-2518992
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -3158,7 +3158,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 255 Lovely Street
+ address1: 283 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3180,7 +3180,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 254 Lovely Street
+ address1: 282 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3341,8 +3341,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2364794
- slug: product-2364794
+ name: Product 2544794
+ slug: product-2544794
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -3396,8 +3396,8 @@ paths:
deliveries: []
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 113
- code: UPS_GROUND_130
+ name: UPS Ground 127
+ code: UPS_GROUND_144
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -3418,7 +3418,7 @@ paths:
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground 113
+ name: UPS Ground 127
selected: true
cost: '10.00'
total: '10.00'
@@ -3437,8 +3437,8 @@ paths:
display_tax_total: "$0.00"
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 113
- code: UPS_GROUND_130
+ name: UPS Ground 127
+ code: UPS_GROUND_144
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -3476,7 +3476,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 261 Lovely Street
+ address1: 289 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3498,7 +3498,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 260 Lovely Street
+ address1: 288 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -3683,8 +3683,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2652614
- slug: product-2652614
+ name: Product 2852614
+ slug: product-2852614
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -3884,8 +3884,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2663461
- slug: product-2663461
+ name: Product 2863461
+ slug: product-2863461
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -4073,8 +4073,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2688182
- slug: product-2688182
+ name: Product 2888182
+ slug: product-2888182
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -4128,8 +4128,8 @@ paths:
deliveries: []
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 130
- code: UPS_GROUND_148
+ name: UPS Ground 146
+ code: UPS_GROUND_164
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -4150,7 +4150,7 @@ paths:
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground 130
+ name: UPS Ground 146
selected: true
cost: '10.00'
total: '10.00'
@@ -4169,8 +4169,8 @@ paths:
display_tax_total: "$0.00"
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 130
- code: UPS_GROUND_148
+ name: UPS Ground 146
+ code: UPS_GROUND_164
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -4184,7 +4184,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 357 Lovely Street
+ address1: 395 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4372,8 +4372,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2705702
- slug: product-2705702
+ name: Product 2905702
+ slug: product-2905702
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -4622,8 +4622,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2749569
- slug: product-2749569
+ name: Product 2949569
+ slug: product-2949569
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -4778,10 +4778,10 @@ paths:
total_quantity: 2
warnings:
- code: delivery_unavailable
- message: Product 27763 cannot be delivered to the selected address
+ message: Product 29763 cannot be delivered to the selected address
line_item_id: li_UkLWZg9DAJ
- code: delivery_unavailable
- message: Product 278298 cannot be delivered to the selected address
+ message: Product 298298 cannot be delivered to the selected address
line_item_id: li_gbHJdmfrXB
coupon_code:
item_total: '29.99'
@@ -4839,8 +4839,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 27763
- slug: product-27763
+ name: Product 29763
+ slug: product-29763
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -4870,8 +4870,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 278298
- slug: product-278298
+ name: Product 298298
+ slug: product-298298
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -5102,8 +5102,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2849165
- slug: product-2849165
+ name: Product 3049165
+ slug: product-3049165
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -5393,7 +5393,7 @@ paths:
cart_id: cart_UkLWZg9DAJ
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card 121
+ name: Credit Card 141
description:
type: bogus
session_required: true
@@ -5494,7 +5494,7 @@ paths:
cart_id: cart_UkLWZg9DAJ
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card 122
+ name: Credit Card 142
description:
type: bogus
session_required: true
@@ -5562,7 +5562,7 @@ paths:
cart_id: cart_UkLWZg9DAJ
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card 124
+ name: Credit Card 144
description:
type: bogus
session_required: true
@@ -5670,7 +5670,7 @@ paths:
cart_id: cart_UkLWZg9DAJ
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card 125
+ name: Credit Card 145
description:
type: bogus
session_required: true
@@ -5936,8 +5936,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 3469789
- slug: product-3469789
+ name: Product 3679789
+ slug: product-3679789
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -6150,8 +6150,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 348179
- slug: product-348179
+ name: Product 369179
+ slug: product-369179
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -6195,6 +6195,121 @@ paths:
- en
schema:
"$ref": "#/components/schemas/Cart"
+ "/api/v3/store/orders/{order_id}/claims":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ get:
+ summary: List claims
+ tags:
+ - Orders
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: The damage or missing-item claims opened on one of the customer's
+ orders, newest first. Accessible via JWT or the order token header for guests.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
+ 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
+
+ Filter 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/store-api/querying#which-filters-an-endpoint-accepts).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `open`, `approved`, `resolved`, `denied`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: open
+ resolution:
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.00'
+ display_refund_total: "$10.00"
+ approved_at:
+ resolved_at:
+ denied_at:
+ canceled_at:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Claim"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
"/api/v3/store/orders/{id}":
get:
summary: Get an order
@@ -6331,8 +6446,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 288496
- slug: product-288496
+ name: Product 308496
+ slug: product-308496
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -6395,8 +6510,8 @@ paths:
delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 144
- code: UPS_GROUND_162
+ name: UPS Ground 160
+ code: UPS_GROUND_178
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -6417,7 +6532,7 @@ paths:
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground 144
+ name: UPS Ground 160
selected: true
cost: '10.00'
total: '10.00'
@@ -6436,8 +6551,8 @@ paths:
display_tax_total: "$0.00"
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 144
- code: UPS_GROUND_162
+ name: UPS Ground 160
+ code: UPS_GROUND_178
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -6450,7 +6565,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 413 Lovely Street
+ address1: 451 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6472,7 +6587,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 414 Lovely Street
+ address1: 452 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6514,6 +6629,122 @@ paths:
message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/orders/{order_id}/returns":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
+ get:
+ summary: List returns
+ tags:
+ - Orders
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: The returns opened on one of the customer's orders, newest first.
+ Accessible via JWT or the order token header for guests.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
+ 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
+
+ Filter 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/store-api/querying#which-filters-an-endpoint-accepts).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `number` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `status` | One of `requested`, `approved`, `received`, `refunded`, `canceled` | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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:
+ example:
+ data:
+ - id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.00'
+ display_refund_total: "$10.00"
+ refund_tax_total: '0.00'
+ display_refund_tax_total: "$0.00"
+ approved_at:
+ received_at:
+ refunded_at:
+ canceled_at:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Return"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
"/api/v3/store/customers/me/addresses":
get:
summary: List customer addresses
@@ -6629,7 +6860,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 219 Lovely Street
+ address1: 247 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6650,7 +6881,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 220 Lovely Street
+ address1: 248 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6671,7 +6902,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 221 Lovely Street
+ address1: 249 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -6929,7 +7160,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 233 Lovely Street
+ address1: 261 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7011,7 +7242,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 239 Lovely Street
+ address1: 267 Lovely Street
address2: Northwest
postal_code: '10118'
city: Los Angeles
@@ -7579,8 +7810,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2535270
- slug: product-2535270
+ name: Product 2725270
+ slug: product-2725270
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -7643,8 +7874,8 @@ paths:
delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 123
- code: UPS_GROUND_140
+ name: UPS Ground 138
+ code: UPS_GROUND_155
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -7665,7 +7896,7 @@ paths:
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground 123
+ name: UPS Ground 138
selected: true
cost: '10.00'
total: '10.00'
@@ -7684,8 +7915,8 @@ paths:
display_tax_total: "$0.00"
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 123
- code: UPS_GROUND_140
+ name: UPS Ground 138
+ code: UPS_GROUND_155
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -7698,7 +7929,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 305 Lovely Street
+ address1: 339 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7720,7 +7951,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 306 Lovely Street
+ address1: 340 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -7903,8 +8134,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2555633
- slug: product-2555633
+ name: Product 2745633
+ slug: product-2745633
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -7967,8 +8198,8 @@ paths:
delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 125
- code: UPS_GROUND_142
+ name: UPS Ground 140
+ code: UPS_GROUND_157
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -7989,7 +8220,7 @@ paths:
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground 125
+ name: UPS Ground 140
selected: true
cost: '10.00'
total: '10.00'
@@ -8008,8 +8239,8 @@ paths:
display_tax_total: "$0.00"
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 125
- code: UPS_GROUND_142
+ name: UPS Ground 140
+ code: UPS_GROUND_157
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -8022,7 +8253,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 311 Lovely Street
+ address1: 345 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8044,7 +8275,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 312 Lovely Street
+ address1: 346 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8267,7 +8498,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 317 Lovely Street
+ address1: 351 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8288,7 +8519,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 318 Lovely Street
+ address1: 352 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8310,7 +8541,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 318 Lovely Street
+ address1: 352 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8332,7 +8563,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 317 Lovely Street
+ address1: 351 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8424,7 +8655,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 319 Lovely Street
+ address1: 353 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8445,7 +8676,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 320 Lovely Street
+ address1: 354 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8467,7 +8698,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 320 Lovely Street
+ address1: 354 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -8489,7 +8720,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 319 Lovely Street
+ address1: 353 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -9113,7 +9344,7 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card 127
+ name: Credit Card 147
description:
type: bogus
session_required: true
@@ -9214,7 +9445,7 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card 130
+ name: Credit Card 150
description:
type: bogus
session_required: true
@@ -9295,7 +9526,7 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method:
id: pm_UkLWZg9DAJ
- name: Credit Card 132
+ name: Credit Card 152
description:
type: bogus
session_required: true
@@ -10694,7 +10925,7 @@ paths:
variant:
id: variant_gbHJdmfrXB
product_id: prod_gbHJdmfrXB
- sku: SKU-436
+ sku: SKU-462
options_text: ''
track_inventory: true
media_count: 0
@@ -11684,6 +11915,99 @@ paths:
required:
- customer_email
+ "/api/v3/store/companies/{company_id}/invitations":
+ parameters:
+ - name: company_id
+ in: path
+ required: true
+ description: Company node ID (comp_...)
+ schema:
+ type: string
+ get:
+ summary: List pending company invitations
+ tags:
+ - Companies
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: The invitations to this node that nobody has accepted or revoked
+ yet. Requires standing over the node.
+ 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
+
+ Filter 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/store-api/querying#which-filters-an-endpoint-accepts).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `email` | Text | `eq` `not_eq` `in` `not_in` `cont` `i_cont` `not_cont` `start` `end` `null` `not_null` `present` `blank` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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 listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: cinv_UkLWZg9DAJ
+ expires_at: '2026-02-14T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ status: pending
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/CompanyInvitation"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
"/api/v3/store/companies/{company_id}/addresses":
parameters:
- name: company_id
@@ -11773,7 +12097,7 @@ paths:
first_name:
last_name:
full_name: ''
- address1: 278 Lovely Street
+ address1: 312 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -11844,7 +12168,7 @@ paths:
first_name:
last_name:
full_name: ''
- address1: 281 Lovely Street
+ address1: 315 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -12108,8 +12432,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2525649
- slug: product-2525649
+ name: Product 2715649
+ slug: product-2715649
options_text: ''
price: '10.00'
display_price: "$10.00"
@@ -12171,8 +12495,8 @@ paths:
delivered_at:
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 114
- code: UPS_GROUND_131
+ name: UPS Ground 129
+ code: UPS_GROUND_146
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -12193,7 +12517,7 @@ paths:
delivery_rates:
- id: dr_gbHJdmfrXB
delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground 114
+ name: UPS Ground 129
selected: true
cost: '10.00'
total: '10.00'
@@ -12212,8 +12536,8 @@ paths:
display_tax_total: "$0.00"
delivery_method:
id: dm_UkLWZg9DAJ
- name: UPS Ground 114
- code: UPS_GROUND_131
+ name: UPS Ground 129
+ code: UPS_GROUND_146
estimated_transit_business_days_min:
estimated_transit_business_days_max:
digital: false
@@ -12226,7 +12550,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 289 Lovely Street
+ address1: 323 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -12248,7 +12572,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 290 Lovely Street
+ address1: 324 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -12566,6 +12890,93 @@ paths:
state_text: AL
pickup_ready_in_minutes:
pickup_instructions:
+ "/api/v3/store/customers/me/digital_links":
+ get:
+ summary: List my digital links
+ tags:
+ - Digital Links
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: The signed-in customer's downloads in this store, newest first.
+ 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
+
+ Filter 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/store-api/querying#which-filters-an-endpoint-accepts).
+
+ | Attribute | Kind | Predicates |
+ |---|---|---|
+ | `created_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+ | `id` | Prefixed ID | `eq` `not_eq` `in` `not_in` `null` `not_null` |
+ | `updated_at` | Date and time | `eq` `not_eq` `in` `not_in` `lt` `lteq` `gt` `gteq` `null` `not_null` |
+
+ **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 listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: dl_UkLWZg9DAJ
+ access_counter: 0
+ filename: thinking-cat.jpg
+ content_type: image/jpeg
+ download_url: "/api/v3/store/digital_links/PyFLkSrH72mE2GaBLUeZnXXF"
+ expires_at: '2026-01-22T12:00:00Z'
+ authorizable: true
+ expired: false
+ access_limit_exceeded: false
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/DigitalLink"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
"/api/v3/store/digital_links/{token}":
get:
summary: Download a digital product
@@ -13853,7 +14264,9 @@ components:
type: string
nullable: true
ancestors:
- type: object
+ type: array
+ items:
+ type: object
required:
- id
- name
@@ -13956,8 +14369,7 @@ components:
- json
key:
type: string
- value:
- type: object
+ value: {}
required:
- id
- label
@@ -16294,7 +16706,9 @@ components:
total_count:
type: number
filters:
- type: object
+ type: array
+ items:
+ type: object
sort_options:
type: array
items:
@@ -17399,6 +17813,22 @@ components:
associations: {}
scopes:
search: text
+ Claim:
+ attributes:
+ created_at: datetime
+ id: id
+ number: text
+ status:
+ enum:
+ - open
+ - approved
+ - resolved
+ - denied
+ - canceled
+ updated_at: datetime
+ associations: {}
+ scopes:
+ search: text
Collection:
attributes:
automatic: boolean
@@ -17422,6 +17852,14 @@ components:
associations: {}
scopes:
search: text
+ CompanyInvitation:
+ attributes:
+ created_at: datetime
+ email: text
+ id: id
+ updated_at: datetime
+ associations: {}
+ scopes: {}
CompanyMembership:
attributes:
created_at: datetime
@@ -17473,6 +17911,13 @@ components:
associations: {}
scopes:
search: text
+ DigitalLink:
+ attributes:
+ created_at: datetime
+ id: id
+ updated_at: datetime
+ associations: {}
+ scopes: {}
GiftCard:
attributes:
code: text
@@ -17635,6 +18080,22 @@ components:
search_by_name: text
with_option_value_ids:
list: id
+ Return:
+ attributes:
+ created_at: datetime
+ id: id
+ number: text
+ status:
+ enum:
+ - requested
+ - approved
+ - received
+ - refunded
+ - canceled
+ updated_at: datetime
+ associations: {}
+ scopes:
+ search: text
Seller:
attributes:
created_at: datetime
diff --git a/docs/plans/6.0-typed-filters.md b/docs/plans/6.0-typed-filters.md
index 396ae1a8d1..00ae80a774 100644
--- a/docs/plans/6.0-typed-filters.md
+++ b/docs/plans/6.0-typed-filters.md
@@ -1,6 +1,6 @@
# Typed Filters from Ransack Declarations
-**Status:** In Progress — PR A (filter tables, filters in OpenAPI, generated SDK filter and sort types) being built 2026-10-09; PR B and PR C not started
+**Status:** In Progress — PR A merged 2026-10-09 (#14854); its follow-ups (every filterable list endpoint documented and typed, `spree filters types` writing every app's file) in progress; PR B and PR C not started
**Target:** Spree 6.0
**Depends on:** `6.0-money-correctness.md` (amounts are decimal strings on the wire, in filters too).
**Author:** Damian + Claude
@@ -135,7 +135,7 @@ Verification per PR: `pnpm test:changed`, then `pnpm test:rspec api`; `pnpm type
## Constraints on Current Work
-- A list endpoint without an integration spec has no filter table in OpenAPI, so its SDK method keeps loose parameters. 44 endpoints are in that state (claims, returns, exchanges, variants, order groups, nested custom fields and others); each one gains typed filters when it gains an integration spec with `filter_parameters_for`.
+- Every filterable list endpoint has an integration spec with `filter_parameters_for` (done 2026-10-09 for the 44 that lacked one). A new list endpoint needs one too, or its SDK method has no filter types; an endpoint that is not a Ransack listing (a registry, a fixed set) declares `filterable?` false instead.
- Declare filterable attributes, associations and scopes on the model allowlists only. Never parse `params[:q]` by hand in a controller; add a scope instead.
- A new scope taking an argument adds its types to `ransackable_scope_types`.
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index e64e53f5a4..44fcb16d40 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -27,8 +27,10 @@ import type {
CategorySort,
ChannelFilters,
ChannelSort,
+ ClaimFilters,
ClaimReasonFilters,
ClaimReasonSort,
+ ClaimSort,
CollectionFilters,
CollectionSort,
CommissionLineFilters,
@@ -36,6 +38,8 @@ import type {
CommissionRateFilters,
CommissionRateSort,
CompanyFilters,
+ CompanyInvitationFilters,
+ CompanyInvitationSort,
CompanyMembershipFilters,
CompanyMembershipSort,
CompanySort,
@@ -49,14 +53,26 @@ import type {
CustomerSort,
CustomFieldDefinitionFilters,
CustomFieldDefinitionSort,
+ CustomFieldFilters,
+ CustomFieldSort,
DeliveryMethodFilters,
DeliveryMethodSort,
DeliveryProfileFilters,
DeliveryProfileSort,
+ DeliveryZoneFilters,
+ DeliveryZoneSort,
+ DigitalAssetFilters,
+ DigitalAssetSort,
+ DigitalLinkFilters,
+ DigitalLinkSort,
DiscountFilters,
DiscountSort,
+ ExchangeFilters,
+ ExchangeSort,
ExportFilters,
ExportSort,
+ FeeFilters,
+ FeeSort,
FulfillmentFilters,
FulfillmentSort,
GiftCardBatchFilters,
@@ -82,6 +98,8 @@ import type {
OrderCancellationReasonFilters,
OrderCancellationReasonSort,
OrderFilters,
+ OrderGroupFilters,
+ OrderGroupSort,
OrderRoutingRuleFilters,
OrderRoutingRuleSort,
OrderSort,
@@ -97,8 +115,10 @@ import type {
PriceListFilters,
PriceListSort,
PriceSort,
+ ProductFilters,
ProductSearchFilters,
ProductSearchSort,
+ ProductSort,
ProductTypeFilters,
ProductTypeSort,
PromotionActionFilters,
@@ -113,14 +133,24 @@ import type {
RefundReasonFilters,
RefundReasonSort,
RefundSort,
+ ReturnFilters,
ReturnReasonFilters,
ReturnReasonSort,
+ ReturnSort,
RoleFilters,
RoleSort,
+ SavedReportFilters,
+ SavedReportSort,
SellerFilters,
+ SellerPayoutFilters,
+ SellerPayoutSort,
SellerRequirementFilters,
SellerRequirementSort,
+ SellerRequirementSubmissionFilters,
+ SellerRequirementSubmissionSort,
SellerSort,
+ SellerTransferFilters,
+ SellerTransferSort,
StockLevelFilters,
StockLevelSort,
StockLocationFilters,
@@ -135,6 +165,8 @@ import type {
StoreCreditSort,
SupplierFilters,
SupplierSort,
+ TaxCategoryFilters,
+ TaxCategorySort,
TaxExemptionCertificateFilters,
TaxExemptionCertificateSort,
TaxIdentifierFilters,
@@ -713,7 +745,7 @@ export class AdminClient {
return {
list: (
parentId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<CustomFieldFilters, CustomFieldSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CustomField>> =>
this.request<PaginatedResponse<CustomField>>(
@@ -786,7 +818,7 @@ export class AdminClient {
*/
list: (
parentId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ProductFilters, ProductSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Row>> =>
this.request<PaginatedResponse<Row>>('GET', `${basePath}/${parentId}/products`, {
@@ -859,7 +891,7 @@ export class AdminClient {
}
const scoped = this.parentScopedCustomFields(ownerPath)
return {
- list: (params?: ListParams & Record<string, unknown>, options?: RequestOptions) =>
+ list: (params?: ListParams<CustomFieldFilters, CustomFieldSort>, options?: RequestOptions) =>
scoped.list(ownerId, params, options),
get: (id: string, options?: RequestOptions) => scoped.get(ownerId, id, options),
create: (params: CustomFieldCreateParams, options?: RequestOptions) =>
@@ -1068,7 +1100,7 @@ export class AdminClient {
/** Store-wide saved reports: a contract query plus visualization config. */
savedReports: {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<SavedReportFilters, SavedReportSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SavedReport>> =>
this.request<PaginatedResponse<SavedReport>>('GET', '/reporting/saved_reports', {
@@ -1328,7 +1360,7 @@ export class AdminClient {
media: {
list: (
productId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<MediaFilters, MediaSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Media>> =>
this.request<PaginatedResponse<Media>>('GET', `/products/${productId}/media`, {
@@ -1361,7 +1393,7 @@ export class AdminClient {
digitalAssets: {
list: (
productId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<DigitalAssetFilters, DigitalAssetSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DigitalAsset>> =>
this.request<PaginatedResponse<DigitalAsset>>(
@@ -1463,7 +1495,7 @@ export class AdminClient {
list: (
productId: string,
variantId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<MediaFilters, MediaSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Media>> =>
this.request<PaginatedResponse<Media>>(
@@ -1527,7 +1559,7 @@ export class AdminClient {
*/
readonly digitalLinks = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<DigitalLinkFilters, DigitalLinkSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DigitalLink>> =>
this.request<PaginatedResponse<DigitalLink>>('GET', '/digital_links', {
@@ -1932,7 +1964,7 @@ export class AdminClient {
returns: {
list: (
orderId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ReturnFilters, ReturnSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Return>> =>
this.request<PaginatedResponse<Return>>('GET', `/orders/${orderId}/returns`, {
@@ -2082,7 +2114,7 @@ export class AdminClient {
exchanges: {
list: (
orderId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ExchangeFilters, ExchangeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Exchange>> =>
this.request<PaginatedResponse<Exchange>>('GET', `/orders/${orderId}/exchanges`, {
@@ -2162,7 +2194,7 @@ export class AdminClient {
claims: {
list: (
orderId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ClaimFilters, ClaimSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Claim>> =>
this.request<PaginatedResponse<Claim>>('GET', `/orders/${orderId}/claims`, {
@@ -2389,7 +2421,7 @@ export class AdminClient {
fees: {
list: (
orderId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<FeeFilters, FeeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Fee>> =>
this.request<PaginatedResponse<Fee>>('GET', `/orders/${orderId}/fees`, {
@@ -2708,7 +2740,7 @@ export class AdminClient {
readonly deliveryZones = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<DeliveryZoneFilters, DeliveryZoneSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DeliveryZone>> =>
this.request<PaginatedResponse<DeliveryZone>>('GET', '/delivery_zones', {
@@ -3313,7 +3345,7 @@ export class AdminClient {
requirementSubmissions: {
list: (
sellerId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<SellerRequirementSubmissionFilters, SellerRequirementSubmissionSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SellerRequirementSubmission>> =>
this.request<PaginatedResponse<SellerRequirementSubmission>>(
@@ -3536,7 +3568,7 @@ export class AdminClient {
*/
readonly orderGroups = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<OrderGroupFilters, OrderGroupSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<OrderGroup>> =>
this.request<PaginatedResponse<OrderGroup>>('GET', '/order_groups', {
@@ -3566,7 +3598,7 @@ export class AdminClient {
*/
readonly sellerTransfers = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<SellerTransferFilters, SellerTransferSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SellerTransfer>> =>
this.request<PaginatedResponse<SellerTransfer>>('GET', '/seller_transfers', {
@@ -3593,7 +3625,7 @@ export class AdminClient {
*/
readonly sellerPayouts = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<SellerPayoutFilters, SellerPayoutSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<SellerPayout>> =>
this.request<PaginatedResponse<SellerPayout>>('GET', '/seller_payouts', {
@@ -3725,7 +3757,7 @@ export class AdminClient {
readonly returns = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ReturnFilters, ReturnSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Return>> =>
this.request<PaginatedResponse<Return>>('GET', '/returns', {
@@ -3742,7 +3774,7 @@ export class AdminClient {
readonly exchanges = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ExchangeFilters, ExchangeSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Exchange>> =>
this.request<PaginatedResponse<Exchange>>('GET', '/exchanges', {
@@ -3763,7 +3795,7 @@ export class AdminClient {
readonly claims = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ClaimFilters, ClaimSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Claim>> =>
this.request<PaginatedResponse<Claim>>('GET', '/claims', {
@@ -3907,7 +3939,7 @@ export class AdminClient {
addresses: {
list: (
companyId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<AddressFilters, AddressSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Address>> =>
this.request<PaginatedResponse<Address>>('GET', `/companies/${companyId}/addresses`, {
@@ -3988,7 +4020,7 @@ export class AdminClient {
invitations: {
list: (
companyId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<CompanyInvitationFilters, CompanyInvitationSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CompanyInvitation>> =>
this.request<PaginatedResponse<CompanyInvitation>>(
@@ -4580,7 +4612,7 @@ export class AdminClient {
taxIdentifiers: {
list: (
customerId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<TaxIdentifierFilters, TaxIdentifierSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<TaxIdentifier>> =>
this.request<PaginatedResponse<TaxIdentifier>>(
@@ -4859,7 +4891,7 @@ export class AdminClient {
readonly variants = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<VariantFilters, VariantSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Variant>> =>
this.request<PaginatedResponse<Variant>>('GET', '/variants', {
@@ -4924,7 +4956,7 @@ export class AdminClient {
readonly taxCategories = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<TaxCategoryFilters, TaxCategorySort>,
options?: RequestOptions,
): Promise<PaginatedResponse<TaxCategory>> =>
this.request<PaginatedResponse<TaxCategory>>('GET', '/tax_categories', {
diff --git a/packages/admin-sdk/src/types/filters.generated.ts b/packages/admin-sdk/src/types/filters.generated.ts
index ae7deaa03a..d3539d1995 100644
--- a/packages/admin-sdk/src/types/filters.generated.ts
+++ b/packages/admin-sdk/src/types/filters.generated.ts
@@ -38,6 +38,11 @@ export type ChannelFields = Filter.BooleanFilters<'active' | 'default'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id' | 'store_id'>
+export type ClaimFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.TextFilters<'number'>
+ & Filter.EnumFilters<'status', 'open' | 'approved' | 'resolved' | 'denied' | 'canceled'>
+
export type ClaimReasonFields = Filter.BooleanFilters<'active'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
@@ -71,9 +76,19 @@ export type CompanyFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.BooleanFilters<'po_number_required'>
& Filter.EnumFilters<'kind', 'company' | 'division'>
+export type CompanyInvitationFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.TextFilters<'email'>
+ & Filter.IdFilters<'id'>
+
export type CompanyMembershipFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
+export type ConsentRecordFields = Filter.BooleanFilters<'accepted'>
+ & Filter.RangeFilters<'created_at' | 'recorded_at' | 'updated_at'>
+ & Filter.TextFilters<'email' | 'purpose'>
+ & Filter.IdFilters<'id'>
+ & Filter.EnumFilters<'source', 'checkout' | 'registration' | 'account' | 'admin' | 'newsletter' | 'anonymization' | 'unknown' | 'import' | 'storefront'>
+
export type CouponCodeFields = Filter.TextFilters<'code'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id' | 'promotion_id'>
@@ -100,6 +115,12 @@ export type CustomerGroupFields = Filter.RangeFilters<'created_at' | 'updated_at
& Filter.IdFilters<'id'>
& Filter.TextFilters<'name'>
+export type DataRequestFields = Filter.RangeFilters<'completed_at' | 'created_at' | 'requested_at' | 'updated_at'>
+ & Filter.TextFilters<'email' | 'number'>
+ & Filter.IdFilters<'id'>
+ & Filter.EnumFilters<'kind', 'access' | 'erasure'>
+ & Filter.EnumFilters<'status', 'pending' | 'processing' | 'completed' | 'failed'>
+
export type DeliveryFields = Filter.TextFilters<'carrier' | 'tracking_number'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
@@ -110,17 +131,40 @@ export type DeliveryMethodFields = Filter.BooleanFilters<'available_to_sellers'
& Filter.IdFilters<'id' | 'seller_id'>
& Filter.TextFilters<'name'>
+export type DeliveryMethodRuleFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+
+export type DeliveryOriginGroupFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.TextFilters<'name'>
+ & Filter.RangeFilters<'position', number>
+
export type DeliveryProfileFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'name'>
& Filter.RangeFilters<'position', number>
+export type DeliveryZoneFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'delivery_profile_id' | 'id'>
+ & Filter.TextFilters<'name'>
+
+export type DigitalAssetFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+
+export type DigitalLinkFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+
export type DiscountFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
export type EmailTemplateRevisionFields = Filter.RangeFilters<'created_at'>
& Filter.IdFilters<'id'>
+export type ExchangeFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.TextFilters<'number'>
+ & Filter.EnumFilters<'status', 'requested' | 'approved' | 'received' | 'fulfilled' | 'canceled'>
+
export type ExportFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id' | 'seller_id' | 'type'>
& Filter.TextFilters<'number'>
@@ -130,6 +174,9 @@ export type ExternalReferenceFields = Filter.RangeFilters<'created_at' | 'update
& Filter.TextFilters<'external_id' | 'system'>
& Filter.IdFilters<'id' | 'resource_type'>
+export type FeeFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+
export type FulfillmentFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'number'>
@@ -287,6 +334,11 @@ export type RefundReasonFields = Filter.BooleanFilters<'active'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'name'>
+export type ReturnFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.TextFilters<'number'>
+ & Filter.EnumFilters<'status', 'requested' | 'approved' | 'received' | 'refunded' | 'canceled'>
+
export type ReturnReasonFields = Filter.BooleanFilters<'active'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
@@ -296,16 +348,36 @@ export type RoleFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'name'>
+export type SavedReportFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.TextFilters<'name'>
+ & Filter.BooleanFilters<'seeded'>
+
export type SellerFields = Filter.TextFilters<'contact_email' | 'name'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
& Filter.EnumFilters<'status', 'pending' | 'invited' | 'canceled' | 'onboarding' | 'ready_for_review' | 'approved' | 'rejected' | 'suspended'>
+export type SellerPayoutFields = Filter.RangeFilters<'amount' | 'created_at' | 'period_end' | 'period_start' | 'updated_at'>
+ & Filter.TextFilters<'currency' | 'provider' | 'reference'>
+ & Filter.IdFilters<'id' | 'seller_id'>
+ & Filter.EnumFilters<'status', 'pending' | 'processing' | 'completed' | 'failed' | 'unresolved'>
+
export type SellerRequirementFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'name'>
& Filter.RangeFilters<'position', number>
+export type SellerRequirementSubmissionFields = Filter.RangeFilters<'created_at' | 'reviewed_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.EnumFilters<'status', 'pending' | 'accepted' | 'rejected' | 'waived'>
+
+export type SellerTransferFields = Filter.RangeFilters<'amount' | 'created_at' | 'updated_at'>
+ & Filter.TextFilters<'currency' | 'provider' | 'reference'>
+ & Filter.IdFilters<'id' | 'order_id' | 'payout_id' | 'seller_id'>
+ & Filter.EnumFilters<'kind', 'earning' | 'refund_reversal'>
+ & Filter.EnumFilters<'status', 'pending' | 'processing' | 'completed' | 'failed' | 'unresolved'>
+
export type ShippingLabelFields = Filter.TextFilters<'carrier' | 'tracking_number'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
@@ -331,6 +403,10 @@ export type StockReceiptFields = Filter.RangeFilters<'created_at' | 'received_at
& Filter.IdFilters<'id' | 'receivable_id' | 'receivable_type' | 'received_by_id' | 'received_by_type'>
& Filter.TextFilters<'number' | 'reference'>
+export type StockReservationFields = Filter.RangeFilters<'created_at' | 'expires_at' | 'updated_at'>
+ & Filter.IdFilters<'id' | 'line_item_id' | 'order_id' | 'stock_item_id' | 'stock_level_id'>
+ & Filter.RangeFilters<'quantity', number>
+
export type StockTransferFields = Filter.RangeFilters<'closed_short_at' | 'created_at' | 'received_at' | 'shipped_at' | 'updated_at'>
& Filter.IdFilters<'destination_location_id' | 'id' | 'source_location_id'>
& Filter.TextFilters<'number' | 'reference'>
@@ -574,6 +650,31 @@ export type ChannelFilters = ChannelFields
export type ChannelSort = Filter.SortKey<'active' | 'code' | 'created_at' | 'default' | 'id' | 'name' | 'store_id' | 'updated_at' | (keyof ChannelSortExtensions & string)>
+/**
+ * Filters your app adds to Claim lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface ClaimFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ClaimFilterExtensions {}
+
+/** Sort fields your app adds to Claim lists, as keys: `{ erp_id: true }`. */
+export interface ClaimSortExtensions {}
+
+export type ClaimFilters = ClaimFields
+ & Filter.Prefixed<'order_', OrderFields & Filter.Prefixed<'bill_address_', AddressFields> & Filter.Prefixed<'channel_', ChannelFields> & Filter.Prefixed<'customer_', CustomerFields> & Filter.Prefixed<'fulfillments_', FulfillmentFields> & Filter.Prefixed<'line_items_', LineItemFields> & Filter.Prefixed<'order_group_', OrderGroupFields> & Filter.Prefixed<'promotions_', PromotionFields> & Filter.Prefixed<'seller_', SellerFields> & Filter.Prefixed<'ship_address_', AddressFields> & Filter.Prefixed<'shipments_', FulfillmentFields> & Filter.Prefixed<'store_', StoreFields> & Filter.Prefixed<'tags_', TagFields>>
+ & Filter.Prefixed<'reason_', ClaimReasonFields>
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & ClaimFilterExtensions
+
+export type ClaimSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'status' | 'updated_at' | (keyof ClaimSortExtensions & string)>
+
/**
* Filters your app adds to ClaimReason lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -690,6 +791,26 @@ export type CompanyFilters = CompanyFields
export type CompanySort = Filter.SortKey<'created_at' | 'id' | 'kind' | 'name' | 'parent_id' | 'po_number_required' | 'updated_at' | (keyof CompanySortExtensions & string)>
+/**
+ * Filters your app adds to CompanyInvitation lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface CompanyInvitationFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface CompanyInvitationFilterExtensions {}
+
+/** Sort fields your app adds to CompanyInvitation lists, as keys: `{ erp_id: true }`. */
+export interface CompanyInvitationSortExtensions {}
+
+export type CompanyInvitationFilters = CompanyInvitationFields
+ & Filter.OrFilters
+ & CompanyInvitationFilterExtensions
+
+export type CompanyInvitationSort = Filter.SortKey<'created_at' | 'email' | 'id' | 'updated_at' | (keyof CompanyInvitationSortExtensions & string)>
+
/**
* Filters your app adds to CompanyMembership lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -710,6 +831,26 @@ export type CompanyMembershipFilters = CompanyMembershipFields
export type CompanyMembershipSort = Filter.SortKey<'created_at' | 'id' | 'updated_at' | (keyof CompanyMembershipSortExtensions & string)>
+/**
+ * Filters your app adds to ConsentRecord lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface ConsentRecordFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ConsentRecordFilterExtensions {}
+
+/** Sort fields your app adds to ConsentRecord lists, as keys: `{ erp_id: true }`. */
+export interface ConsentRecordSortExtensions {}
+
+export type ConsentRecordFilters = ConsentRecordFields
+ & Filter.OrFilters
+ & ConsentRecordFilterExtensions
+
+export type ConsentRecordSort = Filter.SortKey<'accepted' | 'created_at' | 'email' | 'id' | 'purpose' | 'recorded_at' | 'source' | 'updated_at' | (keyof ConsentRecordSortExtensions & string)>
+
/**
* Filters your app adds to CouponCode lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -850,6 +991,31 @@ export type CustomFieldDefinitionFilters = CustomFieldDefinitionFields
export type CustomFieldDefinitionSort = Filter.SortKey<'created_at' | 'field_type' | 'id' | 'key' | 'label' | 'namespace' | 'resource_type' | 'searchable' | 'sortable' | 'storefront_visible' | 'updated_at' | (keyof CustomFieldDefinitionSortExtensions & string)>
+/**
+ * Filters your app adds to DataRequest lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface DataRequestFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DataRequestFilterExtensions {}
+
+/** Sort fields your app adds to DataRequest lists, as keys: `{ erp_id: true }`. */
+export interface DataRequestSortExtensions {}
+
+export type DataRequestFilters = DataRequestFields
+ & {
+ access?: boolean
+ erasure?: boolean
+ in_progress?: boolean
+ }
+ & Filter.OrFilters
+ & DataRequestFilterExtensions
+
+export type DataRequestSort = Filter.SortKey<'completed_at' | 'created_at' | 'email' | 'id' | 'kind' | 'number' | 'requested_at' | 'status' | 'updated_at' | (keyof DataRequestSortExtensions & string)>
+
/**
* Filters your app adds to Delivery lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -894,6 +1060,46 @@ export type DeliveryMethodFilters = DeliveryMethodFields
export type DeliveryMethodSort = Filter.SortKey<'available_to_sellers' | 'created_at' | 'id' | 'name' | 'seller_id' | 'storefront_visible' | 'updated_at' | (keyof DeliveryMethodSortExtensions & string)>
+/**
+ * Filters your app adds to DeliveryMethodRule lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface DeliveryMethodRuleFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DeliveryMethodRuleFilterExtensions {}
+
+/** Sort fields your app adds to DeliveryMethodRule lists, as keys: `{ erp_id: true }`. */
+export interface DeliveryMethodRuleSortExtensions {}
+
+export type DeliveryMethodRuleFilters = DeliveryMethodRuleFields
+ & Filter.OrFilters
+ & DeliveryMethodRuleFilterExtensions
+
+export type DeliveryMethodRuleSort = Filter.SortKey<'created_at' | 'id' | 'updated_at' | (keyof DeliveryMethodRuleSortExtensions & string)>
+
+/**
+ * Filters your app adds to DeliveryOriginGroup lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface DeliveryOriginGroupFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DeliveryOriginGroupFilterExtensions {}
+
+/** Sort fields your app adds to DeliveryOriginGroup lists, as keys: `{ erp_id: true }`. */
+export interface DeliveryOriginGroupSortExtensions {}
+
+export type DeliveryOriginGroupFilters = DeliveryOriginGroupFields
+ & Filter.OrFilters
+ & DeliveryOriginGroupFilterExtensions
+
+export type DeliveryOriginGroupSort = Filter.SortKey<'created_at' | 'id' | 'name' | 'position' | 'updated_at' | (keyof DeliveryOriginGroupSortExtensions & string)>
+
/**
* Filters your app adds to DeliveryProfile lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -917,6 +1123,66 @@ export type DeliveryProfileFilters = DeliveryProfileFields
export type DeliveryProfileSort = Filter.SortKey<'created_at' | 'id' | 'name' | 'position' | 'updated_at' | (keyof DeliveryProfileSortExtensions & string)>
+/**
+ * Filters your app adds to DeliveryZone lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface DeliveryZoneFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DeliveryZoneFilterExtensions {}
+
+/** Sort fields your app adds to DeliveryZone lists, as keys: `{ erp_id: true }`. */
+export interface DeliveryZoneSortExtensions {}
+
+export type DeliveryZoneFilters = DeliveryZoneFields
+ & Filter.OrFilters
+ & DeliveryZoneFilterExtensions
+
+export type DeliveryZoneSort = Filter.SortKey<'created_at' | 'delivery_profile_id' | 'id' | 'name' | 'updated_at' | (keyof DeliveryZoneSortExtensions & string)>
+
+/**
+ * Filters your app adds to DigitalAsset lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface DigitalAssetFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DigitalAssetFilterExtensions {}
+
+/** Sort fields your app adds to DigitalAsset lists, as keys: `{ erp_id: true }`. */
+export interface DigitalAssetSortExtensions {}
+
+export type DigitalAssetFilters = DigitalAssetFields
+ & Filter.OrFilters
+ & DigitalAssetFilterExtensions
+
+export type DigitalAssetSort = Filter.SortKey<'created_at' | 'id' | 'updated_at' | (keyof DigitalAssetSortExtensions & string)>
+
+/**
+ * Filters your app adds to DigitalLink lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface DigitalLinkFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DigitalLinkFilterExtensions {}
+
+/** Sort fields your app adds to DigitalLink lists, as keys: `{ erp_id: true }`. */
+export interface DigitalLinkSortExtensions {}
+
+export type DigitalLinkFilters = DigitalLinkFields
+ & Filter.OrFilters
+ & DigitalLinkFilterExtensions
+
+export type DigitalLinkSort = Filter.SortKey<'created_at' | 'id' | 'updated_at' | (keyof DigitalLinkSortExtensions & string)>
+
/**
* Filters your app adds to Discount lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -957,6 +1223,31 @@ export type EmailTemplateRevisionFilters = EmailTemplateRevisionFields
export type EmailTemplateRevisionSort = Filter.SortKey<'created_at' | 'id' | (keyof EmailTemplateRevisionSortExtensions & string)>
+/**
+ * Filters your app adds to Exchange lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface ExchangeFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ExchangeFilterExtensions {}
+
+/** Sort fields your app adds to Exchange lists, as keys: `{ erp_id: true }`. */
+export interface ExchangeSortExtensions {}
+
+export type ExchangeFilters = ExchangeFields
+ & Filter.Prefixed<'order_', OrderFields & Filter.Prefixed<'bill_address_', AddressFields> & Filter.Prefixed<'channel_', ChannelFields> & Filter.Prefixed<'customer_', CustomerFields> & Filter.Prefixed<'fulfillments_', FulfillmentFields> & Filter.Prefixed<'line_items_', LineItemFields> & Filter.Prefixed<'order_group_', OrderGroupFields> & Filter.Prefixed<'promotions_', PromotionFields> & Filter.Prefixed<'seller_', SellerFields> & Filter.Prefixed<'ship_address_', AddressFields> & Filter.Prefixed<'shipments_', FulfillmentFields> & Filter.Prefixed<'store_', StoreFields> & Filter.Prefixed<'tags_', TagFields>>
+ & Filter.Prefixed<'reason_', ReturnReasonFields>
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & ExchangeFilterExtensions
+
+export type ExchangeSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'status' | 'updated_at' | (keyof ExchangeSortExtensions & string)>
+
/**
* Filters your app adds to Export lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -978,6 +1269,26 @@ export type ExportFilters = ExportFields
export type ExportSort = Filter.SortKey<'created_at' | 'format' | 'id' | 'number' | 'seller_id' | 'type' | 'updated_at' | (keyof ExportSortExtensions & string)>
+/**
+ * Filters your app adds to Fee lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface FeeFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface FeeFilterExtensions {}
+
+/** Sort fields your app adds to Fee lists, as keys: `{ erp_id: true }`. */
+export interface FeeSortExtensions {}
+
+export type FeeFilters = FeeFields
+ & Filter.OrFilters
+ & FeeFilterExtensions
+
+export type FeeSort = Filter.SortKey<'created_at' | 'id' | 'updated_at' | (keyof FeeSortExtensions & string)>
+
/**
* Filters your app adds to Fulfillment lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -1287,6 +1598,28 @@ export type OrderCancellationReasonFilters = OrderCancellationReasonFields
export type OrderCancellationReasonSort = Filter.SortKey<'active' | 'created_at' | 'id' | 'name' | 'updated_at' | (keyof OrderCancellationReasonSortExtensions & string)>
+/**
+ * Filters your app adds to OrderGroup lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface OrderGroupFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface OrderGroupFilterExtensions {}
+
+/** Sort fields your app adds to OrderGroup lists, as keys: `{ erp_id: true }`. */
+export interface OrderGroupSortExtensions {}
+
+export type OrderGroupFilters = OrderGroupFields
+ & Filter.Prefixed<'customer_', CustomerFields & Filter.Prefixed<'addresses_', AddressFields> & Filter.Prefixed<'bill_address_', AddressFields> & Filter.Prefixed<'customer_groups_', CustomerGroupFields> & Filter.Prefixed<'orders_', OrderFields> & Filter.Prefixed<'ship_address_', AddressFields> & Filter.Prefixed<'spree_roles_', RoleFields> & Filter.Prefixed<'tags_', TagFields>>
+ & Filter.Prefixed<'orders_', OrderFields & Filter.Prefixed<'bill_address_', AddressFields> & Filter.Prefixed<'channel_', ChannelFields> & Filter.Prefixed<'customer_', CustomerFields> & Filter.Prefixed<'fulfillments_', FulfillmentFields> & Filter.Prefixed<'line_items_', LineItemFields> & Filter.Prefixed<'order_group_', OrderGroupFields> & Filter.Prefixed<'promotions_', PromotionFields> & Filter.Prefixed<'seller_', SellerFields> & Filter.Prefixed<'ship_address_', AddressFields> & Filter.Prefixed<'shipments_', FulfillmentFields> & Filter.Prefixed<'store_', StoreFields> & Filter.Prefixed<'tags_', TagFields>>
+ & Filter.OrFilters
+ & OrderGroupFilterExtensions
+
+export type OrderGroupSort = Filter.SortKey<'created_at' | 'currency' | 'email' | 'id' | 'number' | 'updated_at' | (keyof OrderGroupSortExtensions & string)>
+
/**
* Filters your app adds to OrderRoutingRule lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -1527,7 +1860,7 @@ export type ProductSearchFilters = ProductFields
with_option_value_ids?: string | string[]
}
& Filter.OrFilters
- & Filter.CustomFieldFilters
+ & Filter.CustomFieldValueFilters
& ProductFilterExtensions
export type ProductSearchSort = Filter.SortKey<'available_on' | 'best_selling' | 'created_at' | 'description' | 'discontinue_on' | 'id' | 'manual' | 'name' | 'price' | 'seller_id' | 'slug' | 'status' | 'updated_at' | (keyof ProductSortExtensions & string) | `cf_${string}`>
@@ -1690,6 +2023,31 @@ export type RefundReasonFilters = RefundReasonFields
export type RefundReasonSort = Filter.SortKey<'active' | 'created_at' | 'id' | 'name' | 'updated_at' | (keyof RefundReasonSortExtensions & string)>
+/**
+ * Filters your app adds to Return lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface ReturnFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ReturnFilterExtensions {}
+
+/** Sort fields your app adds to Return lists, as keys: `{ erp_id: true }`. */
+export interface ReturnSortExtensions {}
+
+export type ReturnFilters = ReturnFields
+ & Filter.Prefixed<'order_', OrderFields & Filter.Prefixed<'bill_address_', AddressFields> & Filter.Prefixed<'channel_', ChannelFields> & Filter.Prefixed<'customer_', CustomerFields> & Filter.Prefixed<'fulfillments_', FulfillmentFields> & Filter.Prefixed<'line_items_', LineItemFields> & Filter.Prefixed<'order_group_', OrderGroupFields> & Filter.Prefixed<'promotions_', PromotionFields> & Filter.Prefixed<'seller_', SellerFields> & Filter.Prefixed<'ship_address_', AddressFields> & Filter.Prefixed<'shipments_', FulfillmentFields> & Filter.Prefixed<'store_', StoreFields> & Filter.Prefixed<'tags_', TagFields>>
+ & Filter.Prefixed<'reason_', ReturnReasonFields>
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & ReturnFilterExtensions
+
+export type ReturnSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'status' | 'updated_at' | (keyof ReturnSortExtensions & string)>
+
/**
* Filters your app adds to ReturnReason lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -1730,6 +2088,29 @@ export type RoleFilters = RoleFields
export type RoleSort = Filter.SortKey<'created_at' | 'id' | 'name' | 'updated_at' | (keyof RoleSortExtensions & string)>
+/**
+ * Filters your app adds to SavedReport lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface SavedReportFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface SavedReportFilterExtensions {}
+
+/** Sort fields your app adds to SavedReport lists, as keys: `{ erp_id: true }`. */
+export interface SavedReportSortExtensions {}
+
+export type SavedReportFilters = SavedReportFields
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & SavedReportFilterExtensions
+
+export type SavedReportSort = Filter.SortKey<'created_at' | 'id' | 'name' | 'seeded' | 'updated_at' | (keyof SavedReportSortExtensions & string)>
+
/**
* Filters your app adds to Seller lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -1753,6 +2134,30 @@ export type SellerFilters = SellerFields
export type SellerSort = Filter.SortKey<'contact_email' | 'created_at' | 'id' | 'name' | 'status' | 'updated_at' | (keyof SellerSortExtensions & string)>
+/**
+ * Filters your app adds to SellerPayout lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface SellerPayoutFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface SellerPayoutFilterExtensions {}
+
+/** Sort fields your app adds to SellerPayout lists, as keys: `{ erp_id: true }`. */
+export interface SellerPayoutSortExtensions {}
+
+export type SellerPayoutFilters = SellerPayoutFields
+ & Filter.Prefixed<'seller_', SellerFields>
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & SellerPayoutFilterExtensions
+
+export type SellerPayoutSort = Filter.SortKey<'amount' | 'created_at' | 'currency' | 'id' | 'period_end' | 'period_start' | 'provider' | 'reference' | 'seller_id' | 'status' | 'updated_at' | (keyof SellerPayoutSortExtensions & string)>
+
/**
* Filters your app adds to SellerRequirement lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -1776,6 +2181,54 @@ export type SellerRequirementFilters = SellerRequirementFields
export type SellerRequirementSort = Filter.SortKey<'created_at' | 'id' | 'name' | 'position' | 'updated_at' | (keyof SellerRequirementSortExtensions & string)>
+/**
+ * Filters your app adds to SellerRequirementSubmission lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface SellerRequirementSubmissionFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface SellerRequirementSubmissionFilterExtensions {}
+
+/** Sort fields your app adds to SellerRequirementSubmission lists, as keys: `{ erp_id: true }`. */
+export interface SellerRequirementSubmissionSortExtensions {}
+
+export type SellerRequirementSubmissionFilters = SellerRequirementSubmissionFields
+ & Filter.Prefixed<'requirement_', SellerRequirementFields>
+ & Filter.Prefixed<'seller_', SellerFields>
+ & Filter.OrFilters
+ & SellerRequirementSubmissionFilterExtensions
+
+export type SellerRequirementSubmissionSort = Filter.SortKey<'created_at' | 'id' | 'reviewed_at' | 'status' | 'updated_at' | (keyof SellerRequirementSubmissionSortExtensions & string)>
+
+/**
+ * Filters your app adds to SellerTransfer lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface SellerTransferFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface SellerTransferFilterExtensions {}
+
+/** Sort fields your app adds to SellerTransfer lists, as keys: `{ erp_id: true }`. */
+export interface SellerTransferSortExtensions {}
+
+export type SellerTransferFilters = SellerTransferFields
+ & Filter.Prefixed<'payout_', SellerPayoutFields & Filter.Prefixed<'seller_', SellerFields>>
+ & Filter.Prefixed<'refund_', RefundFields>
+ & Filter.Prefixed<'seller_', SellerFields>
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & SellerTransferFilterExtensions
+
+export type SellerTransferSort = Filter.SortKey<'amount' | 'created_at' | 'currency' | 'id' | 'kind' | 'order_id' | 'payout_id' | 'provider' | 'reference' | 'seller_id' | 'status' | 'updated_at' | (keyof SellerTransferSortExtensions & string)>
+
/**
* Filters your app adds to ShippingLabel lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -1887,6 +2340,29 @@ export type StockReceiptFilters = StockReceiptFields
export type StockReceiptSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'receivable_id' | 'receivable_type' | 'received_at' | 'received_by_id' | 'received_by_type' | 'reference' | 'updated_at' | (keyof StockReceiptSortExtensions & string)>
+/**
+ * Filters your app adds to StockReservation lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface StockReservationFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface StockReservationFilterExtensions {}
+
+/** Sort fields your app adds to StockReservation lists, as keys: `{ erp_id: true }`. */
+export interface StockReservationSortExtensions {}
+
+export type StockReservationFilters = StockReservationFields
+ & Filter.Prefixed<'line_item_', LineItemFields & Filter.Prefixed<'order_', OrderFields> & Filter.Prefixed<'tax_category_', TaxCategoryFields> & Filter.Prefixed<'variant_', VariantFields>>
+ & Filter.Prefixed<'order_', OrderFields & Filter.Prefixed<'bill_address_', AddressFields> & Filter.Prefixed<'channel_', ChannelFields> & Filter.Prefixed<'customer_', CustomerFields> & Filter.Prefixed<'fulfillments_', FulfillmentFields> & Filter.Prefixed<'line_items_', LineItemFields> & Filter.Prefixed<'order_group_', OrderGroupFields> & Filter.Prefixed<'promotions_', PromotionFields> & Filter.Prefixed<'seller_', SellerFields> & Filter.Prefixed<'ship_address_', AddressFields> & Filter.Prefixed<'shipments_', FulfillmentFields> & Filter.Prefixed<'store_', StoreFields> & Filter.Prefixed<'tags_', TagFields>>
+ & Filter.Prefixed<'stock_level_', StockLevelFields & Filter.Prefixed<'stock_location_', StockLocationFields> & Filter.Prefixed<'variant_', VariantFields>>
+ & Filter.OrFilters
+ & StockReservationFilterExtensions
+
+export type StockReservationSort = Filter.SortKey<'created_at' | 'expires_at' | 'id' | 'line_item_id' | 'order_id' | 'quantity' | 'stock_item_id' | 'stock_level_id' | 'updated_at' | (keyof StockReservationSortExtensions & string)>
+
/**
* Filters your app adds to StockTransfer lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -1985,6 +2461,29 @@ export type SupplierFilters = SupplierFields
export type SupplierSort = Filter.SortKey<'city' | 'contact_name' | 'country_code' | 'created_at' | 'email' | 'id' | 'name' | 'phone' | 'updated_at' | (keyof SupplierSortExtensions & string)>
+/**
+ * Filters your app adds to TaxCategory lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/admin-sdk' {
+ * interface TaxCategoryFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface TaxCategoryFilterExtensions {}
+
+/** Sort fields your app adds to TaxCategory lists, as keys: `{ erp_id: true }`. */
+export interface TaxCategorySortExtensions {}
+
+export type TaxCategoryFilters = TaxCategoryFields
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & TaxCategoryFilterExtensions
+
+export type TaxCategorySort = Filter.SortKey<'created_at' | 'id' | 'is_default' | 'name' | 'tax_code' | 'updated_at' | (keyof TaxCategorySortExtensions & string)>
+
/**
* Filters your app adds to TaxExemptionCertificate lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index 410210d5ce..3925c0dc5b 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -3,7 +3,7 @@
// `spree filters types`).
export type {
BooleanFilters,
- CustomFieldFilters,
+ CustomFieldValueFilters,
EnumFilters,
ErrorResponse,
IdFilters,
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index c058942eb0..27258c0523 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/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/{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/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":{"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":{"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/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":{"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/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/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}/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_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/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/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}/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/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"}}],"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":{"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/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"}}],"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/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/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/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_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":"object","nullable":true},"seller_ids":{"type":"object","nullable":true},"category_ids":{"type":"object","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":"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":"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":{"type":"object"},"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":"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":"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":"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/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
diff --git a/packages/cli/src/generated/resource-paths.json b/packages/cli/src/generated/resource-paths.json
index 1e2429058f..8440739e72 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","/collection_rules","/collections","/commission_lines","/commission_rates","/companies","/custom_field_definitions","/customer_groups","/customers","/delivery_methods","/delivery_profiles","/delivery_zones","/email_templates","/exports","/gift_card_batches","/gift_cards","/imports","/integrations","/invitations","/locales","/markets","/me","/media","/option_types","/order_cancellation_reasons","/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","/return_reasons","/roles","/seller_payouts","/seller_requirements","/sellers","/stock_levels","/stock_locations","/stock_movements","/stock_transfers","/store","/store_credits","/suppliers","/tags","/tax_rates","/translatable_resources","/translations","/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","/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
diff --git a/packages/dashboard/src/hooks/use-digital-assets.ts b/packages/dashboard/src/hooks/use-digital-assets.ts
index f12bc0691e..0643100fb5 100644
--- a/packages/dashboard/src/hooks/use-digital-assets.ts
+++ b/packages/dashboard/src/hooks/use-digital-assets.ts
@@ -10,7 +10,7 @@ const digitalAssetsKey = (productId: string) => ['products', productId, 'digital
export function useDigitalAssets(productId: string, page = 1, enabled = true) {
return useQuery({
queryKey: useResourceKey('products', productId, 'digital-assets', page),
- queryFn: () => adminClient.products.digitalAssets.list(productId, { page, per_page: 25 }),
+ queryFn: () => adminClient.products.digitalAssets.list(productId, { page, limit: 25 }),
enabled: enabled && Boolean(productId),
})
}
diff --git a/packages/sdk-core/src/filter-types.ts b/packages/sdk-core/src/filter-types.ts
index 9e2f0b6c3d..07438b0053 100644
--- a/packages/sdk-core/src/filter-types.ts
+++ b/packages/sdk-core/src/filter-types.ts
@@ -201,7 +201,7 @@ export function renderFilterTypes(spec: FilterSpec, api: string): string {
const typeName =
search && groups.some((g) => g.table === name && !g.search) ? `${name}Search` : name
const parts = [...rootType(tables, name), 'Filter.OrFilters']
- if (search) parts.push('Filter.CustomFieldFilters')
+ if (search) parts.push('Filter.CustomFieldValueFilters')
const fields = [
...(sortable.size ? [union([...sortable].sort())] : []),
diff --git a/packages/sdk-core/src/filters.ts b/packages/sdk-core/src/filters.ts
index e15b921da2..21de59e43e 100644
--- a/packages/sdk-core/src/filters.ts
+++ b/packages/sdk-core/src/filters.ts
@@ -69,7 +69,7 @@ export type Prefixed<P extends string, T> = { [Key in keyof T as `${P}${Key & st
export type OrFilters = { [key: `${string}_or_${string}`]: string | string[] | boolean | undefined }
/** The store's searchable custom fields (`cf_<namespace>_<key>_<predicate>`), which vary per store. */
-export type CustomFieldFilters = {
+export type CustomFieldValueFilters = {
[key: `cf_${string}`]: string | number | boolean | string[] | undefined
}
diff --git a/packages/sdk-core/src/index.ts b/packages/sdk-core/src/index.ts
index 17578748d0..abfbbb0fbb 100644
--- a/packages/sdk-core/src/index.ts
+++ b/packages/sdk-core/src/index.ts
@@ -4,7 +4,7 @@ export type { FilterSpec } from './filter-types'
export { renderAppFilterTypes, renderFilterTypes } from './filter-types'
export type {
BooleanFilters,
- CustomFieldFilters,
+ CustomFieldValueFilters,
EnumFilters,
IdFilters,
OrFilters,
diff --git a/packages/sdk/src/store-client.ts b/packages/sdk/src/store-client.ts
index f05bc41925..c6eb3f47bc 100644
--- a/packages/sdk/src/store-client.ts
+++ b/packages/sdk/src/store-client.ts
@@ -16,11 +16,15 @@ import type {
CategoryListParams,
Channel,
Claim,
+ ClaimFilters,
+ ClaimSort,
Collection,
CollectionListParams,
Company,
CompanyAddressParams,
CompanyInvitation,
+ CompanyInvitationFilters,
+ CompanyInvitationSort,
CompanyMembership,
CompletePaymentSessionParams,
CompletePaymentSetupSessionParams,
@@ -34,6 +38,8 @@ import type {
Customer,
DeliveryMethod,
DigitalLink,
+ DigitalLinkFilters,
+ DigitalLinkSort,
GiftCard,
Locale,
LoginCredentials,
@@ -54,6 +60,8 @@ import type {
RequestPasswordResetParams,
ResetPasswordParams,
Return,
+ ReturnFilters,
+ ReturnSort,
Seller,
StockLocation,
StoreCredit,
@@ -779,7 +787,7 @@ export class StoreClient {
returns: {
list: (
orderId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ReturnFilters, ReturnSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Return>> =>
this.request<PaginatedResponse<Return>>('GET', `/orders/${orderId}/returns`, {
@@ -836,7 +844,7 @@ export class StoreClient {
claims: {
list: (
orderId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ClaimFilters, ClaimSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Claim>> =>
this.request<PaginatedResponse<Claim>>('GET', `/orders/${orderId}/claims`, {
@@ -1116,7 +1124,7 @@ export class StoreClient {
* List the customer's downloads, newest first.
*/
list: (
- params?: ListParams,
+ params?: ListParams<DigitalLinkFilters, DigitalLinkSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<DigitalLink>> =>
this.request<PaginatedResponse<DigitalLink>>('GET', '/customers/me/digital_links', {
@@ -1333,7 +1341,7 @@ export class StoreClient {
invitations: {
list: (
companyId: string,
- params?: ListParams,
+ params?: ListParams<CompanyInvitationFilters, CompanyInvitationSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<CompanyInvitation>> =>
this.request<PaginatedResponse<CompanyInvitation>>(
diff --git a/packages/sdk/src/types/filters.generated.ts b/packages/sdk/src/types/filters.generated.ts
index fa53f11fbd..8ef88c7e6d 100644
--- a/packages/sdk/src/types/filters.generated.ts
+++ b/packages/sdk/src/types/filters.generated.ts
@@ -12,6 +12,11 @@ export type CategoryFields = Filter.BooleanFilters<'automatic'>
& Filter.IdFilters<'id' | 'parent_id'>
& Filter.TextFilters<'name' | 'permalink' | 'pretty_name'>
+export type ClaimFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.TextFilters<'number'>
+ & Filter.EnumFilters<'status', 'open' | 'approved' | 'resolved' | 'denied' | 'canceled'>
+
export type CollectionFields = Filter.BooleanFilters<'automatic'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
@@ -19,6 +24,10 @@ export type CollectionFields = Filter.BooleanFilters<'automatic'>
& Filter.RangeFilters<'position' | 'products_count', number>
& Filter.EnumFilters<'sort_order', 'manual' | 'best_selling' | 'price asc' | 'price desc' | 'available_on desc' | 'available_on asc' | 'name asc' | 'name desc'>
+export type CompanyInvitationFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.TextFilters<'email'>
+ & Filter.IdFilters<'id'>
+
export type CompanyMembershipFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
@@ -37,6 +46,9 @@ export type DeliveryMethodFields = Filter.BooleanFilters<'available_to_sellers'
& Filter.IdFilters<'id' | 'seller_id'>
& Filter.TextFilters<'name'>
+export type DigitalLinkFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+
export type GiftCardFields = Filter.TextFilters<'code' | 'currency'>
& Filter.RangeFilters<'created_at' | 'expires_at' | 'updated_at'>
& Filter.IdFilters<'created_by_id' | 'customer_id' | 'gift_card_batch_id' | 'id'>
@@ -62,6 +74,11 @@ export type ProductFields = Filter.RangeFilters<'available_on' | 'created_at' |
& Filter.IdFilters<'id' | 'seller_id'>
& Filter.EnumFilters<'status', 'draft' | 'active' | 'archived' | 'proposed' | 'rejected'>
+export type ReturnFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.TextFilters<'number'>
+ & Filter.EnumFilters<'status', 'requested' | 'approved' | 'received' | 'refunded' | 'canceled'>
+
export type SellerFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'name'>
@@ -121,6 +138,29 @@ export type CategoryFilters = CategoryFields
export type CategorySort = Filter.SortKey<'automatic' | 'children_count' | 'created_at' | 'depth' | 'id' | 'name' | 'parent_id' | 'permalink' | 'position' | 'pretty_name' | 'products_count' | 'updated_at' | (keyof CategorySortExtensions & string)>
+/**
+ * Filters your app adds to Claim lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/sdk' {
+ * interface ClaimFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ClaimFilterExtensions {}
+
+/** Sort fields your app adds to Claim lists, as keys: `{ erp_id: true }`. */
+export interface ClaimSortExtensions {}
+
+export type ClaimFilters = ClaimFields
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & ClaimFilterExtensions
+
+export type ClaimSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'status' | 'updated_at' | (keyof ClaimSortExtensions & string)>
+
/**
* Filters your app adds to Collection lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -144,6 +184,26 @@ export type CollectionFilters = CollectionFields
export type CollectionSort = Filter.SortKey<'automatic' | 'created_at' | 'id' | 'name' | 'permalink' | 'position' | 'products_count' | 'sort_order' | 'updated_at' | (keyof CollectionSortExtensions & string)>
+/**
+ * Filters your app adds to CompanyInvitation lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/sdk' {
+ * interface CompanyInvitationFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface CompanyInvitationFilterExtensions {}
+
+/** Sort fields your app adds to CompanyInvitation lists, as keys: `{ erp_id: true }`. */
+export interface CompanyInvitationSortExtensions {}
+
+export type CompanyInvitationFilters = CompanyInvitationFields
+ & Filter.OrFilters
+ & CompanyInvitationFilterExtensions
+
+export type CompanyInvitationSort = Filter.SortKey<'created_at' | 'email' | 'id' | 'updated_at' | (keyof CompanyInvitationSortExtensions & string)>
+
/**
* Filters your app adds to CompanyMembership lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -232,6 +292,26 @@ export type DeliveryMethodFilters = DeliveryMethodFields
export type DeliveryMethodSort = Filter.SortKey<'available_to_sellers' | 'created_at' | 'id' | 'name' | 'seller_id' | 'storefront_visible' | 'updated_at' | (keyof DeliveryMethodSortExtensions & string)>
+/**
+ * Filters your app adds to DigitalLink lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/sdk' {
+ * interface DigitalLinkFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DigitalLinkFilterExtensions {}
+
+/** Sort fields your app adds to DigitalLink lists, as keys: `{ erp_id: true }`. */
+export interface DigitalLinkSortExtensions {}
+
+export type DigitalLinkFilters = DigitalLinkFields
+ & Filter.OrFilters
+ & DigitalLinkFilterExtensions
+
+export type DigitalLinkSort = Filter.SortKey<'created_at' | 'id' | 'updated_at' | (keyof DigitalLinkSortExtensions & string)>
+
/**
* Filters your app adds to GiftCard lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -344,11 +424,34 @@ export type ProductFilters = ProductFields
with_option_value_ids?: string | string[]
}
& Filter.OrFilters
- & Filter.CustomFieldFilters
+ & Filter.CustomFieldValueFilters
& ProductFilterExtensions
export type ProductSort = Filter.SortKey<'available_on' | 'best_selling' | 'created_at' | 'description' | 'discontinue_on' | 'id' | 'manual' | 'name' | 'price' | 'seller_id' | 'slug' | 'status' | 'updated_at' | (keyof ProductSortExtensions & string) | `cf_${string}`>
+/**
+ * Filters your app adds to Return lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/sdk' {
+ * interface ReturnFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ReturnFilterExtensions {}
+
+/** Sort fields your app adds to Return lists, as keys: `{ erp_id: true }`. */
+export interface ReturnSortExtensions {}
+
+export type ReturnFilters = ReturnFields
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & ReturnFilterExtensions
+
+export type ReturnSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'status' | 'updated_at' | (keyof ReturnSortExtensions & string)>
+
/**
* Filters your app adds to Seller lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
diff --git a/packages/sdk/src/types/index.ts b/packages/sdk/src/types/index.ts
index 18ae66694d..51debf13ba 100644
--- a/packages/sdk/src/types/index.ts
+++ b/packages/sdk/src/types/index.ts
@@ -325,7 +325,7 @@ export type CompanyAddressParams = AddressParams & {
// that extends them (see `spree filters types`).
export type {
BooleanFilters,
- CustomFieldFilters,
+ CustomFieldValueFilters,
EnumFilters,
IdFilters,
OrFilters,
diff --git a/packages/seller-sdk/src/seller-client.ts b/packages/seller-sdk/src/seller-client.ts
index a4a980eeef..7936181a2a 100644
--- a/packages/seller-sdk/src/seller-client.ts
+++ b/packages/seller-sdk/src/seller-client.ts
@@ -19,7 +19,11 @@ import type {
Export,
Fulfillment,
Import,
+ ImportFilters,
ImportRow,
+ ImportRowFilters,
+ ImportRowSort,
+ ImportSort,
Invitation,
InvitationAcceptanceLink,
Order,
@@ -1334,7 +1338,7 @@ export class SellerClient {
*/
readonly imports = {
list: (
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ImportFilters, ImportSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<Import>> =>
this.request<PaginatedResponse<Import>>('GET', '/imports', {
@@ -1367,7 +1371,7 @@ export class SellerClient {
rows: {
list: (
importId: string,
- params?: ListParams & Record<string, unknown>,
+ params?: ListParams<ImportRowFilters, ImportRowSort>,
options?: RequestOptions,
): Promise<PaginatedResponse<ImportRow>> =>
this.request<PaginatedResponse<ImportRow>>('GET', `/imports/${importId}/rows`, {
diff --git a/packages/seller-sdk/src/types/filters.generated.ts b/packages/seller-sdk/src/types/filters.generated.ts
index 1282b3ac4f..819539e824 100644
--- a/packages/seller-sdk/src/types/filters.generated.ts
+++ b/packages/seller-sdk/src/types/filters.generated.ts
@@ -12,6 +12,11 @@ export type ClaimReasonFields = Filter.BooleanFilters<'active'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'name'>
+export type DeliveryFields = Filter.TextFilters<'carrier' | 'tracking_number'>
+ & Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.EnumFilters<'status', 'pending' | 'pre_transit' | 'in_transit' | 'out_for_delivery' | 'available_for_pickup' | 'delivered' | 'return_to_sender' | 'failure' | 'unknown'>
+
export type DeliveryMethodFields = Filter.BooleanFilters<'available_to_sellers' | 'storefront_visible'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id' | 'seller_id'>
@@ -35,6 +40,16 @@ export type FulfillmentFields = Filter.RangeFilters<'created_at' | 'updated_at'>
& Filter.IdFilters<'id'>
& Filter.TextFilters<'number'>
+export type ImportFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id' | 'seller_id' | 'type'>
+ & Filter.TextFilters<'number'>
+ & Filter.EnumFilters<'status', 'pending' | 'mapping' | 'completed_mapping' | 'processing' | 'completed' | 'failed'>
+
+export type ImportRowFields = Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.RangeFilters<'row_number', number>
+ & Filter.EnumFilters<'status', 'pending' | 'processing' | 'completed' | 'failed'>
+
export type OrderFields = Filter.IdFilters<'channel_id' | 'customer_id' | 'id' | 'order_group_id' | 'seller_id'>
& Filter.RangeFilters<'completed_at' | 'created_at' | 'delivery_total' | 'item_total' | 'total' | 'updated_at'>
& Filter.TextFilters<'currency' | 'number' | 'po_number'>
@@ -90,6 +105,12 @@ export type SellerTransferFields = Filter.RangeFilters<'amount' | 'created_at' |
& Filter.EnumFilters<'kind', 'earning' | 'refund_reversal'>
& Filter.EnumFilters<'status', 'pending' | 'processing' | 'completed' | 'failed' | 'unresolved'>
+export type ShippingLabelFields = Filter.TextFilters<'carrier' | 'tracking_number'>
+ & Filter.RangeFilters<'created_at' | 'updated_at'>
+ & Filter.IdFilters<'id'>
+ & Filter.EnumFilters<'source', 'purchased' | 'uploaded'>
+ & Filter.EnumFilters<'status', 'purchased' | 'refund_requested' | 'refunded'>
+
export type StockLocationFields = Filter.BooleanFilters<'active' | 'default' | 'pickup_enabled' | 'returns_enabled'>
& Filter.TextFilters<'country_code' | 'kind' | 'name' | 'state_code'>
& Filter.RangeFilters<'created_at' | 'updated_at'>
@@ -141,6 +162,26 @@ export type ClaimReasonFilters = ClaimReasonFields
export type ClaimReasonSort = Filter.SortKey<'active' | 'created_at' | 'id' | 'name' | 'updated_at' | (keyof ClaimReasonSortExtensions & string)>
+/**
+ * Filters your app adds to Delivery lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/seller-sdk' {
+ * interface DeliveryFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface DeliveryFilterExtensions {}
+
+/** Sort fields your app adds to Delivery lists, as keys: `{ erp_id: true }`. */
+export interface DeliverySortExtensions {}
+
+export type DeliveryFilters = DeliveryFields
+ & Filter.OrFilters
+ & DeliveryFilterExtensions
+
+export type DeliverySort = Filter.SortKey<'carrier' | 'created_at' | 'id' | 'status' | 'tracking_number' | 'updated_at' | (keyof DeliverySortExtensions & string)>
+
/**
* Filters your app adds to DeliveryMethod lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -250,6 +291,49 @@ export type FulfillmentFilters = FulfillmentFields
export type FulfillmentSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'updated_at' | (keyof FulfillmentSortExtensions & string)>
+/**
+ * Filters your app adds to Import lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/seller-sdk' {
+ * interface ImportFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ImportFilterExtensions {}
+
+/** Sort fields your app adds to Import lists, as keys: `{ erp_id: true }`. */
+export interface ImportSortExtensions {}
+
+export type ImportFilters = ImportFields
+ & {
+ search?: string
+ }
+ & Filter.OrFilters
+ & ImportFilterExtensions
+
+export type ImportSort = Filter.SortKey<'created_at' | 'id' | 'number' | 'seller_id' | 'status' | 'type' | 'updated_at' | (keyof ImportSortExtensions & string)>
+
+/**
+ * Filters your app adds to ImportRow lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/seller-sdk' {
+ * interface ImportRowFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ImportRowFilterExtensions {}
+
+/** Sort fields your app adds to ImportRow lists, as keys: `{ erp_id: true }`. */
+export interface ImportRowSortExtensions {}
+
+export type ImportRowFilters = ImportRowFields
+ & Filter.OrFilters
+ & ImportRowFilterExtensions
+
+export type ImportRowSort = Filter.SortKey<'created_at' | 'id' | 'row_number' | 'status' | 'updated_at' | (keyof ImportRowSortExtensions & string)>
+
/**
* Filters your app adds to Order lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
@@ -491,6 +575,26 @@ export type SellerTransferFilters = SellerTransferFields
export type SellerTransferSort = Filter.SortKey<'amount' | 'created_at' | 'currency' | 'id' | 'kind' | 'order_id' | 'payout_id' | 'provider' | 'reference' | 'seller_id' | 'status' | 'updated_at' | (keyof SellerTransferSortExtensions & string)>
+/**
+ * Filters your app adds to ShippingLabel lists. Generate them with `spree filters types`,
+ * or declare them by hand in a file that has an `export`:
+ *
+ * export {}
+ * declare module '@spree/seller-sdk' {
+ * interface ShippingLabelFilterExtensions { erp_id_eq?: string }
+ * }
+ */
+export interface ShippingLabelFilterExtensions {}
+
+/** Sort fields your app adds to ShippingLabel lists, as keys: `{ erp_id: true }`. */
+export interface ShippingLabelSortExtensions {}
+
+export type ShippingLabelFilters = ShippingLabelFields
+ & Filter.OrFilters
+ & ShippingLabelFilterExtensions
+
+export type ShippingLabelSort = Filter.SortKey<'carrier' | 'created_at' | 'id' | 'source' | 'status' | 'tracking_number' | 'updated_at' | (keyof ShippingLabelSortExtensions & string)>
+
/**
* Filters your app adds to StockLocation lists. Generate them with `spree filters types`,
* or declare them by hand in a file that has an `export`:
diff --git a/packages/seller-sdk/src/types/index.ts b/packages/seller-sdk/src/types/index.ts
index f73528ddf2..cd6661cd8c 100644
--- a/packages/seller-sdk/src/types/index.ts
+++ b/packages/seller-sdk/src/types/index.ts
@@ -46,7 +46,7 @@ export interface AuthTokens {
// that extends them (see `spree filters types`).
export type {
BooleanFilters,
- CustomFieldFilters,
+ CustomFieldValueFilters,
EnumFilters,
IdFilters,
OrFilters,
diff --git a/spree/api/app/controllers/spree/api/v3/admin/tracking_carriers_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/tracking_carriers_controller.rb
index 74a7efd2e0..72ac806910 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/tracking_carriers_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/tracking_carriers_controller.rb
@@ -23,6 +23,10 @@ module Spree
protected
+ def filterable?
+ false
+ end
+
def model_class
Spree::Fulfillment
end
diff --git a/spree/api/lib/spree/api/openapi/schema_helper.rb b/spree/api/lib/spree/api/openapi/schema_helper.rb
index d19a72b22e..a76515bf15 100644
--- a/spree/api/lib/spree/api/openapi/schema_helper.rb
+++ b/spree/api/lib/spree/api/openapi/schema_helper.rb
@@ -427,6 +427,7 @@ module Spree
s[:'x-typelizer'] = true
strip_null_from_enums(s)
end
+ patch_typescript_only_types(schemas, writer_name)
patch_cart_schema(schemas)
patch_fulfillment_schema(schemas)
patch_admin_user_schema(schemas)
@@ -437,6 +438,34 @@ module Spree
end
end
+ # Typelizer publishes a type only TypeScript can express (`Array<{ … }>`,
+ # `any`) as a plain object. Give each such property the shape the API
+ # sends — an array, or any value — so responses validate against it;
+ # the patches below then point some arrays at a named item component.
+ def patch_typescript_only_types(schemas, writer_name)
+ Typelizer.interfaces(writer_name: writer_name).each do |interface|
+ properties = (schemas[interface.name] || schemas[interface.name.to_sym])&.dig(:properties)
+ next unless properties
+
+ interface.properties.each do |property|
+ key = [property.name.to_s, property.name.to_sym].find { |name| properties.key?(name) }
+ schema = key && !property.type.is_a?(Array) && typescript_only_type_schema(property.type.to_s)
+ next unless schema
+
+ schema[:nullable] = true if property.nullable || property.type.to_s.end_with?('| null')
+ properties[key] = schema.merge(properties[key].slice(:description))
+ end
+ end
+ end
+
+ def typescript_only_type_schema(type)
+ case type.delete_suffix(' | null')
+ when /\AArray<(string|number|boolean)>\z/ then { type: :array, items: { type: Regexp.last_match(1).to_sym } }
+ when /\AArray</ then { type: :array, items: { type: :object } }
+ when 'any', 'unknown' then {}
+ end
+ end
+
# Same Array<{...}> issue as cart/fulfillment — patch Import#schema_fields
# to reference the ImportSchemaField component schema.
def patch_import_schema(schemas)
diff --git a/spree/api/spec/integration/spree/api/v3/admin/claims_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/claims_spec.rb
new file mode 100644
index 0000000000..3cce0ecd2c
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/claims_spec.rb
@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Claims API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:record) { create(:claim, order: create(:shipped_order, store: store)) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ path '/api/v3/admin/claims' do
+ get 'List claims' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Every damage or missing-item claim in the store, across all orders.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'claims listed' do
+ schema SwaggerSchemaHelpers.paginated('Claim')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to include(record.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/claims' do
+ get 'List order claims' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'The damage or missing-item claims opened on one order.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order prefixed ID'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'claims listed' do
+ let(:order_id) { record.order.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Claim')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to include(record.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/addresses_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/addresses_spec.rb
new file mode 100644
index 0000000000..c3898b7489
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/addresses_spec.rb
@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Company Addresses API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:company) { create(:company, store: store) }
+ let!(:address) { create(:company_address, owner: company, label: 'Head office') }
+
+ path '/api/v3/admin/companies/{company_id}/addresses' do
+ let(:company_id) { company.prefixed_id }
+
+ get 'List company addresses' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the business's addresses: its sites, billing address and delivery points."
+ admin_scope :read, :customers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'addresses found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('Address')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(address.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/companies/invitations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/companies/invitations_spec.rb
new file mode 100644
index 0000000000..dc41e13cd7
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/companies/invitations_spec.rb
@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Company Invitations API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:company) { create(:company, store: store) }
+ let!(:invitation) { create(:company_invitation, company: company, email: '[email protected]') }
+
+ path '/api/v3/admin/companies/{company_id}/invitations' do
+ let(:company_id) { company.prefixed_id }
+
+ get 'List company invitations' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the invitations into this business that are still waiting to be accepted.'
+ admin_scope :read, :customers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :company_id, in: :path, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'invitations found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('CompanyInvitation')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(invitation.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/custom_fields_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/custom_fields_spec.rb
new file mode 100644
index 0000000000..dbc4a7904f
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/custom_fields_spec.rb
@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+# Product custom fields have their own spec (admin/products/custom_fields_spec.rb)
+# with the write operations; these are the lists on every other parent.
+RSpec.describe 'Admin Custom Fields API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ {
+ 'categories' => { tag: 'Categories', scope: :categories, label: 'category', parent: -> { create(:category) } },
+ 'collections' => { tag: 'Collections', scope: :collections, label: 'collection', parent: -> { create(:collection, store: store) } },
+ 'customers' => { tag: 'Customers', scope: :customers, label: 'customer', parent: -> { create(:user) } },
+ 'option_types' => { tag: 'Option Types', scope: :products, label: 'option type', parent: -> { create(:option_type) } },
+ 'orders' => { tag: 'Orders', scope: :orders, label: 'order', parent: -> { create(:order, store: store) } },
+ 'sellers' => { tag: 'Sellers', scope: :sellers, label: 'seller', parent: -> { create(:seller, store: store) } },
+ 'variants' => { tag: 'Variants', scope: :products, label: 'variant', parent: -> { create(:variant) } }
+ }.each do |segment, config|
+ parent_param = :"#{segment.singularize}_id"
+
+ path "/api/v3/admin/#{segment}/{#{parent_param}}/custom_fields" do
+ get "List #{config[:label]} custom fields" do
+ tags config[:tag]
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the #{config[:label]}'s custom field values."
+ admin_scope :read, config[:scope]
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: parent_param, in: :path, type: :string, required: true
+ parameter name: :expand, in: :query, type: :string, required: false,
+ description: 'Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).'
+ parameter name: :fields, in: :query, type: :string, required: false,
+ description: 'Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.'
+ filter_parameters_for
+
+ response '200', 'custom fields found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:parent) { instance_exec(&config[:parent]) }
+ let(:definition) do
+ create(:custom_field_definition, :short_text_field, resource_type: parent.class.name)
+ end
+ let!(:custom_field) do
+ create(:custom_field, resource: parent, custom_field_definition: definition, value: 'wool')
+ end
+ let(parent_param) { parent.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('CustomField')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |record| record['id'] }).to eq([custom_field.prefixed_id])
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/customer_privacy_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customer_privacy_spec.rb
index 3487278de5..a0b8ee80e3 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/customer_privacy_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/customer_privacy_spec.rb
@@ -95,4 +95,56 @@ RSpec.describe 'Admin Customer Privacy API', type: :request, swagger_doc: 'api-r
end
end
+
+ path '/api/v3/admin/consent_records' do
+ get 'List consent records' do
+ tags 'Customers'
+ produces 'application/json'
+ 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.'
+ admin_scope :read, :customers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'consent records found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let!(:consent_record) { create(:consent_record, store: store, owner: customer) }
+
+ schema SwaggerSchemaHelpers.paginated('ConsentRecord')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(consent_record.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/data_requests' do
+ get 'List data requests' do
+ tags 'Customers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the requests customers made to export or erase their personal data, newest first.'
+ admin_scope :read, :customers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'data requests found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let!(:data_request) { create(:data_request, store: store, customer: customer) }
+
+ schema SwaggerSchemaHelpers.paginated('DataRequest')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(data_request.prefixed_id)
+ end
+ end
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/customers/tax_identifiers_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/customers/tax_identifiers_spec.rb
new file mode 100644
index 0000000000..f49e958a25
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/customers/tax_identifiers_spec.rb
@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Customer Tax Identifiers API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:customer) { create(:user) }
+ let!(:tax_identifier) { create(:tax_identifier, owner: customer) }
+
+ path '/api/v3/admin/customers/{customer_id}/tax_identifiers' do
+ let(:customer_id) { customer.prefixed_id }
+
+ get 'List customer tax registrations' do
+ tags 'Customers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the customer's own tax registrations, one per kind."
+ admin_scope :read, :customers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :customer_id, in: :path, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'registrations found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('TaxIdentifier')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(tax_identifier.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/delivery_profiles_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/delivery_profiles_spec.rb
index 5e39e19c79..0684cdb409 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/delivery_profiles_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/delivery_profiles_spec.rb
@@ -76,6 +76,31 @@ RSpec.describe 'Admin Delivery Profiles API', type: :request, swagger_doc: 'api-
path '/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups' do
parameter name: :delivery_profile_id, in: :path, type: :string
+ get 'List origin groups' do
+ tags 'Delivery'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the profile's origin groups: the sets of warehouses that each quote their own delivery rates."
+ admin_scope :read, :settings
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'origin groups found' do
+ let(:delivery_profile) { create(:delivery_profile, store: store, name: "Grouped #{Time.current.to_f}") }
+ let(:delivery_profile_id) { delivery_profile.prefixed_id }
+ let!(:origin_group) { create(:delivery_origin_group, delivery_profile: delivery_profile, name: 'EU warehouse') }
+
+ schema SwaggerSchemaHelpers.paginated('DeliveryOriginGroup')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(origin_group.prefixed_id)
+ end
+ end
+ end
+
post 'Create an origin group' do
tags 'Delivery'
consumes 'application/json'
diff --git a/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
index 514d4512a0..bbf93e1cfb 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/delivery_settings_spec.rb
@@ -111,6 +111,29 @@ RSpec.describe 'Admin Delivery Settings API', type: :request, swagger_doc: 'api-
end
path '/api/v3/admin/delivery_zones' do
+ get 'List delivery zones' do
+ tags 'Delivery'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the areas delivery methods ship to, each made of countries, states or postal code ranges.'
+ admin_scope :read, :settings
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'delivery zones found' do
+ let!(:delivery_zone) { create(:delivery_zone, store: store, name: 'US North-East') }
+
+ schema SwaggerSchemaHelpers.paginated('DeliveryZone')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(delivery_zone.prefixed_id)
+ end
+ end
+ end
+
post 'Create delivery zone' do
tags 'Delivery'
consumes 'application/json'
@@ -170,4 +193,35 @@ RSpec.describe 'Admin Delivery Settings API', type: :request, swagger_doc: 'api-
end
end
end
+
+ path '/api/v3/admin/delivery_methods/{delivery_method_id}/rules' do
+ let(:delivery_method) { create(:delivery_method) }
+ let(:delivery_method_id) { delivery_method.prefixed_id }
+
+ get 'List delivery method rules' do
+ tags 'Delivery'
+ produces 'application/json'
+ 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.'
+ admin_scope :read, :settings
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :delivery_method_id, in: :path, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'rules found' do
+ let!(:rule) do
+ Spree::DeliveryMethodRules::ItemTotalRule.create!(delivery_method: delivery_method, preferred_minimum_amount: '25')
+ end
+
+ schema SwaggerSchemaHelpers.paginated('DeliveryMethodRule')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(rule.prefixed_id)
+ end
+ end
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/digital_links_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/digital_links_spec.rb
new file mode 100644
index 0000000000..6f35068de1
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/digital_links_spec.rb
@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Digital Links API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:order) { create(:order_with_line_items, store: store, line_items_count: 1) }
+ let(:line_item) { order.line_items.first }
+ let(:digital_asset) { create(:digital_asset, variant: line_item.variant) }
+ let!(:digital_link) { create(:digital_link, digital_asset: digital_asset, line_item: line_item) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/digital_links' do
+ get 'List digital links' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the download links issued for digital products bought in this store, newest first.'
+ admin_scope :read, :orders
+
+ 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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'digital links found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('DigitalLink')
+
+ run_test! do |response|
+ ids = JSON.parse(response.body)['data'].map { |record| record['id'] }
+ expect(ids).to eq([digital_link.prefixed_id])
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/exchanges_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/exchanges_spec.rb
new file mode 100644
index 0000000000..b6e14dab16
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/exchanges_spec.rb
@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Exchanges API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:record) { create(:exchange, order: create(:shipped_order, store: store)) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ path '/api/v3/admin/exchanges' do
+ get 'List exchanges' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Every exchange in the store, across all orders.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'exchanges listed' do
+ schema SwaggerSchemaHelpers.paginated('Exchange')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to include(record.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/exchanges' do
+ get 'List order exchanges' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'The exchanges opened on one order.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order prefixed ID'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'exchanges listed' do
+ let(:order_id) { record.order.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Exchange')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to include(record.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/media_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/media_spec.rb
index 1876f73c58..99fc30c196 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
@@ -142,6 +142,33 @@ RSpec.describe 'Admin Media Library API', type: :request, swagger_doc: 'api-refe
path '/api/v3/admin/products/{product_id}/media' do
parameter name: :product_id, in: :path, type: :string, description: 'Product ID'
+ get 'List product media' do
+ tags 'Media'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the files placed on a product, in their display order."
+ admin_scope :read, :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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'media found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:product_id) { product.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Media')
+
+ run_test! do |response|
+ ids = JSON.parse(response.body)['data'].map { |record| record['id'] }
+ expect(ids).to include(media.prefixed_id)
+ end
+ end
+ end
+
post 'Place a library file on a product' do
tags 'Media'
consumes 'application/json'
@@ -183,4 +210,39 @@ RSpec.describe 'Admin Media Library API', type: :request, swagger_doc: 'api-refe
end
end
end
+
+ path '/api/v3/admin/products/{product_id}/variants/{variant_id}/media' do
+ parameter name: :product_id, in: :path, type: :string, description: 'Product ID'
+ parameter name: :variant_id, in: :path, type: :string, description: 'Variant ID'
+
+ get 'List variant media' do
+ tags 'Media'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the files placed on one of a product's variants, in their display order."
+ admin_scope :read, :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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'media found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:variant) { create(:variant, product: product) }
+ let!(:variant_media) { create(:media, viewable: variant, alt: 'Variant view') }
+ let(:product_id) { product.prefixed_id }
+ let(:variant_id) { variant.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Media')
+
+ run_test! do |response|
+ ids = JSON.parse(response.body)['data'].map { |record| record['id'] }
+ expect(ids).to eq([variant_media.prefixed_id])
+ end
+ end
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb
index f3d26c871f..ac99bde3cb 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/order_adjustment_lines_spec.rb
@@ -104,6 +104,30 @@ RSpec.describe 'Admin Order Adjustment Lines API', type: :request, swagger_doc:
end
path '/api/v3/admin/orders/{order_id}/fees' do
+ get 'List fees' do
+ tags 'Orders'
+ produces 'application/json'
+ 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."
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order prefixed ID'
+ filter_parameters_for
+
+ response '200', 'fees found' do
+ let!(:fee) { create(:fee, order: order, label: 'Gift wrap', kind: 'gift_wrap', amount: '4.00') }
+
+ schema SwaggerSchemaHelpers.paginated('Fee')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(fee.prefixed_id)
+ end
+ end
+ end
+
post 'Create fee' do
tags 'Orders'
consumes 'application/json'
diff --git a/spree/api/spec/integration/spree/api/v3/admin/order_groups_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/order_groups_spec.rb
new file mode 100644
index 0000000000..319b525d4b
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/order_groups_spec.rb
@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Order Groups API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:order_group) { create(:order_group, store: store) }
+
+ path '/api/v3/admin/order_groups' do
+ get 'List order groups' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns checkouts split into one order per seller, grouping the orders placed together.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'order groups found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('OrderGroup')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(order_group.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/products/digital_assets_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/products/digital_assets_spec.rb
new file mode 100644
index 0000000000..b470f310b8
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/products/digital_assets_spec.rb
@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Product Digital Assets API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:product) { create(:product, store: store) }
+ let!(:digital_asset) { create(:digital_asset, variant: product.default_variant) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/products/{product_id}/digital_assets' do
+ parameter name: :product_id, in: :path, type: :string, required: true, description: 'Product ID'
+
+ get 'List product digital assets' do
+ tags 'Products'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the downloadable files attached to the product's variants, oldest first."
+ admin_scope :read, :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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'digital assets found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:product_id) { product.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('DigitalAsset')
+
+ run_test! do |response|
+ ids = JSON.parse(response.body)['data'].map { |record| record['id'] }
+ expect(ids).to eq([digital_asset.prefixed_id])
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/reporting/saved_reports_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/reporting/saved_reports_spec.rb
new file mode 100644
index 0000000000..5573b6a8ac
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/reporting/saved_reports_spec.rb
@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Saved Reports API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:saved_report) { create(:saved_report, store: store, name: 'Sales by channel') }
+
+ path '/api/v3/admin/reporting/saved_reports' do
+ get 'List saved reports' do
+ tags 'Reports'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "Returns the store's saved reports, each a named query staff can run again."
+ admin_scope :read, :reports
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'saved reports found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('SavedReport')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(saved_report.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/returns_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/returns_spec.rb
new file mode 100644
index 0000000000..16a761df9c
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/returns_spec.rb
@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Returns API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:record) { create(:return, order: create(:shipped_order, store: store)) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ path '/api/v3/admin/returns' do
+ get 'List returns' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Every return in the store, across all orders.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'returns listed' do
+ schema SwaggerSchemaHelpers.paginated('Return')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to include(record.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/returns' do
+ get 'List order returns' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'The returns opened on one order.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order prefixed ID'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'returns listed' do
+ let(:order_id) { record.order.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Return')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to include(record.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/orders/{order_id}/returns/{return_id}/labels' do
+ get 'List return labels' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'The shipping labels issued for sending one return back to the store.'
+ admin_scope :read, :orders
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order prefixed ID'
+ parameter name: :return_id, in: :path, type: :string, required: true, description: 'Return prefixed ID'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'labels listed' do
+ let!(:label) { create(:shipping_label, owner: record, store: store) }
+ let(:order_id) { record.order.prefixed_id }
+ let(:return_id) { record.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('ShippingLabel')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to include(label.prefixed_id)
+ end
+ end
+ end
+ end
+end
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.rb
index 22ec1f390f..11f71b624a 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
@@ -578,6 +578,101 @@ RSpec.describe 'Admin Sellers API', type: :request, swagger_doc: 'api-reference/
end
end
+ path '/api/v3/admin/sellers/{seller_id}/requirement_submissions' do
+ parameter name: :seller_id, in: :path, type: :string, required: true, description: 'Seller prefixed ID'
+
+ get "List a seller's requirement submissions" do
+ tags 'Sellers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'What this seller submitted against the marketplace requirements, with the review decision on each.'
+ admin_scope :read, :sellers
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'
+ filter_parameters_for
+
+ response '200', 'submissions listed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:seller_id) { seller.prefixed_id }
+ let!(:submission) { create(:seller_requirement_submission, seller: seller) }
+
+ schema SwaggerSchemaHelpers.paginated('SellerRequirementSubmission')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |item| item['id'] }).to eq([submission.prefixed_id])
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/seller_transfers' do
+ get 'List seller transfers' do
+ tags 'Sellers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ The fund ledger: what each seller earned from an order, and any
+ reversals. Read-only, since fulfilment and refunds write it.
+ DESC
+ admin_scope :read, :payouts
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'
+ filter_parameters_for
+
+ response '200', 'transfers listed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:order) { create(:completed_order_with_totals, store: store, seller: seller) }
+ let!(:transfer) { create(:seller_transfer, :completed, seller: seller, amount: 40, order: order) }
+
+ schema SwaggerSchemaHelpers.paginated('SellerTransfer')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |item| item['id'] }).to include(transfer.prefixed_id)
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/seller_payouts' do
+ get 'List seller payouts' do
+ tags 'Sellers'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Settlements to sellers, each batching the transfers that had
+ accumulated since the last. `pending` and `processing` payouts are
+ still owed; `completed` ones reached the seller.
+ DESC
+ admin_scope :read, :payouts
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'
+ filter_parameters_for
+
+ response '200', 'payouts listed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let!(:seller_payout) { create(:seller_payout, seller: seller, store: store, amount: 40, currency: 'USD') }
+
+ schema SwaggerSchemaHelpers.paginated('SellerPayout')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |item| item['id'] }).to include(seller_payout.prefixed_id)
+ end
+ end
+ end
+ end
+
path '/api/v3/admin/seller_payouts/{id}/complete' do
parameter name: :id, in: :path, type: :string, required: true, description: 'Seller payout prefixed ID'
diff --git a/spree/api/spec/integration/spree/api/v3/admin/stock_reservations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/stock_reservations_spec.rb
new file mode 100644
index 0000000000..8a0cbabc22
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/stock_reservations_spec.rb
@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Stock Reservations API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:order) { create(:order_with_line_items, store: store, line_items_count: 1) }
+ let!(:stock_reservation) { create(:stock_reservation, order: order) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/stock_reservations' do
+ get 'List stock reservations' do
+ tags 'Stock'
+ produces 'application/json'
+ 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.'
+ admin_scope :read, :stock
+
+ 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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'stock reservations found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('StockReservation')
+
+ run_test! do |response|
+ ids = JSON.parse(response.body)['data'].map { |record| record['id'] }
+ expect(ids).to eq([stock_reservation.prefixed_id])
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/tax_categories_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/tax_categories_spec.rb
new file mode 100644
index 0000000000..40aa0f92e5
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/tax_categories_spec.rb
@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Tax Categories API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:tax_category) { create(:tax_category, name: 'Clothing') }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/tax_categories' do
+ get 'List tax categories' do
+ tags 'Settings'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'Returns the tax categories products and delivery methods can be assigned to, which tax rates then apply to.'
+ admin_scope :read, :settings
+
+ 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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'tax categories found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('TaxCategory')
+
+ run_test! do |response|
+ ids = JSON.parse(response.body)['data'].map { |record| record['id'] }
+ expect(ids).to include(tax_category.prefixed_id)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb
index 70cf91e367..7f8f0fe2dc 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/variants_spec.rb
@@ -292,4 +292,32 @@ RSpec.describe 'Admin Variants API', type: :request, swagger_doc: 'api-reference
end
end
end
+
+ path '/api/v3/admin/variants' do
+ get 'List variants' do
+ tags 'Variants'
+ produces 'application/json'
+ 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.'
+ admin_scope :read, :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: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Number of records per page'
+ filter_parameters_for
+
+ response '200', 'variants found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('Variant')
+
+ run_test! do |response|
+ ids = JSON.parse(response.body)['data'].map { |record| record['id'] }
+ expect(ids).to include(variant.prefixed_id)
+ end
+ end
+ end
+ end
end
diff --git a/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb
index f60216d319..54e578d411 100644
--- a/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/seller/fulfillments_spec.rb
@@ -182,6 +182,70 @@ RSpec.describe 'Seller Fulfillments API', type: :request, swagger_doc: 'api-refe
end
end
+ path '/api/v3/seller/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries' do
+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, description: 'Prefixed fulfillment ID'
+
+ get 'List deliveries' do
+ tags 'Fulfillments'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "The consignments of one of this seller's parcels, one per tracking number, with each carrier status."
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'
+ filter_parameters_for
+
+ response '200', 'deliveries listed' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { fulfillment.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Delivery')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |item| item['id'] }).to match_array(fulfillment.deliveries.map(&:prefixed_id))
+ expect(data).not_to be_empty
+ end
+ end
+ end
+ end
+
+ path '/api/v3/seller/orders/{order_id}/fulfillments/{fulfillment_id}/labels' do
+ parameter name: :order_id, in: :path, type: :string, description: 'Prefixed order ID'
+ parameter name: :fulfillment_id, in: :path, type: :string, description: 'Prefixed fulfillment ID'
+
+ get 'List shipping labels' do
+ tags 'Fulfillments'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "Every label bought or uploaded for one of this seller's parcels, refunded ones included."
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'
+ filter_parameters_for
+
+ response '200', 'labels listed' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:order_id) { order.prefixed_id }
+ let(:fulfillment_id) { fulfillment.prefixed_id }
+ let!(:shipping_label) { create(:shipping_label, owner: fulfillment, store: store) }
+
+ schema SwaggerSchemaHelpers.paginated('ShippingLabel')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |item| item['id'] }).to eq([shipping_label.prefixed_id])
+ end
+ end
+ end
+ end
+
path '/api/v3/seller/tracking_carriers' do
get 'List tracking carriers' do
tags 'Fulfillments'
diff --git a/spree/api/spec/integration/spree/api/v3/seller/imports_spec.rb b/spree/api/spec/integration/spree/api/v3/seller/imports_spec.rb
new file mode 100644
index 0000000000..0e0d4f6bbb
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/seller/imports_spec.rb
@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Seller Imports API', type: :request, swagger_doc: 'api-reference/seller.yaml' do
+ include_context 'API v3 Seller'
+
+ let!(:product_import) { create(:product_import, store: store, seller: seller, user: seller_user) }
+
+ path '/api/v3/seller/imports' do
+ get 'List imports' do
+ tags 'Imports'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "This seller's product CSV imports, queued or finished. Another seller's imports are never listed."
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'
+ filter_parameters_for
+
+ response '200', 'imports listed' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+
+ before { create(:product_import, :for_seller, store: store) }
+
+ schema SwaggerSchemaHelpers.paginated('Import')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |item| item['id'] }).to eq([product_import.prefixed_id])
+ end
+ end
+ end
+ end
+
+ path '/api/v3/seller/imports/{import_id}/rows' do
+ parameter name: :import_id, in: :path, type: :string, required: true, description: 'Import prefixed ID'
+
+ get 'List import rows' do
+ tags 'Imports'
+ produces 'application/json'
+ security [bearer_auth: []]
+ description "The rows of one of this seller's imports, each with its status and any validation errors."
+
+ parameter name: 'X-Spree-Seller-Id', in: :header, type: :string, required: true
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false, description: 'Records per page (max 100)'
+ filter_parameters_for
+
+ response '200', 'rows listed' do
+ let(:Authorization) { "Bearer #{seller_jwt_token}" }
+ let(:'X-Spree-Seller-Id') { seller.prefixed_id }
+ let(:import_id) { product_import.prefixed_id }
+ let!(:import_row) { create(:import_row, import: product_import) }
+
+ schema SwaggerSchemaHelpers.paginated('ImportRow')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.map { |item| item['id'] }).to eq([import_row.prefixed_id])
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/store/claims_spec.rb b/spree/api/spec/integration/spree/api/v3/store/claims_spec.rb
new file mode 100644
index 0000000000..cf62b5be9e
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/store/claims_spec.rb
@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Order Claims API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:order) { create(:shipped_order, store: store, customer: user) }
+ let!(:claim) { create(:claim, order: order) }
+
+ path '/api/v3/store/orders/{order_id}/claims' do
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order prefixed ID'
+
+ get 'List claims' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'The damage or missing-item claims opened on one of the customer\'s orders, newest first. Accessible via JWT or the order token header for guests.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer token for authenticated customers'
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
+ description: 'Order token for guest access'
+ filter_parameters_for
+
+ response '200', 'claims listed' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Claim')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to eq([claim.prefixed_id])
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/store/companies_spec.rb b/spree/api/spec/integration/spree/api/v3/store/companies_spec.rb
index 4b4f04b10a..6c4dd61c0a 100644
--- a/spree/api/spec/integration/spree/api/v3/store/companies_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/companies_spec.rb
@@ -174,6 +174,35 @@ RSpec.describe 'Company Self-Service API', type: :request, swagger_doc: 'api-ref
end
end
+ path '/api/v3/store/companies/{company_id}/invitations' do
+ parameter name: :company_id, in: :path, type: :string, required: true, description: 'Company node ID (comp_...)'
+
+ get 'List pending company invitations' do
+ tags 'Companies'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'The invitations to this node that nobody has accepted or revoked yet. Requires standing over the node.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'invitations listed' do
+ let!(:membership) { create(:company_membership, company: company, customer: user) }
+ let!(:invitation) { create(:company_invitation, company: company, email: '[email protected]') }
+ let(:company_id) { company.prefixed_id }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema SwaggerSchemaHelpers.paginated('CompanyInvitation')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to eq([invitation.prefixed_id])
+ end
+ end
+ end
+ end
+
path '/api/v3/store/companies/{company_id}/addresses' do
parameter name: :company_id, in: :path, type: :string, required: true, description: 'Company node ID (comp_...)'
diff --git a/spree/api/spec/integration/spree/api/v3/store/digital_links_spec.rb b/spree/api/spec/integration/spree/api/v3/store/digital_links_spec.rb
index a2b41c044e..e3fac4c317 100644
--- a/spree/api/spec/integration/spree/api/v3/store/digital_links_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/store/digital_links_spec.rb
@@ -11,6 +11,31 @@ RSpec.describe 'Digital Links API', type: :request, swagger_doc: 'api-reference/
let(:digital_asset) { create(:digital_asset, variant: line_item.variant) }
let!(:digital_link) { create(:digital_link, digital_asset: digital_asset, line_item: line_item) }
+ path '/api/v3/store/customers/me/digital_links' do
+ get 'List my digital links' do
+ tags 'Digital Links'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description "The signed-in customer's downloads in this store, newest first."
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: true
+ filter_parameters_for
+
+ response '200', 'digital links listed' do
+ let(:order) { create(:completed_order_with_totals, store: store, customer: user) }
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+
+ schema SwaggerSchemaHelpers.paginated('DigitalLink')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to eq([digital_link.prefixed_id])
+ end
+ end
+ end
+ end
+
path '/api/v3/store/digital_links/{token}' do
get 'Download a digital product' do
tags 'Digital Links'
diff --git a/spree/api/spec/integration/spree/api/v3/store/returns_spec.rb b/spree/api/spec/integration/spree/api/v3/store/returns_spec.rb
new file mode 100644
index 0000000000..5630eb8753
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/store/returns_spec.rb
@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Order Returns API', type: :request, swagger_doc: 'api-reference/store.yaml' do
+ include_context 'API v3 Store'
+
+ let(:order) { create(:shipped_order, store: store, customer: user) }
+ let!(:return_record) { create(:return, order: order) }
+
+ path '/api/v3/store/orders/{order_id}/returns' do
+ parameter name: :order_id, in: :path, type: :string, required: true, description: 'Order prefixed ID'
+
+ get 'List returns' do
+ tags 'Orders'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description 'The returns opened on one of the customer\'s orders, newest first. Accessible via JWT or the order token header for guests.'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: 'Authorization', in: :header, type: :string, required: false,
+ description: 'Bearer token for authenticated customers'
+ parameter name: 'x-spree-token', in: :header, type: :string, required: false,
+ description: 'Order token for guest access'
+ filter_parameters_for
+
+ response '200', 'returns listed' do
+ let(:'x-spree-api-key') { api_key.token }
+ let(:'Authorization') { "Bearer #{jwt_token}" }
+ let(:order_id) { order.prefixed_id }
+
+ schema SwaggerSchemaHelpers.paginated('Return')
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['data'].map { |row| row['id'] }).to eq([return_record.prefixed_id])
+ end
+ end
+ end
+ end
+end