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.

Drop bridges for code that never shipped, and keep an arrival

Damian Legawiecbf0caaacb623
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 3cd728c33c..ae44fce91d 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -39,18 +39,28 @@ info:
```
version: v3
paths:
- "/api/v3/admin/admin_users":
- get:
- summary: List staff
+ "/api/v3/admin/auth/login":
+ post:
+ summary: Login
tags:
- - Staff
+ - Authentication
security:
- api_key: []
- bearer_auth: []
- description: |-
- Returns admin users with at least one role assignment on the current store.
+ description: |
+ Authenticates an admin user and returns a short-lived JWT access token.
+ The rotatable refresh token is set in an HttpOnly cookie — it is not
+ included in the response body.
- **Required scope:** `read_staff` (for API-key authentication).
+ The `provider` field selects the authentication method. When omitted it
+ defaults to `email`, the built-in email/password login.
+
+ To authenticate against a third-party identity provider (Okta, Azure AD,
+ Google Workspace SSO, a custom JWT issuer, SAML, etc.), send
+ `{ "provider": "<your_key>", ... }` with the fields that provider
+ requires. The endpoint returns the same JWT regardless of which provider
+ authenticated the request. See
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
+ for the list of configured providers and their required fields.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -62,33 +72,110 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: staff } = await client.adminUsers.list()
+ // The refresh token is set as an HttpOnly cookie; only `token` and `user` come back in the body.
+ const auth = await client.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /admin_users
+ source: spree api post /auth/login -d '{"email":"[email protected]","password":"password123"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
responses:
'200':
- description: staff found
- "/api/v3/admin/admin_users/{id}":
- get:
- summary: Show a staff member
+ description: login successful
+ content:
+ application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjE3NmVlN2M3LWJkYzktNGM1MS1hMzFiLTEwMDYxOTc3NGZmNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.t4Ntas5E8dwfI8wxMdwcC-XVFXWzaFSAFL8_Mv4HnlU
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Gavin
+ last_name: Swift
+ full_name: Gavin Swift
+ 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
+ schema:
+ "$ref": "#/components/schemas/AuthResponse"
+ '401':
+ description: invalid credentials
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_failed
+ message: Invalid email or password
+ 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
+ example: password123
+ required:
+ - email
+ - password
+ - title: ProviderLogin
+ description: |
+ Provider-dispatched login. The `provider` key selects a configured
+ authentication provider; the remaining fields are forwarded to it.
+ Required fields depend on the provider — see
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
+ type: object
+ properties:
+ provider:
+ type: string
+ example: okta
+ 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:
- - Staff
+ - Authentication
security:
- api_key: []
- bearer_auth: []
- description: "**Required scope:** `read_staff` (for API-key authentication)."
+ description: |
+ Exchanges the HttpOnly refresh-token cookie for a new access JWT and a
+ rotated refresh token cookie. No request body or Authorization header
+ is required — the cookie alone authenticates the call.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -100,40 +187,62 @@ paths:
secretKey: 'sk_xxx',
})
- const staff = await client.adminUsers.get('admin_xxx')
+ // Driven entirely by the HttpOnly refresh-token cookie + CSRF header (set by the SDK).
+ const auth = await client.auth.refresh()
- lang: bash
label: Spree CLI
- source: spree api get /admin_users/{id}
+ source: spree api post /auth/refresh
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
- patch:
- summary: Update a staff member
+ description: refresh successful
+ content:
+ application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImFiN2M4YjAxLTY0MGYtNDJhZi1hZTY1LTQxY2NmOTk1YmVlMCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.oXS2FwkI2rK4WOX4QUNW4oTPu7gzMmB9Y9oqsJpW7SY
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Clarine
+ last_name: Jenkins
+ full_name: Clarine Jenkins
+ 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
+ schema:
+ "$ref": "#/components/schemas/AuthResponse"
+ '401':
+ description: missing or invalid refresh-token cookie
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_refresh_token
+ message: Refresh token cookie missing
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/auth/logout":
+ post:
+ summary: Logout
tags:
- - Staff
+ - Authentication
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: Revokes the refresh-token cookie, effectively logging the admin
+ out.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -145,59 +254,29 @@ paths:
secretKey: 'sk_xxx',
})
- const staff = await client.adminUsers.update('admin_xxx', {
- first_name: 'Ada',
- role_ids: ['role_xxx'],
- })
+ await client.auth.logout()
- lang: bash
label: Spree CLI
- source: spree api patch /admin_users/{id} -d '{"first_name":"Ada","role_ids":["role_xxx"]}'
+ source: spree api post /auth/logout
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
- 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
+ '204':
+ description: logout successful
+ "/api/v3/admin/me":
+ get:
+ summary: Get current admin user and permissions
tags:
- - Staff
+ - Authentication
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.
-
- **Required scope:** `write_staff` (for API-key authentication).
+ description: Returns the current admin user profile and a serialized list of
+ permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -209,10 +288,17 @@ paths:
secretKey: 'sk_xxx',
})
- await client.adminUsers.delete('admin_xxx')
+ const me = await client.me.get()
+ if (
+ me.permissions.some(
+ (r) => r.allow && r.actions.includes('manage') && r.subjects.includes('Spree::Product'),
+ )
+ ) {
+ // show "Create product" button
+ }
- lang: bash
label: Spree CLI
- source: spree api delete /admin_users/{id}
+ source: spree api get /me
parameters:
- name: x-spree-api-key
in: header
@@ -222,33 +308,112 @@ 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: staff removed from store
- "/api/v3/admin/allowed_origins":
- get:
- summary: List allowed origins
+ '200':
+ description: current admin user and permissions
+ content:
+ application/json:
+ example:
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Zenobia
+ last_name: Sanford
+ full_name: Zenobia Sanford
+ 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
+ permissions:
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - all
+ has_conditions: false
+ permission_keys:
+ - read_orders
+ - write_orders
+ - read_payments
+ - write_payments
+ - read_fulfillments
+ - write_fulfillments
+ - read_refunds
+ - write_refunds
+ - read_gift_cards
+ - write_gift_cards
+ - read_store_credits
+ - write_store_credits
+ - read_products
+ - write_products
+ - read_product_types
+ - write_product_types
+ - read_publishing
+ - write_publishing
+ - read_media
+ - write_media
+ - read_categories
+ - write_categories
+ - read_collections
+ - write_collections
+ - read_stock
+ - write_stock
+ - read_promotions
+ - write_promotions
+ - read_customers
+ - write_customers
+ - read_settings
+ - write_settings
+ - read_delivery_methods
+ - write_delivery_methods
+ - read_webhooks
+ - write_webhooks
+ - read_integrations
+ - write_integrations
+ - read_api_keys
+ - write_api_keys
+ - read_staff
+ - write_staff
+ - read_sellers
+ - write_sellers
+ - read_commissions
+ - write_commissions
+ - read_payouts
+ - write_payouts
+ - read_seller_profile
+ - write_seller_profile
+ - read_dashboard
+ schema:
+ "$ref": "#/components/schemas/MeResponse"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update the current admin profile
tags:
- - Allowed Origins
+ - Authentication
security:
- api_key: []
bearer_auth: []
- description: |-
- Returns the CORS allowlist for the current store. Each entry is a
- bare `scheme://host[:port]` permitted to call the admin API from a
- browser. Backs the `Rack::Cors` allowlist and the CSRF boundary of
- the admin cookie session (see
- `docs/plans/5.5-admin-auth-cookie-refresh.md`).
-
-
- **Required scope:** `read_settings` (for API-key authentication).
+ description: Self-service update of the signed-in admin's own profile, such
+ as their admin UI display language (`selected_locale`).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -260,10 +425,13 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: origins } = await client.allowedOrigins.list()
+ // Set the signed-in admin's own UI display language.
+ const me = await client.me.update({
+ selected_locale: 'de',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /allowed_origins
+ source: spree api patch /me -d '{"selected_locale":"de"}'
parameters:
- name: x-spree-api-key
in: header
@@ -276,73 +444,122 @@ paths:
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[origin_cont]
- in: query
- required: false
- description: Filter by origin (contains)
- schema:
- type: string
- - 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
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
+ description: profile updated
content:
application/json:
+ example:
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Phebe
+ last_name: Bosco
+ full_name: Phebe Bosco
+ selected_locale: de
+ 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
+ permissions:
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - all
+ has_conditions: false
+ permission_keys:
+ - read_orders
+ - write_orders
+ - read_payments
+ - write_payments
+ - read_fulfillments
+ - write_fulfillments
+ - read_refunds
+ - write_refunds
+ - read_gift_cards
+ - write_gift_cards
+ - read_store_credits
+ - write_store_credits
+ - read_products
+ - write_products
+ - read_product_types
+ - write_product_types
+ - read_publishing
+ - write_publishing
+ - read_media
+ - write_media
+ - read_categories
+ - write_categories
+ - read_collections
+ - write_collections
+ - read_stock
+ - write_stock
+ - read_promotions
+ - write_promotions
+ - read_customers
+ - write_customers
+ - read_settings
+ - write_settings
+ - read_delivery_methods
+ - write_delivery_methods
+ - read_webhooks
+ - write_webhooks
+ - read_integrations
+ - write_integrations
+ - read_api_keys
+ - write_api_keys
+ - read_staff
+ - write_staff
+ - read_sellers
+ - write_sellers
+ - read_commissions
+ - write_commissions
+ - read_payouts
+ - write_payouts
+ - read_seller_profile
+ - write_seller_profile
+ - read_dashboard
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/MeResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ selected_locale:
+ type: string
+ example: de
+ first_name:
+ type: string
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ "/api/v3/admin/auth/password_resets":
post:
- summary: Create an allowed origin
+ summary: Request password reset
tags:
- - Allowed Origins
+ - Authentication
security:
- api_key: []
- bearer_auth: []
- description: |-
- Adds an origin to the admin CORS allowlist. The value must be a bare
- `scheme://host[:port]` (no path, query, or fragment) and use `http` or
- `https`.
-
+ description: |
+ Requests a password reset email for an admin user. Always returns `202`
+ whether or not the email matches an account, to prevent enumeration.
- **Required scope:** `write_settings` (for API-key authentication).
+ `redirect_url` is where the emailed link should point (the reset token
+ is appended as a `token` query param). It must match one of the store's
+ allowed origins — otherwise it is silently ignored and the server-side
+ default is used. The email is delivered by Spree itself via the
+ `admin_user.password_reset_requested` event; this event is never
+ forwarded to webhook endpoints.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -354,67 +571,59 @@ paths:
secretKey: 'sk_xxx',
})
- const origin = await client.allowedOrigins.create({
- origin: 'https://admin.example.com',
+ // Always resolves (202) whether or not the email exists — no account enumeration.
+ // The emailed link points at redirect_url with the reset token appended as ?token=.
+ await client.auth.requestPasswordReset({
+ email: '[email protected]',
+ redirect_url: 'https://admin.your-store.com/reset-password',
})
- lang: bash
label: Spree CLI
- source: spree api post /allowed_origins -d '{"origin":"https://admin.example.com"}'
+ source: spree api post /auth/password_resets -d '{"email":"[email protected]","redirect_url":"https://admin.your-store.com/reset-password"}'
parameters:
- name: x-spree-api-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
+ '202':
+ description: reset requested
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ message: If an account exists for that email, password reset instructions
+ have been sent.
requestBody:
content:
application/json:
schema:
type: object
properties:
- origin:
+ email:
type: string
- example: https://admin.example.com
+ format: email
+ redirect_url:
+ type: string
+ example: https://admin.your-store.com/reset-password
+ description: Must match an allowed origin of the store; ignored
+ otherwise.
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
+ - email
+ "/api/v3/admin/auth/password_resets/{id}":
+ patch:
+ summary: Reset password
tags:
- - Allowed Origins
+ - Authentication
security:
- api_key: []
- bearer_auth: []
- description: |-
- Returns a single allowed origin by prefixed ID.
-
- **Required scope:** `read_settings` (for API-key authentication).
+ description: |
+ Consumes a password reset token (the `token` query param from the
+ emailed link), sets the new password, and signs the admin in: the
+ response carries a JWT access token and the rotatable refresh token is
+ set in an HttpOnly cookie. The token is single-use — it invalidates as
+ soon as the password changes.
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -426,92 +635,61 @@ paths:
secretKey: 'sk_xxx',
})
- const origin = await client.allowedOrigins.get('ao_xxx')
+ // The token comes from the emailed link's ?token= param. On success the admin
+ // is signed in: a JWT comes back and the refresh token is set as an HttpOnly cookie.
+ const auth = await client.auth.resetPassword('reset-token-from-email', {
+ password: 'new-password-123',
+ password_confirmation: 'new-password-123',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /allowed_origins/{id}
+ source: spree api patch /auth/password_resets/{id} -d '{"password":"new-password-123","password_confirmation":"new-password-123"}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
+ - name: id
+ in: path
+ description: The reset token from the emailed link
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.
-
- **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 origin = await client.allowedOrigins.update('ao_xxx', {
- origin: 'https://www.example.com',
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /allowed_origins/{id} -d '{"origin":"https://www.example.com"}'
- parameters:
- - name: x-spree-api-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
+ description: password reset
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjBiZTdhM2RmLWEyYzYtNDZkOC1hNTZiLWE4NDg4MGIyZGZiNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Vo2RzprqsH2XBa8DaSQ6awyXqlBA5QDFA5R7ygTezXY
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Olga
+ last_name: Schneider
+ full_name: Olga Schneider
+ 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
schema:
- "$ref": "#/components/schemas/AllowedOrigin"
+ "$ref": "#/components/schemas/AuthResponse"
'422':
- description: validation error
+ description: invalid or expired token
content:
application/json:
+ example:
+ error:
+ code: password_reset_token_invalid
+ message: Password reset token is invalid or has expired.
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -520,11736 +698,1468 @@ paths:
schema:
type: object
properties:
- origin:
+ password:
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
- admin SPA running at that origin will no longer be able to call the
- admin API from a browser.
-
-
- **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.allowedOrigins.delete('ao_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api delete /allowed_origins/{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: allowed origin deleted
- "/api/v3/admin/api_keys":
+ example: new-password-123
+ password_confirmation:
+ type: string
+ example: new-password-123
+ required:
+ - password
+ - password_confirmation
+ "/api/v3/admin/auth/setup":
get:
- summary: List API keys
+ summary: Check first-run setup availability
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.
-
- **Required scope:** `read_api_keys` (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: keys } = await client.apiKeys.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /api_keys
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
+ - Authentication
+ description: |
+ Reports whether first-run setup is still available — true only while
+ the installation has no admin user. Unauthenticated; the dashboard
+ login page uses it to offer the setup screen.
responses:
'200':
- description: API keys found
+ description: setup status
+ content:
+ application/json:
+ example:
+ setup_required: true
post:
- summary: Create an API key
+ summary: Complete first-run setup
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.
-
- **Required scope:** `write_api_keys` (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 key = await client.apiKeys.create({
- name: 'Backend integration',
- key_type: 'secret',
- scopes: ['read_orders', 'write_orders'],
- })
-
- // `key.plaintext_token` is available only on this response.
- - lang: bash
- label: Spree CLI
- source: spree api post /api_keys -d '{"name":"Backend integration","key_type":"secret","scopes":["read_orders","write_orders"]}'
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
+ - Authentication
+ description: |
+ Creates the first admin account and adopts the seeded store, authorized
+ by the one-time setup token printed at install time (rotate it with
+ `bin/rails spree:setup:token`). Issues a JWT access token and a
+ refresh-token cookie exactly like login. Returns 404 once any admin
+ user exists — the flow is closed permanently after setup.
+ parameters: []
responses:
- '201':
- description: secret key created — plaintext token returned once
- '422':
- description: validation error
+ '200':
+ description: setup completed
+ content:
+ application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZjMjg1ODk5LTExMzUtNDBhMi1hNDBiLTE4NjNiODcwZDRjYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDc4NzAwfQ.Go2eUEiXf7rVD5mwtNMqkWqUGcBfhxk3b7JT8dw8uiE
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Olivia
+ last_name: Owner
+ full_name: Olivia Owner
+ 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: My Store
+ code: spree_1
+ '404':
+ description: setup not available
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Setup is not available
requestBody:
content:
application/json:
schema:
type: object
required:
- - name
- - key_type
+ - setup_token
+ - email
+ - password
+ - country_code
properties:
- name:
+ setup_token:
type: string
- example: Backend integration
- key_type:
+ description: One-time token from the install output.
+ email:
type: string
- enum:
- - publishable
- - secret
- scopes:
- type: array
- items:
- type: string
- example:
- - read_orders
- - write_orders
- "/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)."
- 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 key = await client.apiKeys.get('key_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api get /api_keys/{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: API key found
- 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.
-
- **Required scope:** `write_api_keys` (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',
- })
-
- // Only `name` is editable — scopes and key_type are fixed at creation.
- const key = await client.apiKeys.update('key_xxx', { name: 'CI key (renamed)' })
- - lang: bash
- label: Spree CLI
- source: spree api patch /api_keys/{id} -d '{"name":"CI key (renamed)"}'
- 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
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
+ format: email
+ password:
type: string
- example: Backend integration (renamed)
- delete:
- summary: Delete an API key
- tags:
- - API Keys
- security:
- - api_key: []
- bearer_auth: []
- description: "**Required scope:** `write_api_keys` (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.apiKeys.delete('key_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api delete /api_keys/{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: API key deleted
- "/api/v3/admin/api_keys/current":
+ example: Secret123!
+ password_confirmation:
+ type: string
+ example: Secret123!
+ first_name:
+ type: string
+ example: Olivia
+ last_name:
+ type: string
+ example: Owner
+ store_name:
+ type: string
+ example: My Store
+ 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.
+ example: US
+ locale:
+ type: string
+ description: Storefront locale. Defaults to the country's own language.
+ example: en
+ currency:
+ type: string
+ description: ISO 4217 currency. Defaults to the country's own currency
+ — pass one only when the store prices in something else.
+ example: USD
+ "/api/v3/admin/auth/setup/countries":
get:
- summary: Describe the current API key
+ summary: List countries for first-run setup
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.
-
- **Required scope:** none — any key can describe itself (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',
- })
-
- // Describes the key you authenticated with, including its live scopes.
- const key = await client.apiKeys.current()
- - lang: bash
- label: Spree CLI
- source: spree api get /api_keys/current
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
+ - Authentication
+ description: |
+ Countries the store can be set up in, each with the currency and
+ official languages derived from it. Unauthenticated, because the setup
+ screen runs before any credential exists. Returns 404 once any admin
+ user exists.
responses:
'200':
- description: current API key
- "/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.
-
- **Required scope:** `write_api_keys` (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 key = await client.apiKeys.revoke('key_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api patch /api_keys/{id}/revoke -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: API key revoked
- "/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.
- The rotatable refresh token is set in an HttpOnly cookie — it is not
- included in the response body.
-
- The `provider` field selects the authentication method. When omitted it
- defaults to `email`, the built-in email/password login.
-
- To authenticate against a third-party identity provider (Okta, Azure AD,
- Google Workspace SSO, a custom JWT issuer, SAML, etc.), send
- `{ "provider": "<your_key>", ... }` with the fields that provider
- requires. The endpoint returns the same JWT regardless of which provider
- authenticated the request. See
- [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
- for the list of configured providers and their required fields.
- 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 refresh token is set as an HttpOnly cookie; only `token` and `user` come back in the body.
- const auth = await client.auth.login({
- email: '[email protected]',
- password: 'password123',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /auth/login -d '{"email":"[email protected]","password":"password123"}'
- 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
- example: password123
- required:
- - email
- - password
- - title: ProviderLogin
- description: |
- Provider-dispatched login. The `provider` key selects a configured
- authentication provider; the remaining fields are forwarded to it.
- Required fields depend on the provider — see
- [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
- type: object
- properties:
- provider:
- type: string
- example: okta
- 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
- rotated refresh token cookie. No request body or Authorization header
- is required — the cookie alone authenticates the call.
- 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',
- })
-
- // Driven entirely by the HttpOnly refresh-token cookie + CSRF header (set by the SDK).
- const auth = await client.auth.refresh()
- - lang: bash
- label: Spree CLI
- source: spree api post /auth/refresh
- 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.
- 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.auth.logout()
- - lang: bash
- label: Spree CLI
- source: spree api post /auth/logout
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- responses:
- '204':
- description: logout successful
- "/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
- responses:
- '200':
- description: catalogs found
- 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
- '422':
- description: invalid request
- 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
- 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: expand
- in: query
- required: false
- description: Comma-separated. `catalog_price` adds the resolved price to every
- row.
- example: catalog_price
- schema:
- type: string
- 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.
-
- **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
- 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
- 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}/quantity_rules":
- get:
- summary: List catalog quantity rules
- tags:
- - Catalogs
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- The catalog's per-variant quantity terms. The catalog-wide default is a pair of fields on the catalog itself, so these are strictly the overrides.
-
- **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
- responses:
- '200':
- description: quantity rules found
- post:
- summary: Create a catalog quantity rule
- tags:
- - Catalogs
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- States how much of one variant a buyer on this agreement must order. Both fields are optional individually, but a rule must state at least one — a field left out falls through to the catalog default, and then to the variant.
-
- **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: quantity rule created
- '422':
- description: invalid request
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- variant_id:
- type: string
- example: variant_86Rf07xd4z
- minimum_order_quantity:
- type: integer
- nullable: true
- example: 48
- description: The least a buyer may order.
- order_multiple:
- type: integer
- nullable: true
- example: 24
- description: Orders must land on a multiple of this, counted from
- the minimum.
- required:
- - variant_id
- "/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
- responses:
- '200':
- description: order minimums found
+ description: countries
content:
application/json:
example:
- data:
- - id: com_UkLWZg9DAJ
+ countries:
+ - code: AD
+ name: Andorra
+ currency: EUR
+ locales:
+ - ca
+ - code: AE
+ name: United Arab Emirates
+ currency: AED
+ locales:
+ - ar
+ - code: AF
+ name: Afghanistan
+ currency: AFN
+ locales:
+ - ps
+ - uz
+ - tk
+ - code: AG
+ name: Antigua and Barbuda
+ currency: XCD
+ locales:
+ - en
+ - code: AI
+ name: Anguilla
+ currency: XCD
+ locales:
+ - en
+ - code: AL
+ name: Albania
+ currency: ALL
+ locales:
+ - sq
+ - code: AM
+ name: Armenia
+ currency: AMD
+ locales:
+ - hy
+ - code: AO
+ name: Angola
+ currency: AOA
+ locales:
+ - pt
+ - code: AR
+ name: Argentina
+ currency: ARS
+ locales:
+ - es
+ - gn
+ - code: AS
+ name: American Samoa
currency: USD
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- amount: '500.0'
- display_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.0'
- display_amount: "$500.00"
- '422':
- description: invalid request
- 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}/quantity_rules/{id}":
- patch:
- summary: Update a catalog quantity rule
- tags:
- - Catalogs
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Restates one variant term. A field sent as null hands that field back to the catalog default; a rule must still state at least one of the two.
-
- **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: quantity rule updated
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- minimum_order_quantity:
- type: integer
- nullable: true
- example: 96
- order_multiple:
- type: integer
- nullable: true
- example: 48
- delete:
- summary: Delete a catalog quantity rule
- tags:
- - Catalogs
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Drops one variant's exception, so it falls back to the catalog's own default.
-
- **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: quantity rule deleted
- "/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
- 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: |-
- Lifts the threshold for one currency, so orders in it may come to any total.
-
- **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}/product_terms":
- get:
- summary: List catalog terms by product
- tags:
- - Catalogs
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- The catalog's quantity terms at the grain a merchant states them: one entry per product, over rows the database keeps per variant. `mixed` marks a product whose variants carry different terms.
-
- **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
- responses:
- '200':
- description: product terms found
- put:
- summary: Set catalog terms by product
- tags:
- - Catalogs
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Writes the given products' terms in one request, keyed by prefixed product id. 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 — this is the one catalog-term surface that is not a whole-set replacement, because an agreement may name terms for thousands of SKUs.
-
- **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: product terms 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
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- 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')
- - lang: bash
- label: Spree CLI
- 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:
- 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:
- schema:
- "$ref": "#/components/schemas/Catalog"
- "/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).
-
- **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: 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
- 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.
-
- **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
- example: Shirts
- parent_id:
- type: string
- example: ctg_abc123
- 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.
-
- **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.
-
- **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
- example: Apparel
- 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.
-
- **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.
-
- **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.
-
- **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
- responses:
- '200':
- description: products found
- content:
- application/json:
- example:
- data: []
- meta:
- page: 1
- limit: 25
- count: 0
- pages: 1
- from: 0
- to: 0
- in: 0
- 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 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.
-
- **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
- 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 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.
-
- **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
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- product_ids:
- type: array
- items:
- type: string
- example:
- - prod_abc123
- 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.
-
- **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.
-
- **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: channels } = await client.channels.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /channels
- 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
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- 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
- URL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's
- derived from `name`.
-
-
- **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',
- })
-
- // `code` is optional — when omitted it's derived from `name`
- // ("Point of Sale" → "point-of-sale").
- const channel = await client.channels.create({
- name: 'Point of Sale',
- code: 'pos',
- active: true,
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /channels -d '{"name":"Point of Sale","code":"pos","active":true}'
- 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
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - name
- properties:
- name:
- type: string
- example: Point of Sale
- code:
- type: string
- example: pos
- description: Slug — auto-derived from `name` when blank.
- active:
- type: boolean
- default: true
- default:
- type: boolean
- default: false
- preferred_order_routing_strategy:
- type: string
- nullable: true
- description: Routing strategy class name. `null` inherits the store
- setting.
- preferred_storefront_access:
- type: string
- nullable: true
- enum:
- - public
- - prices_hidden
- - login_required
- description: Anonymous-visitor access posture. `null` inherits the
- store setting.
- preferred_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)."
- 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 channel = await client.channels.get('channel_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api get /channels/{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: channel found
- patch:
- summary: Update a channel
- tags:
- - Channels
- security:
- - api_key: []
- bearer_auth: []
- description: "**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 channel = await client.channels.update('channel_xxx', {
- name: 'Wholesale (Updated)',
- active: false,
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /channels/{id} -d '{"name":"Wholesale (Updated)","active":false}'
- parameters:
- - 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
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- code:
- type: string
- active:
- type: boolean
- default:
- type: boolean
- preferred_order_routing_strategy:
- type: string
- nullable: true
- description: Routing strategy class name. `null` inherits the store
- setting.
- preferred_storefront_access:
- type: string
- nullable: true
- enum:
- - public
- - prices_hidden
- - login_required
- description: Anonymous-visitor access posture. `null` inherits the
- store setting.
- preferred_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)."
- 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.channels.delete('channel_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api delete /channels/{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: 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
- an already-published product updates its publication window. Products from
- sibling stores are silently dropped.
-
-
- **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',
- })
-
- // Idempotent — re-publishing an already-published product updates its
- // publication window. `published_at`/`unpublished_at` are optional:
- // `null` (or omitted) means live immediately and never come down.
- const { product_count } = await client.channels.addProducts('channel_xxx', {
- product_ids: ['prod_xxx', 'prod_yyy'],
- published_at: '2026-07-01T00:00:00Z',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /channels/{id}/add_products -d '{"product_ids":["prod_xxx","prod_yyy"],"published_at":"2026-07-01T00:00:00Z"}'
- parameters:
- - 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.
-
- **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 { product_count } = await client.channels.removeProducts('channel_xxx', {
- product_ids: ['prod_xxx', 'prod_yyy'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /channels/{id}/remove_products -d '{"product_ids":["prod_xxx","prod_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: 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/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[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: q[active_eq]
- in: query
- required: false
- description: Filter by active flag
- schema:
- type: boolean
- - name: sort
- in: query
- required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
- schema:
- type: string
- responses:
- '200':
- description: claim reasons found
- '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.
-
- **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 reason = await client.claimReasons.create({
- name: 'Arrived damaged',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /claim_reasons -d '{"name":"Arrived damaged"}'
- parameters:
- - name: x-spree-api-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
- '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
- 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
- required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- responses:
- '200':
- description: claim reason found
- '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
- 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'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const reason = await client.claimReasons.update('clr_UkLWZg9DAJ', {
- active: false,
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /claim_reasons/{id} -d '{"active":false}'
- parameters:
- - name: x-spree-api-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
- 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
- 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/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
- 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: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., rules, custom_fields,
- translations).
- schema:
- type: string
- 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`.
-
- **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
- 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: Spree::CollectionRules::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:
- 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.
-
- **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
- 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
- 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.
-
- **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.
-
- **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
- 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.
-
- **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
- 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 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.
-
- **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
- 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":
- 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.
-
- **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`.
-
- **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
- "/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
- 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:** `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',
- })
-
- // `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 get /commission_lines -d '{"page":1,"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: 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[seller_id_eq]
- in: query
- required: false
- description: Filter to one seller
- schema:
- type: string
- - name: q[order_id_eq]
- in: query
- required: false
- description: Filter to one order
- schema:
- type: string
- - name: sort
- in: query
- required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
- schema:
- type: string
- 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.
-
- 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
- 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[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: q[enabled_eq]
- in: query
- required: false
- description: Filter by whether the rate is in use
- schema:
- type: boolean
- - name: sort
- in: query
- required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-position`).
- schema:
- type: string
- 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:
- example:
- error:
- code: authentication_required
- message: Authentication required
- 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.
-
- `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
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '201':
- description: commission rate created
- content:
- application/json:
- example:
- 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/CommissionRate"
- '422':
- description: validation failed
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: needs a flat fee amount in at least one currency
- details:
- base:
- - needs a flat fee amount in at least one currency
- 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.
- 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:
- type: string
- example: '0.21'
- 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
- 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 preference_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
- the configuration it takes — so a client builds its editor from what
- this marketplace has rather than a list hardcoded to match core's.
-
- `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
- 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
- preference_schema:
- - key: seller_ids
- type: array
- default: []
- association_fields: []
- - type: category_rule
- name: Category
- description: Charges this rate only for products in the selected
- categories, and anything filed beneath them
- preference_schema:
- - key: category_ids
- type: array
- default: []
- association_fields: []
- - type: product_rule
- name: Product
- description: Charges this rate only for the selected products
- preference_schema: []
- association_fields:
- - product_ids
- - type: item_total_rule
- name: Sale value
- description: Charges this rate only on sales within a value range
- preference_schema:
- - key: min_amount
- type: decimal
- default:
- - key: max_amount
- type: decimal
- default:
- 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
- preference_schema:
- type: array
- items:
- type: object
- 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
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- 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.0'
- commission_tax_rate:
- amounts: {}
- bounds: {}
- global: true
- rules: []
- schema:
- "$ref": "#/components/schemas/CommissionRate"
- '404':
- description: commission rate not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Commission rate not found
- 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"}}]}'
- parameters:
- - 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:
- 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.0'
- commission_tax_rate:
- amounts: {}
- bounds: {}
- global: true
- rules: []
- 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
- tags:
- - Commission Rates
- 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',
- })
-
- // 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
- 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.
-
- **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
- 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
- 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
- responses:
- '200':
- description: certificates 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:
- 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: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- 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
- 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`.
-
-
- **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: certificate 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:
- 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
- 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:
- 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:
- - 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
- 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).
- 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: certificate verified
- "/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.
-
- **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:
- '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).
- 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
- 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
- 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_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: registrations } = await client.companies.taxIdentifiers.list('comp_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /companies/{company_id}/tax_identifiers
- responses:
- '200':
- description: registrations found
- content:
- application/json:
- example:
- data:
- - 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'
- validatable: false
- customer_id:
- cart_id:
- order_id:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- 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: validation_error
- message: Registration type has already been taken
- details:
- kind:
- - has already been taken
- 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
- 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
- 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:
- '422':
- description: no validator installed for this kind
- 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":
- get:
- summary: List companies
- tags:
- - Companies
- 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',
- })
-
- const { data: companies } = await client.companies.list({ name_cont: 'Acme' })
- - lang: bash
- label: Spree CLI
- source: spree api get /companies -d '{"name_cont":"Acme"}'
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: companies 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: {}
- 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
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- 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.
-
- **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',
- })
-
- const company = await client.companies.create({
- name: 'Globex Corporation',
- external_references: { erp: 'GLBX-42' },
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /companies -d '{"name":"Globex Corporation","external_references":{"erp":"GLBX-42"}}'
- 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:
- example:
- id: comp_gbHJdmfrXB
- name: Globex Corporation
- kind: company
- po_number_required: false
- parent_id:
- ancestors: []
- external_references:
- erp: GLBX-42
- metadata: {}
- 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:
- - can't be blank
- requestBody:
- content:
- application/json:
- schema:
- type: object
- 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:
- type: string
- nullable: true
- description: The parent node. Omit for a root.
- example: comp_86Rf07xd4z
- 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
- example: erp
- external_id:
- type: string
- example: GLBX-42
- required:
- - system
- - external_id
- required:
- - name
- "/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
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: coupon codes found
- "/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]=Spree::Product` to narrow to one parent type.
-
- **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: definitions } = await client.customFieldDefinitions.list({
- q: { resource_type_eq: 'Spree::Product' },
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /custom_field_definitions -d '{"q":{"resource_type_eq":"Spree::Product"}}'
- 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. 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: definitions returned
- post:
- summary: Create a custom field definition
- tags:
- - Custom Fields
- security:
- - api_key: []
- bearer_auth: []
- description: "**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 definition = await client.customFieldDefinitions.create({
- namespace: 'specs',
- key: 'origin',
- label: 'Country of Origin',
- field_type: 'short_text',
- resource_type: 'Spree::Product',
- storefront_visible: true,
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /custom_field_definitions -d '{"namespace":"specs","key":"origin","label":"Country
- of Origin","field_type":"short_text","resource_type":"Spree::Product","storefront_visible":true}'
- 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
- 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 identifier (one of the registered
- field-type class names).
- resource_type:
- type: string
- description: Owner class, e.g. `Spree::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)."
- 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 definition = await client.customFieldDefinitions.get('cfd_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /custom_field_definitions/{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., key,label,field_type).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: definition found
- patch:
- summary: Update a custom field definition
- tags:
- - Custom Fields
- security:
- - api_key: []
- bearer_auth: []
- description: "**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 definition = await client.customFieldDefinitions.update('cfd_UkLWZg9DAJ', {
- label: 'Country of Origin',
- storefront_visible: false,
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /custom_field_definitions/{id} -d '{"label":"Country
- of Origin","storefront_visible":false}'
- 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
- 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.
-
- **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.customFieldDefinitions.delete('cfd_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /custom_field_definitions/{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: definition deleted
- "/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
- 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. The two differ where a class has been renamed — categories are
- stored under `Spree::Taxon` and shown as "Categories" — so send the
- value back verbatim rather than deriving it from the name.
-
-
- **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
- 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
- example: Spree::Seller
- name:
- type: string
- example: Sellers
- "/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
- segment customers for targeted promotions (see the `customer_group`
- promotion rule) and reporting. The list endpoint never embeds the
- member list — fetch a single group with `?expand=customers` if you
- need them inline, or query `/admin/customers?customer_group_id_in=…`
- for paginated membership.
-
-
- **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: groups } = await client.customerGroups.list({ page: 1, limit: 25 })
- - lang: bash
- label: Spree CLI
- source: spree api get /customer_groups -d '{"page":1,"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: 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[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - 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
- responses:
- '200':
- description: customer groups found
- content:
- application/json:
- example:
- data:
- - id: cg_UkLWZg9DAJ
- name: VIPs
- description: Top spenders
- customers_count: 0
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- - id: cg_gbHJdmfrXB
- name: Wholesale
- description:
- customers_count: 0
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- 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/CustomerGroup"
- 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 customer group
- tags:
- - Customer Groups
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Creates a customer group in the current store. `customer_ids` is
- optional; when present, customers are attached at create time.
- Pass prefixed IDs (e.g. `cus_…`) — the server decodes them
- automatically.
-
-
- **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',
- })
-
- const group = await client.customerGroups.create({
- name: 'VIP customers',
- description: 'Top spenders, eligible for early access',
- customer_ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customer_groups -d '{"name":"VIP customers","description":"Top
- spenders, eligible for early access","customer_ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"]}'
- 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
- example: Wholesale
- description:
- type: string
- example: B2B accounts
- nullable: true
- customer_ids:
- type: array
- items:
- type: string
- example:
- - cus_UkLWZg9DAJ
- "/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
- the full member list inline (recommended only for single-record
- reads — embed cost scales with membership size).
-
-
- **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',
- })
-
- // Pass `expand: ['customers']` to embed the group's customers in the response
- // — omit it for the much smaller index-payload shape.
- const group = await client.customerGroups.get('cg_UkLWZg9DAJ', { expand: ['customers'] })
- - lang: bash
- label: Spree CLI
- source: spree api get /customer_groups/{id} -d '{"expand":["customers"]}'
- 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
- full-set replacement — the server reconciles the membership to
- match the array, adding new IDs and removing ones not present.
- Send `customer_ids: []` to clear all members.
-
-
- **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',
- })
-
- // `customer_ids` is a full-set update — the model reconciles the membership
- // to match the array (adds new IDs, removes ones not present).
- const group = await client.customerGroups.update('cg_UkLWZg9DAJ', {
- name: 'VIP customers (Q1)',
- customer_ids: ['cus_UkLWZg9DAJ'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /customer_groups/{id} -d '{"name":"VIP customers (Q1)","customer_ids":["cus_UkLWZg9DAJ"]}'
- parameters:
- - 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
- example: VIP customers (Q1)
- description:
- type: string
- example: Updated description
- nullable: true
- customer_ids:
- type: array
- items:
- type: string
- example:
- - cus_UkLWZg9DAJ
- 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.
-
- **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',
- })
-
- await client.customerGroups.delete('cg_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /customer_groups/{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: customer group deleted
- "/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.
-
- **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: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /customers/{customer_id}/addresses
- 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
- responses:
- '200':
- description: addresses found
- 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.
-
- **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',
- })
-
- const address = await client.customers.addresses.create('cus_UkLWZg9DAJ', {
- 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',
- label: 'Office',
- is_default_shipping: true,
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customers/{customer_id}/addresses -d '{"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","label":"Office","is_default_shipping":true}'
- 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
- 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.
-
- **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',
- })
-
- const address = await client.customers.addresses.update('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ', {
- city: 'Manhattan',
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /customers/{customer_id}/addresses/{id} -d '{"city":"Manhattan"}'
- 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
- 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).
-
- **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',
- })
-
- await client.customers.addresses.delete('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /customers/{customer_id}/addresses/{id}
- 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 }`.
-
- **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: cards } = await client.customers.creditCards.list('cus_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /customers/{customer_id}/credit_cards
- 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
- responses:
- '200':
- description: credit cards found
- "/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.
-
- **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 card = await client.customers.creditCards.get('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /customers/{customer_id}/credit_cards/{id}
- 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
- delete:
- summary: Delete a customer credit card
- tags:
- - Customers
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Deletes a saved credit card.
-
- **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',
- })
-
- await client.customers.creditCards.delete('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /customers/{customer_id}/credit_cards/{id}
- 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.
-
- **Required scope:** `read_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',
- })
-
- const { data: storeCredits } = await client.customers.storeCredits.list('cus_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /customers/{customer_id}/store_credits
- 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., 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
- responses:
- '200':
- description: store credits found
- 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.
-
- **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',
- })
-
- const credit = await client.customers.storeCredits.create('cus_UkLWZg9DAJ', {
- amount: '25.00',
- currency: 'USD',
- memo: 'Goodwill credit',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customers/{customer_id}/store_credits -d '{"amount":"25.00","currency":"USD","memo":"Goodwill
- credit"}'
- 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
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - amount
- - currency
- properties:
- amount:
- type: string
- example: '50.00'
- currency:
- type: string
- example: USD
- 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`.
-
- **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',
- })
-
- const credit = await client.customers.storeCredits.update('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ', {
- memo: 'Reissued for damaged shipment',
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /customers/{customer_id}/store_credits/{id} -d '{"memo":"Reissued
- for damaged shipment"}'
- 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
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- amount:
- type: string
- example: '50.00'
- 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.
-
- **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',
- })
-
- await client.customers.storeCredits.delete('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /customers/{customer_id}/store_credits/{id}
- 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.
-
- **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: customers } = await client.customers.list({
- search: 'jane',
- sort: '-created_at',
- limit: 25,
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /customers -d '{"search":"jane","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: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: q[search]
- in: query
- required: false
- description: Email + name full-text-ish search
- schema:
- type: string
- - 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
- responses:
- '200':
- description: customers found
- post:
- summary: Create a customer
- tags:
- - Customers
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Creates a customer. No welcome email is sent automatically.
-
- **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',
- })
-
- const customer = await client.customers.create({
- email: '[email protected]',
- first_name: 'Jane',
- last_name: 'Doe',
- phone: '+1 212 555 1234',
- tags: ['wholesale'],
- accepts_email_marketing: true,
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customers -d '{"email":"[email protected]","first_name":"Jane","last_name":"Doe","phone":"+1
- 212 555 1234","tags":["wholesale"],"accepts_email_marketing":true}'
- 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
- 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).
-
- **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 customer = await client.customers.get('cus_UkLWZg9DAJ', {
- expand: ['addresses', 'store_credits'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /customers/{id} -d '{"expand":["addresses","store_credits"]}'
- 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
- patch:
- summary: Update a customer
- tags:
- - Customers
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Updates customer attributes. `tags` replaces the full set.
-
- **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',
- })
-
- const customer = await client.customers.update('cus_UkLWZg9DAJ', {
- first_name: 'Updated',
- tags: ['wholesale', 'vip'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /customers/{id} -d '{"first_name":"Updated","tags":["wholesale","vip"]}'
- 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
- 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.
-
- **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',
- })
-
- await client.customers.delete('cus_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /customers/{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: 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`.
- Idempotent — customers already in a group are skipped server-side.
- Groups from sibling stores are silently ignored. Returns counts of
- customers and groups that were processed (post store-scoping).
-
-
- **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',
- })
-
- const result = await client.customers.bulkAddToGroups({
- ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
- customer_group_ids: ['cg_UkLWZg9DAJ'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customers/bulk_add_to_groups -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
- parameters:
- - 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
- example:
- - cus_UkLWZg9DAJ
- - cus_QrLWXg9CAJ
- customer_group_ids:
- type: array
- items:
- type: string
- example:
- - cg_UkLWZg9DAJ
- "/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`.
- No-op for non-members. Groups from sibling stores are silently ignored.
-
-
- **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',
- })
-
- const result = await client.customers.bulkRemoveFromGroups({
- ids: ['cus_UkLWZg9DAJ'],
- customer_group_ids: ['cg_UkLWZg9DAJ'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customers/bulk_remove_from_groups -d '{"ids":["cus_UkLWZg9DAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
- parameters:
- - 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
- example:
- - cus_UkLWZg9DAJ
- customer_group_ids:
- type: array
- items:
- type: string
- example:
- - cg_UkLWZg9DAJ
- "/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
- upserted by name; re-adding an existing tag is a no-op.
-
-
- **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',
- })
-
- const result = await client.customers.bulkAddTags({
- ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
- tags: ['vip', 'newsletter'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customers/bulk_add_tags -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"tags":["vip","newsletter"]}'
- parameters:
- - 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
- example:
- - cus_UkLWZg9DAJ
- tags:
- type: array
- items:
- type: string
- example:
- - vip
- - newsletter
- "/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
- for customers that don't carry the tag.
-
-
- **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',
- })
-
- const result = await client.customers.bulkRemoveTags({
- ids: ['cus_UkLWZg9DAJ'],
- tags: ['vip'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /customers/bulk_remove_tags -d '{"ids":["cus_UkLWZg9DAJ"],"tags":["vip"]}'
- parameters:
- - 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
- example:
- - cus_UkLWZg9DAJ
- tags:
- type: array
- items:
- type: string
- example:
- - vip
- "/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.
-
- **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 profiles = await client.deliveryProfiles.list()
- - lang: bash
- label: Spree CLI
- 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
- responses:
- '200':
- description: delivery profiles found
- 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.
-
- **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 profile = await client.deliveryProfiles.create({
- name: 'Oversized',
- stock_location_ids: ['sloc_86Rf07xd4z'],
- })
- - lang: bash
- label: Spree CLI
- 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: delivery profile created
- '422':
- description: validation error
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- 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:
- - 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.
-
- **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 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 /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: origin group created
- 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
- tags:
- - Delivery
- security:
- - api_key: []
- bearer_auth: []
- description: "**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 profile = await client.deliveryProfiles.update('fp_86Rf07xd4z', {
- name: 'Oversized freight',
- stock_location_ids: [],
- })
- - lang: bash
- label: Spree CLI
- 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: delivery profile updated
- 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":
- get:
- summary: List delivery methods
- tags:
- - Delivery
- 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'
-
- 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
- parameters:
- - 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 methods found
- 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.
-
- **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 deliveryMethod = await client.deliveryMethods.create({
- name: 'Express',
- storefront_visible: true,
- calculator_type: 'Spree::Calculator::Shipping::FlatRate',
- calculator_preferences: { amount: 12.5 },
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /delivery_methods -d '{"name":"Express","storefront_visible":true,"calculator_type":"Spree::Calculator::Shipping::FlatRate","calculator_preferences":{"amount":12.5}}'
- 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
- 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: Spree::FulfillmentProvider::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:
- type: string
- example: Spree::Calculator::Shipping::FlatRate
- calculator_preferences:
- type: object
- example:
- amount: 12.5
- 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.
-
- **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
- "/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).
-
- **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 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"}]}'
- 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
- 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/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`).
-
- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (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: exports } = await client.exports.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /exports
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: exports found
- 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
- optional Ransack query (same shape used by the `q[...]` params on list endpoints)
- that filters which records are exported. Pass `record_selection: "all"` to
- clear the filter server-side and export everything in scope.
-
- Generation is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,
- then redirect the browser to `download_url` to fetch the file.
-
-
- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (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 exp = await client.exports.create({
- type: 'Spree::Exports::Products',
- search_params: { name_cont: 'shirt' },
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /exports -d '{"type":"Spree::Exports::Products","search_params":{"name_cont":"shirt"}}'
- 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
- 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
- example: products
- record_selection:
- type: string
- enum:
- - filtered
- - all
- description: Set to "all" to ignore search_params and export everything
- in scope.
- example: filtered
- search_params:
- type: object
- description: Ransack query hash. Same predicates accepted by the
- list endpoint.
- example:
- name_cont: shirt
- 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.
- example: https://admin.example.com/store_abc/exports
- "/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.
-
- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (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 exp = await client.exports.get('exp_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api get /exports/{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: export found
- delete:
- summary: Delete an export
- tags:
- - Exports
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Removes the export and purges its attachment.
-
- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (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.exports.delete('exp_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api delete /exports/{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: 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.
-
- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (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',
- })
-
- // Fetch with the Bearer token, then drive the browser download:
- const res = await fetch(exp.download_url, {
- headers: { Authorization: `Bearer ${token}` },
- })
- const blob = await res.blob()
- const url = URL.createObjectURL(blob)
- const a = Object.assign(document.createElement('a'), {
- href: url,
- download: exp.filename,
- })
- a.click()
- URL.revokeObjectURL(url)
- - lang: bash
- label: Spree CLI
- source: spree api get /exports/{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: id
- in: path
- required: true
- schema:
- type: string
- responses:
- '200':
- description: CSV file
- content:
- text/csv:
- schema:
- type: string
- format: binary
- "/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
- groups the cards generated together for a campaign or bulk-issuance
- — the cards themselves live under `/admin/gift_cards` and reference
- the batch via `gift_card_batch_id`.
-
-
- **Required scope:** `read_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',
- })
-
- const { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })
- - lang: bash
- label: Spree CLI
- source: spree api get /gift_card_batches -d '{"page":1,"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: 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[prefix_cont]
- in: query
- required: false
- description: Filter by prefix (contains)
- schema:
- type: string
- - name: sort
- in: query
- required: false
- description: Sort by field. Prefix with `-` for descending.
- schema:
- type: string
- 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
- `codes_count` cards inline for small batches (configurable via
- `Spree.config.gift_card_batch_web_limit`, default 500) or enqueues
- a background job for larger ones. Each card's code is the batch
- `prefix` followed by random hex.
-
-
- **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',
- })
-
- const batch = await client.giftCardBatches.create({
- prefix: 'WELCOME',
- amount: '25.00',
- currency: 'USD',
- codes_count: 100,
- expires_at: '2030-12-31',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /gift_card_batches -d '{"prefix":"WELCOME","amount":"25.00","currency":"USD","codes_count":100,"expires_at":"2030-12-31"}'
- 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:
- example:
- id: gcb_gbHJdmfrXB
- codes_count: 5
- currency: USD
- prefix: NEWCAMP
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- amount: '25.0'
- expires_at: '2030-12-31'
- created_by_id: adm_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/GiftCardBatch"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Prefix can't be blank
- details:
- prefix:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - prefix
- - amount
- - codes_count
- properties:
- prefix:
- type: string
- example: WELCOME
- description: Lowercased and prepended to every generated code.
- amount:
- type: string
- example: '25.00'
- description: Decimal amount per card, greater than zero.
- currency:
- type: string
- example: USD
- description: ISO 4217 currency code. Defaults to the store currency.
- codes_count:
- type: integer
- example: 100
- description: Number of cards to generate. Capped at `gift_card_batch_limit`.
- expires_at:
- type: string
- example: '2030-12-31'
- 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.
-
- **Required scope:** `read_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',
- })
-
- const batch = await client.giftCardBatches.get('gcb_K3zr8x')
- - lang: bash
- label: Spree CLI
- source: spree api get /gift_card_batches/{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: gift card batch found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/GiftCardBatch"
- '404':
- description: gift card batch not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Gift card batch not found
- 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
- `q[code_cont]` for code search, `q[user_id_eq]` for cards issued
- to a specific customer, or `q[status_eq]` for status filtering.
-
-
- **Required scope:** `read_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',
- })
-
- const { data: giftCards } = await client.giftCards.list({
- page: 1,
- limit: 25,
- expand: ['customer', 'created_by'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /gift_cards -d '{"page":1,"limit":25,"expand":["customer","created_by"]}'
- parameters:
- - name: x-spree-api-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[code_cont]
- in: query
- required: false
- description: Filter by gift card code (contains)
- schema:
- type: string
- - name: q[status_eq]
- in: query
- required: false
- description: Filter by status (active, redeemed, partially_redeemed, canceled)
- schema:
- type: string
- - 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
- responses:
- '200':
- description: gift cards found
- content:
- application/json:
- example:
- data:
- - id: gc_UkLWZg9DAJ
- code: C5BC700C4EF16A06
- status: active
- currency: USD
- amount: '50.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '50.0'
- display_amount: "$50.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$50.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:
- - id: gc_gbHJdmfrXB
- code: 3BECEA5A776AD146
- status: active
- currency: USD
- amount: '25.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '25.0'
- display_amount: "$25.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$25.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:
- 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/GiftCard"
- 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 gift card
- tags:
- - Gift Cards
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Issues a gift card scoped to the current store. The code is
- auto-generated when omitted. `currency` defaults to the store's
- configured currency. Pass `user_id` (prefixed ID) to attach the
- card to a specific customer.
-
-
- **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',
- })
-
- const giftCard = await client.giftCards.create({
- amount: '25.00',
- currency: 'USD',
- expires_at: '2030-12-31',
- user_id: 'cus_UkLWZg9DAJ',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /gift_cards -d '{"amount":"25.00","currency":"USD","expires_at":"2030-12-31","user_id":"cus_UkLWZg9DAJ"}'
- 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:
- example:
- id: gc_EfhxLZ9ck8
- code: A68048412201A26B
- status: active
- currency: USD
- amount: '25.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '25.0'
- display_amount: "$25.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$25.00"
- expires_at: '2030-12-31'
- 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: adm_UkLWZg9DAJ
- 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
- example: '25.00'
- description: Decimal amount, greater than zero.
- currency:
- type: string
- example: USD
- description: ISO 4217 currency code. Defaults to the store currency.
- code:
- type: string
- example: WELCOME50
- description: Optional caller-supplied code. Auto-generated when
- omitted.
- expires_at:
- type: string
- example: '2030-12-31'
- description: ISO 8601 date.
- nullable: true
- user_id:
- type: string
- example: cus_UkLWZg9DAJ
- 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.
-
- **Required scope:** `read_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',
- })
-
- const giftCard = await client.giftCards.get('gc_K3zr8x', {
- expand: ['customer', 'created_by', 'orders'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api get /gift_cards/{id} -d '{"expand":["customer","created_by","orders"]}'
- 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
- partially-redeemed cards cannot be edited.
-
-
- **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',
- })
-
- const giftCard = await client.giftCards.update('gc_K3zr8x', {
- amount: '75.00',
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /gift_cards/{id} -d '{"amount":"75.00"}'
- parameters:
- - 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
- example: '75.00'
- expires_at:
- type: string
- example: '2031-12-31'
- nullable: true
- user_id:
- type: string
- example: cus_UkLWZg9DAJ
- 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
- partially redeemed cannot be deleted and return 422.
-
-
- **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.giftCards.delete('gc_K3zr8x')
- - lang: bash
- label: Spree CLI
- source: spree api delete /gift_cards/{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: gift card deleted
- '422':
- description: redeemed gift card cannot be deleted
- "/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.
-
- **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:
- '200':
- description: imports found
- 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`
- and pass the returned `signed_id` as `attachment`. On success the import is in the
- `mapping` state and the response carries the mapping payload: `schema_fields`
- (the canonical columns for the type), `csv_headers`, a `sample_row`, and the
- auto-assigned `mappings`.
-
- Adjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`
- to start processing. Poll `GET /admin/imports/{id}` while `status` is
- `completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.
-
-
- **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
- '422':
- description: unknown import type
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - type
- - attachment
- properties:
- type:
- type: string
- enum:
- - products
- - customers
- - product_translations
- example: products
- attachment:
- type: string
- description: ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.
- example: eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed
- preferred_delimiter:
- type: string
- enum:
- - ","
- - ";"
- - "|"
- - "\t"
- description: CSV column separator. Defaults to a comma.
- example: ","
- 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.
- example: https://admin.example.com/store_abc/settings/imports
- "/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.
-
- **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:
- 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.
-
- **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`.
-
- **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
- 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.
-
- **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.
-
- **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:
- 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`
- to accept the auto-assigned ones from the create response. Returns 422 when a
- required schema field is left unmapped (`details.missing_required_fields`) or a
- file column is assigned twice.
-
-
- **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
- 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
- example: slug
- file_column:
- type: string
- nullable: true
- example: Product Handle
- "/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.
-
- **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
- "/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`.
-
- **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[status_eq]
- in: query
- required: false
- description: 'Filter rows by status: pending, processing, completed, failed.'
- schema:
- type: string
- responses:
- '200':
- description: rows found
- "/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.
-
- **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: integrations } = await client.integrations.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /integrations
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: integrations found
- 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.
-
- **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 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"}}'
- 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
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- type:
- 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'
- 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
- "/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
- "/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
- responses:
- '200':
- description: invitations found
- 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
- 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/{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
- "/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
- "/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
- store-scoped and ordered by `position` (an `acts_as_list` column —
- update the order via `PATCH /markets/{id}` with `position`).
-
-
- **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: markets } = await client.markets.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /markets
- 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
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: q[name_cont]
- in: query
- required: false
- schema:
- type: string
- - 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
- responses:
- '200':
- description: markets found
- content:
- application/json:
- example:
- data:
- - id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- - id: mkt_gbHJdmfrXB
- name: EU
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: false
- country_codes:
- - DE
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- 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/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.
-
- - `country_codes` accepts 2-letter ISO country codes (e.g. `["DE", "FR"]`);
- the market must contain at least one country. Unknown codes are
- silently dropped.
- - `supported_locales` accepts an array of locale codes; the
- `default_locale` is always implicitly included.
- - Setting `default: true` automatically demotes the previous default
- market in the store.
-
-
- **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 market = await client.markets.create({
- name: 'Europe',
- currency: 'EUR',
- default_locale: 'de',
- supported_locales: ['de', 'en', 'fr'],
- tax_inclusive: true,
- country_codes: ['DE', 'FR', 'IT'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /markets -d '{"name":"Europe","currency":"EUR","default_locale":"de","supported_locales":["de","en","fr"],"tax_inclusive":true,"country_codes":["DE","FR","IT"]}'
- 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
- example: Europe
- currency:
- type: string
- example: EUR
- description: ISO 4217 currency code.
- default_locale:
- type: string
- example: de
- 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.
- example:
- - de
- - en
- 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.
- example:
- - DE
- - FR
- 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)."
- 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 market = await client.markets.get('market_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api get /markets/{id}
- 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
- market's country list (full-set update), `supported_locales` to
- replace the supported locales, or `position` to reorder the market
- within the store.
-
- Setting `default: true` automatically demotes the previous default.
-
-
- **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',
- })
-
- // `country_codes` is a full-set update — the market is reconciled to match
- // the array (adds new countries, removes ones not present). Setting
- // `default: true` demotes the previous default market in the store.
- const market = await client.markets.update('market_UkLWZg9DAJ', {
- name: 'European Union',
- tax_inclusive: true,
- country_codes: ['DE', 'FR'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_codes":["DE","FR"]}'
- parameters:
- - 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
- the last remaining market in a store cannot be deleted — both return
- 422 with a `validation_error`.
-
-
- **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',
- })
-
- // Soft-deletes the market (sets `deleted_at`). The default market and the
- // last remaining market in a store cannot be deleted — both return 422.
- await client.markets.delete('market_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /markets/{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: market deleted
- '422':
- description: cannot delete default or last market
- "/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.
- 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 me = await client.me.get()
- if (
- me.permissions.some(
- (r) => r.allow && r.actions.includes('manage') && r.subjects.includes('Spree::Product'),
- )
- ) {
- // show "Create product" button
- }
- - lang: bash
- label: Spree CLI
- source: spree api get /me
- parameters:
- - name: x-spree-api-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:
- example:
- error:
- code: authentication_required
- message: Authentication required
- 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`).
- 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',
- })
-
- // Set the signed-in admin's own UI display language.
- const me = await client.me.update({
- selected_locale: 'de',
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /me -d '{"selected_locale":"de"}'
- parameters:
- - name: x-spree-api-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
- example: de
- first_name:
- type: string
- example: Ada
- last_name:
- type: string
- example: Lovelace
- "/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
- 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.
-
-
- **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: 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
- 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
- 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==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/library-upload.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d7596f383abfdff308e034c9ea5ad505acd7f2b4/library-upload.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e135576662c594d9c8cfd5a3e58d866defe22992/library-upload.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--aaf899c506d117d283f0ccd3e8cb48a41bdcee1d/library-upload.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--3c0bb7cacbaf66ddaa1c179a61a1e5a9e0a849f8/library-upload.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--717aa91ed068163f5b61bb03ed156b6f56fa991f/library-upload.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--4c20916daf771f49aa482b19600aa72bbfd820a6/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==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7e5aedb16bc1f8f3bb9766a4e2782205777e8468/library-upload.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13
- viewable_id:
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--46b5bc8c9df48d9ba0d459fb782d85ff2e4d1a13/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 43397
- owner_type: Spree::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:
- 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/option_types":
- get:
- summary: List option types
- tags:
- - Option Types
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Returns a paginated list of option types.
-
- **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: optionTypes } = await client.optionTypes.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /option_types
- parameters:
- - name: x-spree-api-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[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- 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 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.
-
- Option values can be provided inline and will be created or updated by name.
-
-
- **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 optionType = await client.optionTypes.create({
- name: 'color',
- label: 'Color',
- option_values: [
- { name: 'red', label: 'Red' },
- { name: 'navy', label: 'Navy' },
- ],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /option_types -d '{"name":"color","label":"Color","option_values":[{"name":"red","label":"Red"},{"name":"navy","label":"Navy"}]}'
- parameters:
- - name: x-spree-api-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
- example: color
- label:
- type: string
- example: Color
- position:
- type: integer
- example: 1
- filterable:
- type: boolean
- example: true
- option_values:
- type: array
- items:
- type: object
- properties:
- name:
- type: string
- example: red
- label:
- type: string
- example: Red
- 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.
-
- **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 optionType = await client.optionTypes.get('ot_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /option_types/{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: 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.
-
- **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 optionType = await client.optionTypes.update('ot_UkLWZg9DAJ', {
- label: 'Updated Label',
- option_values: [{ name: 'red', label: 'Crimson' }],
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /option_types/{id} -d '{"label":"Updated Label","option_values":[{"name":"red","label":"Crimson"}]}'
- parameters:
- - name: x-spree-api-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
- example: color
- label:
- type: string
- example: Color
- position:
- type: integer
- example: 1
- filterable:
- type: boolean
- example: true
- option_values:
- type: array
- items:
- type: object
- properties:
- id:
- type: string
- description: Existing option value ID to update
- name:
- type: string
- example: red
- label:
- type: string
- example: Red
- position:
- type: integer
- delete:
- summary: Delete an option type
- tags:
- - Option Types
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Deletes an option type.
-
- **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',
- })
-
- await client.optionTypes.delete('ot_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /option_types/{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: 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.
-
- **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: taxLines } = await client.orders.taxLines.list('or_abc123')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/tax_lines
- 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:
- '200':
- description: tax lines found
- "/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.
-
- **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
- 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:
- '200':
- description: discounts found
- 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.
-
- **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',
- })
-
- // 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"}'
- 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
- '422':
- description: invalid discount
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- label:
- type: string
- example: Customer appeasement
- value:
- type: number
- example: 10
- 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,
- kind: 'gift_wrap',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":4,"kind":"gift_wrap"}'
- 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
- '422':
- description: invalid fee
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- label:
- type: string
- example: Gift wrap
- amount:
- type: number
- example: 4
- kind:
- type: string
- enum:
- - surcharge
- - handling
- - gift_wrap
- - cod
- - payment
- - duty
- 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_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
- 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[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: q[active_eq]
- in: query
- required: false
- description: Filter by active flag
- schema:
- type: boolean
- - name: sort
- in: query
- required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
- schema:
- type: string
- responses:
- '200':
- description: order cancellation reasons found
- '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.
-
- **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 reason = await client.orderCancellationReasons.create({
- name: 'Out of stock',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /order_cancellation_reasons -d '{"name":"Out of stock"}'
- parameters:
- - name: x-spree-api-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
- '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
- 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
- get:
- summary: Get a order cancellation reason
- tags:
- - Reasons
- security:
- - api_key: []
- bearer_auth: []
- 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
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const reason = await client.orderCancellationReasons.get('ocr_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /order_cancellation_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: order cancellation reason found
- '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
- 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'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
-
- const reason = await client.orderCancellationReasons.update('ocr_UkLWZg9DAJ', {
- active: false,
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /order_cancellation_reasons/{id} -d '{"active":false}'
- parameters:
- - name: x-spree-api-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
- 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
- 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.orderCancellationReasons.delete('ocr_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /order_cancellation_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:
- '204':
- description: order cancellation reason deleted
- "/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.
-
- **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: rules } = await client.channels.orderRoutingRules.list('ch_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /channels/{channel_id}/order_routing_rules
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: rules found
- 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.
-
- **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 rule = await client.channels.orderRoutingRules.create('ch_UkLWZg9DAJ', {
- type: 'preferred_location',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /channels/{channel_id}/order_routing_rules -d '{"type":"preferred_location"}'
- 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
- '422':
- description: unknown rule type
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- type:
- type: string
- example: preferred_location
- 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.
-
- **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 rule = await client.channels.orderRoutingRules.update('ch_UkLWZg9DAJ', 'orule_k5nR8xLq', {
- active: false,
- position: 2,
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /channels/{channel_id}/order_routing_rules/{id} -d
- '{"active":false,"position":2}'
- parameters:
- - 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
- 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)."
- 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.channels.orderRoutingRules.delete('ch_UkLWZg9DAJ', 'orule_k5nR8xLq')
- - lang: bash
- label: Spree CLI
- source: spree api delete /channels/{channel_id}/order_routing_rules/{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: 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`.
-
- **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: ruleTypes } = await client.orderRoutingRules.types()
- - lang: bash
- label: Spree CLI
- source: spree api get /order_routing_rules/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: types found
- "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":
+ locales:
+ - en
+ - sm
+ - code: AT
+ name: Austria
+ currency: EUR
+ locales:
+ - de
+ - code: AU
+ name: Australia
+ currency: AUD
+ locales:
+ - en
+ - code: AW
+ name: Aruba
+ currency: AWG
+ locales:
+ - nl
+ - code: AZ
+ name: Azerbaijan
+ currency: AZN
+ locales:
+ - az
+ - hy
+ - code: BA
+ name: Bosnia and Herzegovina
+ currency: BAM
+ locales:
+ - bs
+ - hr
+ - sr
+ - code: BB
+ name: Barbados
+ currency: BBD
+ locales:
+ - en
+ - code: BD
+ name: Bangladesh
+ currency: BDT
+ locales:
+ - bn
+ - code: BE
+ name: Belgium
+ currency: EUR
+ locales:
+ - nl
+ - fr
+ - de
+ - code: BF
+ name: Burkina Faso
+ currency: XOF
+ locales:
+ - fr
+ - ff
+ - code: BG
+ name: Bulgaria
+ currency: EUR
+ locales:
+ - bg
+ - code: BH
+ name: Bahrain
+ currency: BHD
+ locales:
+ - ar
+ - code: BI
+ name: Burundi
+ currency: BIF
+ locales:
+ - fr
+ - rn
+ - code: BJ
+ name: Benin
+ currency: XOF
+ locales:
+ - fr
+ - code: BL
+ name: Saint Barthélemy
+ currency: EUR
+ locales:
+ - fr
+ - code: BM
+ name: Bermuda
+ currency: BMD
+ locales:
+ - en
+ - code: BN
+ name: Brunei Darussalam
+ currency: BND
+ locales:
+ - ms
+ - code: BO
+ name: Bolivia
+ currency: BOB
+ locales:
+ - es
+ - ay
+ - qu
+ - code: BQ
+ name: Bonaire, Sint Eustatius and Saba
+ currency: USD
+ locales:
+ - nl
+ - en
+ - code: BR
+ name: Brazil
+ currency: BRL
+ locales:
+ - pt
+ - code: BS
+ name: Bahamas
+ currency: BSD
+ locales:
+ - en
+ - code: BT
+ name: Bhutan
+ currency: BTN
+ locales:
+ - dz
+ - code: BW
+ name: Botswana
+ currency: BWP
+ locales:
+ - en
+ - tn
+ - code: BY
+ name: Belarus
+ currency: BYN
+ locales:
+ - be
+ - ru
+ - code: BZ
+ name: Belize
+ currency: BZD
+ locales:
+ - en
+ - es
+ - code: CA
+ name: Canada
+ currency: CAD
+ locales:
+ - en
+ - fr
+ - code: CC
+ name: Cocos (Keeling) Islands
+ currency: AUD
+ locales:
+ - en
+ - code: CD
+ name: Congo, The Democratic Republic of the
+ currency: CDF
+ locales:
+ - fr
+ - ln
+ - kg
+ - sw
+ - lu
+ - code: CF
+ name: Central African Republic
+ currency: XAF
+ locales:
+ - fr
+ - sg
+ - code: CG
+ name: Congo
+ currency: XAF
+ locales:
+ - fr
+ - ln
+ - code: CH
+ name: Switzerland
+ currency: CHF
+ locales:
+ - de
+ - fr
+ - it
+ - rm
+ - code: CI
+ name: Côte d'Ivoire
+ currency: XOF
+ locales:
+ - fr
+ - code: CK
+ name: Cook Islands
+ currency: NZD
+ locales:
+ - en
+ - code: CL
+ name: Chile
+ currency: CLP
+ locales:
+ - es
+ - code: CM
+ name: Cameroon
+ currency: XAF
+ locales:
+ - en
+ - fr
+ - code: CN
+ name: China
+ currency: CNY
+ locales:
+ - zh
+ - code: CO
+ name: Colombia
+ currency: COP
+ locales:
+ - es
+ - code: CR
+ name: Costa Rica
+ currency: CRC
+ locales:
+ - es
+ - code: CU
+ name: Cuba
+ currency: CUP
+ locales:
+ - es
+ - code: CV
+ name: Cabo Verde
+ currency: CVE
+ locales:
+ - pt
+ - code: CW
+ name: Curaçao
+ currency: XCG
+ locales:
+ - nl
+ - code: CX
+ name: Christmas Island
+ currency: AUD
+ locales:
+ - en
+ - zh
+ - ms
+ - code: CY
+ name: Cyprus
+ currency: EUR
+ locales:
+ - el
+ - tr
+ - hy
+ - code: CZ
+ name: Czechia
+ currency: CZK
+ locales:
+ - cs
+ - code: DE
+ name: Germany
+ currency: EUR
+ locales:
+ - de
+ - code: DJ
+ name: Djibouti
+ currency: DJF
+ locales:
+ - ar
+ - fr
+ - code: DK
+ name: Denmark
+ currency: DKK
+ locales:
+ - da
+ - code: DM
+ name: Dominica
+ currency: XCD
+ locales:
+ - en
+ - code: DO
+ name: Dominican Republic
+ currency: DOP
+ locales:
+ - es
+ - code: DZ
+ name: Algeria
+ currency: DZD
+ locales:
+ - ar
+ - code: EC
+ name: Ecuador
+ currency: USD
+ locales:
+ - es
+ - code: EE
+ name: Estonia
+ currency: EUR
+ locales:
+ - et
+ - code: EG
+ name: Egypt
+ currency: EGP
+ locales:
+ - ar
+ - code: ER
+ name: Eritrea
+ currency: ERN
+ locales:
+ - en
+ - ar
+ - ti
+ - code: ES
+ name: Spain
+ currency: EUR
+ locales:
+ - es
+ - code: ET
+ name: Ethiopia
+ currency: ETB
+ locales:
+ - am
+ - code: FI
+ name: Finland
+ currency: EUR
+ locales:
+ - fi
+ - sv
+ - code: FJ
+ name: Fiji
+ currency: FJD
+ locales:
+ - en
+ - fj
+ - hi
+ - code: FK
+ name: Falkland Islands (Malvinas)
+ currency: FKP
+ locales:
+ - en
+ - code: FM
+ name: Micronesia, Federated States of
+ currency: USD
+ locales:
+ - en
+ - code: FO
+ name: Faroe Islands
+ currency: DKK
+ locales:
+ - fo
+ - code: FR
+ name: France
+ currency: EUR
+ locales:
+ - fr
+ - code: GA
+ name: Gabon
+ currency: XAF
+ locales:
+ - fr
+ - code: GB
+ name: United Kingdom
+ currency: GBP
+ locales:
+ - en
+ - code: GD
+ name: Grenada
+ currency: XCD
+ locales:
+ - en
+ - code: GE
+ name: Georgia
+ currency: GEL
+ locales:
+ - ka
+ - code: GF
+ name: French Guiana
+ currency: EUR
+ locales:
+ - fr
+ - code: GG
+ name: Guernsey
+ currency: GBP
+ locales:
+ - en
+ - fr
+ - code: GH
+ name: Ghana
+ currency: GHS
+ locales:
+ - en
+ - code: GI
+ name: Gibraltar
+ currency: GIP
+ locales:
+ - en
+ - code: GL
+ name: Greenland
+ currency: DKK
+ locales:
+ - kl
+ - code: GM
+ name: Gambia
+ currency: GMD
+ locales:
+ - en
+ - code: GN
+ name: Guinea
+ currency: GNF
+ locales:
+ - fr
+ - ff
+ - code: GP
+ name: Guadeloupe
+ currency: EUR
+ locales:
+ - fr
+ - code: GQ
+ name: Equatorial Guinea
+ currency: XAF
+ locales:
+ - es
+ - fr
+ - code: GR
+ name: Greece
+ currency: EUR
+ locales:
+ - el
+ - code: GT
+ name: Guatemala
+ currency: GTQ
+ locales:
+ - es
+ - code: GU
+ name: Guam
+ currency: USD
+ locales:
+ - en
+ - ch
+ - es
+ - code: GW
+ name: Guinea-Bissau
+ currency: XOF
+ locales:
+ - pt
+ - code: GY
+ name: Guyana
+ currency: GYD
+ locales:
+ - en
+ - code: HK
+ name: Hong Kong
+ currency: HKD
+ locales:
+ - en
+ - zh
+ - code: HN
+ name: Honduras
+ currency: HNL
+ locales:
+ - es
+ - code: HR
+ name: Croatia
+ currency: EUR
+ locales:
+ - hr
+ - code: HT
+ name: Haiti
+ currency: HTG
+ locales:
+ - fr
+ - ht
+ - code: HU
+ name: Hungary
+ currency: HUF
+ locales:
+ - hu
+ - code: ID
+ name: Indonesia
+ currency: IDR
+ locales:
+ - id
+ - code: IE
+ name: Ireland
+ currency: EUR
+ locales:
+ - en
+ - ga
+ - code: IL
+ name: Israel
+ currency: ILS
+ locales:
+ - he
+ - ar
+ - code: IM
+ name: Isle of Man
+ currency: GBP
+ locales:
+ - en
+ - gv
+ - code: IN
+ name: India
+ currency: INR
+ locales:
+ - hi
+ - en
+ - code: IQ
+ name: Iraq
+ currency: IQD
+ locales:
+ - ar
+ - code: IR
+ name: Iran
+ currency: IRR
+ locales:
+ - fa
+ - code: IS
+ name: Iceland
+ currency: ISK
+ locales:
+ - is
+ - code: IT
+ name: Italy
+ currency: EUR
+ locales:
+ - it
+ - code: JE
+ name: Jersey
+ currency: GBP
+ locales:
+ - en
+ - fr
+ - code: JM
+ name: Jamaica
+ currency: JMD
+ locales:
+ - en
+ - code: JO
+ name: Jordan
+ currency: JOD
+ locales:
+ - ar
+ - code: JP
+ name: Japan
+ currency: JPY
+ locales:
+ - ja
+ - code: KE
+ name: Kenya
+ currency: KES
+ locales:
+ - en
+ - sw
+ - code: KG
+ name: Kyrgyzstan
+ currency: KGS
+ locales:
+ - ky
+ - ru
+ - code: KH
+ name: Cambodia
+ currency: KHR
+ locales:
+ - km
+ - code: KI
+ name: Kiribati
+ currency: AUD
+ locales:
+ - en
+ - code: KM
+ name: Comoros
+ currency: KMF
+ locales:
+ - ar
+ - fr
+ - code: KN
+ name: Saint Kitts and Nevis
+ currency: XCD
+ locales:
+ - en
+ - code: KP
+ name: North Korea
+ currency: KPW
+ locales:
+ - ko
+ - code: KR
+ name: South Korea
+ currency: KRW
+ locales:
+ - ko
+ - code: KW
+ name: Kuwait
+ currency: KWD
+ locales:
+ - ar
+ - code: KY
+ name: Cayman Islands
+ currency: KYD
+ locales:
+ - en
+ - code: KZ
+ name: Kazakhstan
+ currency: KZT
+ locales:
+ - kk
+ - ru
+ - code: LA
+ name: Lao People's Democratic Republic
+ currency: LAK
+ locales:
+ - lo
+ - code: LB
+ name: Lebanon
+ currency: LBP
+ locales:
+ - ar
+ - fr
+ - code: LC
+ name: Saint Lucia
+ currency: XCD
+ locales:
+ - en
+ - code: LI
+ name: Liechtenstein
+ currency: CHF
+ locales:
+ - de
+ - code: LK
+ name: Sri Lanka
+ currency: LKR
+ locales:
+ - si
+ - ta
+ - code: LR
+ name: Liberia
+ currency: LRD
+ locales:
+ - en
+ - code: LS
+ name: Lesotho
+ currency: LSL
+ locales:
+ - en
+ - st
+ - code: LT
+ name: Lithuania
+ currency: EUR
+ locales:
+ - lt
+ - code: LU
+ name: Luxembourg
+ currency: EUR
+ locales:
+ - fr
+ - de
+ - lb
+ - code: LV
+ name: Latvia
+ currency: EUR
+ locales:
+ - lv
+ - code: LY
+ name: Libya
+ currency: LYD
+ locales:
+ - ar
+ - code: MA
+ name: Morocco
+ currency: MAD
+ locales:
+ - ar
+ - code: MC
+ name: Monaco
+ currency: EUR
+ locales:
+ - fr
+ - code: MD
+ name: Moldova
+ currency: MDL
+ locales:
+ - ro
+ - code: ME
+ name: Montenegro
+ currency: EUR
+ locales:
+ - sr
+ - bs
+ - sq
+ - hr
+ - code: MF
+ name: Saint Martin (French part)
+ currency: EUR
+ locales:
+ - en
+ - fr
+ - nl
+ - code: MG
+ name: Madagascar
+ currency: MGA
+ locales:
+ - fr
+ - mg
+ - code: MH
+ name: Marshall Islands
+ currency: USD
+ locales:
+ - en
+ - mh
+ - code: MK
+ name: North Macedonia
+ currency: MKD
+ locales:
+ - mk
+ - code: ML
+ name: Mali
+ currency: XOF
+ locales:
+ - fr
+ - code: MM
+ name: Myanmar
+ currency: MMK
+ locales:
+ - my
+ - code: MN
+ name: Mongolia
+ currency: MNT
+ locales:
+ - mn
+ - code: MO
+ name: Macao
+ currency: MOP
+ locales:
+ - zh
+ - pt
+ - code: MP
+ name: Northern Mariana Islands
+ currency: USD
+ locales:
+ - en
+ - ch
+ - code: MQ
+ name: Martinique
+ currency: EUR
+ locales:
+ - fr
+ - code: MR
+ name: Mauritania
+ currency: MRU
+ locales:
+ - ar
+ - fr
+ - code: MS
+ name: Montserrat
+ currency: XCD
+ locales:
+ - en
+ - code: MT
+ name: Malta
+ currency: EUR
+ locales:
+ - mt
+ - en
+ - code: MU
+ name: Mauritius
+ currency: MUR
+ locales:
+ - en
+ - code: MV
+ name: Maldives
+ currency: MVR
+ locales:
+ - dv
+ - code: MW
+ name: Malawi
+ currency: MWK
+ locales:
+ - en
+ - ny
+ - code: MX
+ name: Mexico
+ currency: MXN
+ locales:
+ - es
+ - code: MY
+ name: Malaysia
+ currency: MYR
+ locales:
+ - ms
+ - en
+ - code: MZ
+ name: Mozambique
+ currency: MZN
+ locales:
+ - pt
+ - code: NA
+ name: Namibia
+ currency: NAD
+ locales:
+ - en
+ - af
+ - code: NC
+ name: New Caledonia
+ currency: XPF
+ locales:
+ - fr
+ - code: NE
+ name: Niger
+ currency: XOF
+ locales:
+ - fr
+ - code: NF
+ name: Norfolk Island
+ currency: AUD
+ locales:
+ - en
+ - code: NG
+ name: Nigeria
+ currency: NGN
+ locales:
+ - en
+ - code: NI
+ name: Nicaragua
+ currency: NIO
+ locales:
+ - es
+ - code: NL
+ name: Netherlands
+ currency: EUR
+ locales:
+ - nl
+ - code: 'NO'
+ name: Norway
+ currency: NOK
+ locales:
+ - nb
+ - nn
+ - code: NP
+ name: Nepal
+ currency: NPR
+ locales:
+ - ne
+ - code: NR
+ name: Nauru
+ currency: AUD
+ locales:
+ - en
+ - na
+ - code: NU
+ name: Niue
+ currency: NZD
+ locales:
+ - en
+ - code: NZ
+ name: New Zealand
+ currency: NZD
+ locales:
+ - en
+ - code: OM
+ name: Oman
+ currency: OMR
+ locales:
+ - ar
+ - code: PA
+ name: Panama
+ currency: PAB
+ locales:
+ - es
+ - code: PE
+ name: Peru
+ currency: PEN
+ locales:
+ - es
+ - code: PF
+ name: French Polynesia
+ currency: XPF
+ locales:
+ - fr
+ - code: PG
+ name: Papua New Guinea
+ currency: PGK
+ locales:
+ - en
+ - code: PH
+ name: Philippines
+ currency: PHP
+ locales:
+ - tl
+ - en
+ - code: PK
+ name: Pakistan
+ currency: PKR
+ locales:
+ - en
+ - ur
+ - code: PL
+ name: Poland
+ currency: PLN
+ locales:
+ - pl
+ - code: PM
+ name: Saint Pierre and Miquelon
+ currency: EUR
+ locales:
+ - fr
+ - code: PN
+ name: Pitcairn
+ currency: NZD
+ locales:
+ - en
+ - code: PR
+ name: Puerto Rico
+ currency: USD
+ locales:
+ - es
+ - en
+ - code: PS
+ name: Palestine, State of
+ currency: ILS
+ locales:
+ - ar
+ - he
+ - en
+ - code: PT
+ name: Portugal
+ currency: EUR
+ locales:
+ - pt
+ - code: PW
+ name: Palau
+ currency: USD
+ locales:
+ - en
+ - code: PY
+ name: Paraguay
+ currency: PYG
+ locales:
+ - es
+ - gn
+ - code: QA
+ name: Qatar
+ currency: QAR
+ locales:
+ - ar
+ - code: RE
+ name: Réunion
+ currency: EUR
+ locales:
+ - fr
+ - code: RO
+ name: Romania
+ currency: RON
+ locales:
+ - ro
+ - code: RS
+ name: Serbia
+ currency: RSD
+ locales:
+ - sr
+ - code: RU
+ name: Russian Federation
+ currency: RUB
+ locales:
+ - ru
+ - code: RW
+ name: Rwanda
+ currency: RWF
+ locales:
+ - rw
+ - en
+ - fr
+ - code: SA
+ name: Saudi Arabia
+ currency: SAR
+ locales:
+ - ar
+ - code: SB
+ name: Solomon Islands
+ currency: SBD
+ locales:
+ - en
+ - code: SC
+ name: Seychelles
+ currency: SCR
+ locales:
+ - fr
+ - en
+ - code: SD
+ name: Sudan
+ currency: SDG
+ locales:
+ - ar
+ - en
+ - code: SE
+ name: Sweden
+ currency: SEK
+ locales:
+ - sv
+ - code: SG
+ name: Singapore
+ currency: SGD
+ locales:
+ - en
+ - ms
+ - ta
+ - code: SH
+ name: Saint Helena, Ascension and Tristan da Cunha
+ currency: SHP
+ locales:
+ - en
+ - code: SI
+ name: Slovenia
+ currency: EUR
+ locales:
+ - sl
+ - code: SJ
+ name: Svalbard and Jan Mayen
+ currency: NOK
+ locales:
+ - 'no'
+ - code: SK
+ name: Slovakia
+ currency: EUR
+ locales:
+ - sk
+ - code: SL
+ name: Sierra Leone
+ currency: SLE
+ locales:
+ - en
+ - code: SM
+ name: San Marino
+ currency: EUR
+ locales:
+ - it
+ - code: SN
+ name: Senegal
+ currency: XOF
+ locales:
+ - fr
+ - code: SO
+ name: Somalia
+ currency: SOS
+ locales:
+ - so
+ - ar
+ - code: SR
+ name: Suriname
+ currency: SRD
+ locales:
+ - nl
+ - code: SS
+ name: South Sudan
+ currency: SSP
+ locales:
+ - ar
+ - en
+ - code: ST
+ name: Sao Tome and Principe
+ currency: STN
+ locales:
+ - pt
+ - code: SV
+ name: El Salvador
+ currency: USD
+ locales:
+ - es
+ - code: SX
+ name: Sint Maarten (Dutch part)
+ currency: XCG
+ locales:
+ - nl
+ - en
+ - code: SY
+ name: Syrian Arab Republic
+ currency: SYP
+ locales:
+ - ar
+ - code: SZ
+ name: Eswatini
+ currency: SZL
+ locales:
+ - en
+ - ss
+ - code: TC
+ name: Turks and Caicos Islands
+ currency: USD
+ locales:
+ - en
+ - code: TD
+ name: Chad
+ currency: XAF
+ locales:
+ - ar
+ - fr
+ - code: TG
+ name: Togo
+ currency: XOF
+ locales:
+ - fr
+ - code: TH
+ name: Thailand
+ currency: THB
+ locales:
+ - th
+ - code: TJ
+ name: Tajikistan
+ currency: TJS
+ locales:
+ - tg
+ - ru
+ - code: TK
+ name: Tokelau
+ currency: NZD
+ locales:
+ - en
+ - code: TL
+ name: Timor-Leste
+ currency: IDR
+ locales:
+ - pt
+ - code: TM
+ name: Turkmenistan
+ currency: TMT
+ locales:
+ - tk
+ - code: TN
+ name: Tunisia
+ currency: TND
+ locales:
+ - ar
+ - fr
+ - code: TO
+ name: Tonga
+ currency: TOP
+ locales:
+ - en
+ - to
+ - code: TR
+ name: Türkiye
+ currency: TRY
+ locales:
+ - tr
+ - code: TT
+ name: Trinidad and Tobago
+ currency: TTD
+ locales:
+ - en
+ - code: TV
+ name: Tuvalu
+ currency: AUD
+ locales:
+ - en
+ - code: TW
+ name: Taiwan
+ currency: TWD
+ locales:
+ - zh
+ - code: TZ
+ name: Tanzania
+ currency: TZS
+ locales:
+ - sw
+ - en
+ - code: UA
+ name: Ukraine
+ currency: UAH
+ locales:
+ - uk
+ - code: UG
+ name: Uganda
+ currency: UGX
+ locales:
+ - en
+ - sw
+ - code: US
+ name: United States
+ currency: USD
+ locales:
+ - en
+ - code: UY
+ name: Uruguay
+ currency: UYU
+ locales:
+ - es
+ - code: UZ
+ name: Uzbekistan
+ currency: UZS
+ locales:
+ - uz
+ - code: VA
+ name: Holy See (Vatican City State)
+ currency: EUR
+ locales:
+ - it
+ - la
+ - code: VC
+ name: Saint Vincent and the Grenadines
+ currency: XCD
+ locales:
+ - en
+ - code: VE
+ name: Venezuela
+ currency: VES
+ locales:
+ - es
+ - code: VG
+ name: Virgin Islands, British
+ currency: USD
+ locales:
+ - en
+ - code: VI
+ name: Virgin Islands, U.S.
+ currency: USD
+ locales:
+ - en
+ - code: VN
+ name: Vietnam
+ currency: VND
+ locales:
+ - vi
+ - code: VU
+ name: Vanuatu
+ currency: VUV
+ locales:
+ - bi
+ - en
+ - fr
+ - code: WF
+ name: Wallis and Futuna
+ currency: XPF
+ locales:
+ - fr
+ - code: WS
+ name: Samoa
+ currency: WST
+ locales:
+ - sm
+ - en
+ - code: YE
+ name: Yemen
+ currency: YER
+ locales:
+ - ar
+ - code: YT
+ name: Mayotte
+ currency: EUR
+ locales:
+ - fr
+ - code: ZA
+ name: South Africa
+ currency: ZAR
+ locales:
+ - af
+ - en
+ - nr
+ - st
+ - ss
+ - tn
+ - ts
+ - ve
+ - xh
+ - zu
+ - code: ZM
+ name: Zambia
+ currency: ZMW
+ locales:
+ - en
+ - code: ZW
+ name: Zimbabwe
+ currency: USD
+ locales:
+ - en
+ - sn
+ - nd
+ "/api/v3/admin/allowed_origins":
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.
-
- **Required scope:** `read_fulfillments` (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: deliveries } = await client.orders.fulfillments.deliveries.list(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- )
-
- // Each carries its own carrier status: pending, in_transit, delivered, ...
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries
- parameters:
- - name: x-spree-api-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:
- '200':
- description: deliveries found
- 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.
-
- **Required scope:** `write_fulfillments` (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 second box, or a freight consignment: the carrier is free text, so a
- // forwarder's PRO number is as valid as a parcel number.
- const delivery = await client.orders.fulfillments.deliveries.create(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- { tracking_number: 'PRO-4471923', carrier: 'Estes Freight' },
- )
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries
- -d '{"tracking_number":"PRO-4471923","carrier":"Estes Freight"}'
- parameters:
- - name: x-spree-api-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
- '422':
- description: tracking number already recorded on this parcel
- 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.
-
- **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
- 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
+ summary: List allowed origins
tags:
- - Deliveries
+ - Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
- Removes a hand-entered consignment. One a label minted is refused — refund the label instead.
+ Returns the CORS allowlist for the current store. Each entry is a
+ bare `scheme://host[:port]` permitted to call the admin API from a
+ browser. Backs the `Rack::Cors` allowlist and the CSRF boundary of
+ the admin cookie session (see
+ `docs/plans/5.5-admin-auth-cookie-refresh.md`).
- **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.
- **Required scope:** `write_fulfillments` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12261,17 +2171,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Staff confirming one consignment arrived. The fulfillment follows once
- // every one of its consignments has.
- const delivery = await client.orders.fulfillments.deliveries.markDelivered(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- 'dlv_UkLWZg9DAJ',
- )
+ const { data: origins } = await client.allowedOrigins.list()
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered
- -d '{ ... }'
+ source: spree api get /allowed_origins
parameters:
- name: x-spree-api-key
in: header
@@ -12284,115 +2187,93 @@ paths:
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
- 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":
- get:
- summary: List fulfillments
- tags:
- - Fulfillments
- security:
- - api_key: []
- bearer_auth: []
- description: |-
- Returns all shipments for an order.
-
- **Required scope:** `read_fulfillments` (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: fulfillments } = await client.orders.fulfillments.list('or_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/fulfillments
- 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
- description: Bearer token for admin authentication
+ 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 ID
+ type: integer
+ - name: q[origin_cont]
+ in: query
+ required: false
+ description: Filter by origin (contains)
schema:
type: string
- - name: expand
+ - name: sort
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).
+ 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 (e.g., number,status,tracking,cost).
- id is always included.
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
- description: fulfillments found
+ description: allowed origins found
+ content:
+ application/json:
+ example:
+ data:
+ - id: ao_UkLWZg9DAJ
+ origin: https://shop.example.com
+ 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/AllowedOrigin"
+ 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 fulfillment
+ summary: Create an allowed origin
tags:
- - Fulfillments
+ - Allowed Origins
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. 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).
+ Adds an origin to the admin CORS allowlist. The value must be a bare
+ `scheme://host[:port]` (no path, query, or fragment) and use `http` or
+ `https`.
- **Required scope:** `write_fulfillments` (for API-key authentication).
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12404,16 +2285,12 @@ paths:
secretKey: 'sk_xxx',
})
- const fulfillment = await client.orders.fulfillments.create('or_UkLWZg9DAJ', {
- stock_location_id: 'sloc_UkLWZg9DAJ',
- tracking: 'INPOST-12345',
- delivery_method_id: 'dm_UkLWZg9DAJ',
- status: 'shipped',
- items: [{ item_id: 'li_UkLWZg9DAJ', quantity: 1 }],
+ const origin = await client.allowedOrigins.create({
+ origin: 'https://admin.example.com',
})
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/fulfillments -d '{"stock_location_id":"sloc_UkLWZg9DAJ","tracking":"INPOST-12345","delivery_method_id":"dm_UkLWZg9DAJ","status":"shipped","items":[{"item_id":"li_UkLWZg9DAJ","quantity":1}]}'
+ source: spree api post /allowed_origins -d '{"origin":"https://admin.example.com"}'
parameters:
- name: x-spree-api-key
in: header
@@ -12426,84 +2303,61 @@ 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: fulfillment created
+ description: allowed origin created
+ content:
+ application/json:
+ example:
+ id: ao_gbHJdmfrXB
+ origin: https://admin.example.com
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/AllowedOrigin"
'422':
- description: order not completed
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Origin is invalid
+ details:
+ origin:
+ - is invalid
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
- required:
- - stock_location_id
properties:
- stock_location_id:
- type: string
- description: Stock location the fulfillment ships from
- tracking:
- type: string
- example: INPOST-12345
- 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
- example: '7.42'
- 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:
+ origin:
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
- example: 1
- metadata:
- type: object
- additionalProperties: true
- "/api/v3/admin/orders/{order_id}/fulfillments/{id}":
+ example: https://admin.example.com
+ required:
+ - origin
+ "/api/v3/admin/allowed_origins/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: Allowed origin ID
+ schema:
+ type: string
get:
- summary: Show a shipment
+ summary: Get an allowed origin
tags:
- - Fulfillments
+ - Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
- Returns details of a specific shipment.
+ Returns a single allowed origin by prefixed ID.
- **Required scope:** `read_fulfillments` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12515,10 +2369,10 @@ paths:
secretKey: 'sk_xxx',
})
- const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+ const origin = await client.allowedOrigins.get('ao_xxx')
- lang: bash
label: Spree CLI
- source: spree api get /orders/{order_id}/fulfillments/{id}
+ source: spree api get /allowed_origins/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -12531,47 +2385,45 @@ 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: 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.
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
- description: shipment found
+ description: allowed origin found
+ content:
+ application/json:
+ example:
+ id: ao_UkLWZg9DAJ
+ origin: https://shop.example.com
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/AllowedOrigin"
+ '404':
+ description: allowed origin not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Allowed origin not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a shipment
+ summary: Update an allowed origin
tags:
- - Fulfillments
+ - Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a fulfillment (tracking, delivery rate).
+ Updates an existing allowed origin.
- **Required scope:** `write_fulfillments` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12583,12 +2435,12 @@ paths:
secretKey: 'sk_xxx',
})
- const fulfillment = await client.orders.fulfillments.update('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {
- tracking: '1Z999AA10123456784',
+ const origin = await client.allowedOrigins.update('ao_xxx', {
+ origin: 'https://www.example.com',
})
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{id} -d '{"tracking":"1Z999AA10123456784"}'
+ source: spree api patch /allowed_origins/{id} -d '{"origin":"https://www.example.com"}'
parameters:
- name: x-spree-api-key
in: header
@@ -12601,47 +2453,55 @@ 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: Fulfillment ID
- schema:
- type: string
responses:
'200':
- description: shipment updated
+ description: allowed origin updated
+ content:
+ application/json:
+ example:
+ id: ao_UkLWZg9DAJ
+ origin: https://www.example.com
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/AllowedOrigin"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Origin must be an origin (scheme and host) without path,
+ query, or fragment
+ details:
+ origin:
+ - must be an origin (scheme and host) without path, query, or
+ fragment
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- tracking:
- type: string
- example: 1Z999AA10123456784
- description: Carrier tracking number, or a full https:// tracking
- link served back as tracking_url unchanged
- selected_delivery_rate_id:
+ origin:
type: string
- description: Delivery rate ID (dr_...) to select
- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":
- patch:
- summary: Fulfill a fulfillment
+ delete:
+ summary: Delete an allowed origin
tags:
- - Fulfillments
+ - Allowed Origins
security:
- api_key: []
bearer_auth: []
description: |-
- Marks a fulfillment as fulfilled.
+ Removes an origin from the admin CORS allowlist. After deletion the
+ admin SPA running at that origin will no longer be able to call the
+ admin API from a browser.
- **Required scope:** `write_fulfillments` (for API-key authentication).
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12653,11 +2513,10 @@ paths:
secretKey: 'sk_xxx',
})
- const fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+ await client.allowedOrigins.delete('ao_xxx')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{
- ... }'
+ source: spree api delete /allowed_origins/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -12670,34 +2529,21 @@ 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: Fulfillment ID
- schema:
- type: string
responses:
- '200':
- description: fulfillment fulfilled
- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":
- patch:
- summary: Buy the shipping label (deprecated)
+ '204':
+ description: allowed origin deleted
+ "/api/v3/admin/api_keys":
+ get:
+ summary: List API keys
tags:
- - Fulfillments
+ - API Keys
security:
- api_key: []
bearer_auth: []
description: |-
- Deprecated alias of POST /labels, answering with the fulfillment instead of the label. Removed in Spree 6.1.
+ 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.
- **Required scope:** `write_fulfillments` (for API-key authentication).
- deprecated: true
+ **Required scope:** `read_api_keys` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12709,19 +2555,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Deprecated: use client.orders.fulfillments.labels.create() instead, which
- // answers with the label itself. Removed in Spree 6.1.
- const fulfillment = await client.orders.fulfillments.purchaseLabel(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- )
-
- // The label is ready to print; the parcel is still unfulfilled.
- const label = fulfillment.labels[0]
+ const { data: keys } = await client.apiKeys.list()
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{id}/purchase_label
- -d '{ ... }'
+ source: spree api get /api_keys
parameters:
- name: x-spree-api-key
in: header
@@ -12731,38 +2568,74 @@ 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: Fulfillment ID
schema:
type: string
responses:
'200':
- description: label purchased
- '422':
- description: provider does not produce labels
- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":
- patch:
- summary: Mark a fulfillment delivered
+ description: API keys found
+ content:
+ application/json:
+ example:
+ data:
+ - id: key_UkLWZg9DAJ
+ name: Storefront key
+ key_type: publishable
+ token_prefix:
+ scopes: []
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ revoked_at:
+ last_used_at:
+ channel_id:
+ plaintext_token: pk_K6zNkaVogFy735ukK6E7Qs1F
+ created_by_email:
+ - id: key_gbHJdmfrXB
+ name: Backend integration
+ key_type: secret
+ token_prefix: sk_JiXS5S1gJ
+ scopes:
+ - write_all
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ revoked_at:
+ last_used_at:
+ channel_id:
+ plaintext_token:
+ created_by_email:
+ - id: key_EfhxLZ9ck8
+ name: velit
+ key_type: secret
+ token_prefix: sk_vihKVmP6r
+ scopes:
+ - write_all
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ revoked_at:
+ last_used_at:
+ channel_id:
+ plaintext_token:
+ created_by_email:
+ meta:
+ page: 1
+ limit: 25
+ count: 3
+ pages: 1
+ from: 1
+ to: 3
+ in: 3
+ previous:
+ next:
+ post:
+ summary: Create an API key
tags:
- - Fulfillments
+ - API Keys
security:
- api_key: []
bearer_auth: []
description: |-
- Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.
+ 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.
- **Required scope:** `write_fulfillments` (for API-key authentication).
+ **Required scope:** `write_api_keys` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12774,15 +2647,16 @@ paths:
secretKey: 'sk_xxx',
})
- const fulfillment = await client.orders.fulfillments.markDelivered(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- { delivered_at: '2026-08-11T09:30:00Z' },
- )
+ const key = await client.apiKeys.create({
+ name: 'Backend integration',
+ key_type: 'secret',
+ scopes: ['read_orders', 'write_orders'],
+ })
+
+ // `key.plaintext_token` is available only on this response.
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{id}/mark_delivered
- -d '{"delivered_at":"2026-08-11T09:30:00Z"}'
+ source: spree api post /api_keys -d '{"name":"Backend integration","key_type":"secret","scopes":["read_orders","write_orders"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -12792,107 +2666,73 @@ 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: Fulfillment ID
schema:
type: string
responses:
- '200':
- description: fulfillment delivered
+ '201':
+ description: secret key created — plaintext token returned once
+ content:
+ application/json:
+ example:
+ id: key_VqXmZF31wY
+ name: CI key
+ key_type: secret
+ token_prefix: sk_kCkDUvba1
+ scopes:
+ - read_orders
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ revoked_at:
+ last_used_at:
+ channel_id:
+ plaintext_token: sk_kCkDUvba1Z9gf8HAy29ih1Bj
+ created_by_email: [email protected]
'422':
- description: fulfillment has not shipped
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank and Scopes can't be blank
+ details:
+ name:
+ - can't be blank
+ scopes:
+ - can't be blank
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - name
+ - key_type
properties:
- delivered_at:
+ name:
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.
-
- **Required scope:** `write_fulfillments` (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 fulfillment = await client.orders.fulfillments.cancel('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{id}/cancel -d '{
- ... }'
- parameters:
- - name: x-spree-api-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
- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
- patch:
- summary: Split a fulfillment
+ example: Backend integration
+ key_type:
+ type: string
+ enum:
+ - publishable
+ - secret
+ scopes:
+ type: array
+ items:
+ type: string
+ example:
+ - read_orders
+ - write_orders
+ "/api/v3/admin/api_keys/{id}":
+ get:
+ summary: Show an API key
tags:
- - Fulfillments
+ - API Keys
security:
- api_key: []
bearer_auth: []
- description: |-
- Transfers items from this shipment to a new shipment at a different stock location.
-
- **Required scope:** `write_fulfillments` (for API-key authentication).
+ description: "**Required scope:** `read_api_keys` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12904,21 +2744,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Splitting moves a quantity of one variant into its own fulfillment, so the
- // response is the order's full set: the source is re-shaped, and disappears
- // when the split drains it. Pass stock_location_id to send the new
- // fulfillment out from a different origin.
- const { data: fulfillments } = await client.orders.fulfillments.split(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- {
- variant_id: 'variant_86Rf07xd4z',
- quantity: 1,
- },
- )
+ const key = await client.apiKeys.get('key_xxx')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{id}/split -d '{"variant_id":"variant_86Rf07xd4z","quantity":1}'
+ source: spree api get /api_keys/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -12928,54 +2757,42 @@ 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: Fulfillment ID
schema:
type: string
responses:
'200':
- description: fulfillment split
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - variant_id
- - quantity
- properties:
- variant_id:
- type: string
- description: Variant ID
- quantity:
- type: integer
- example: 1
- stock_location_id:
- type: string
- description: Target stock location ID
- "/api/v3/admin/orders/{order_id}/gift_cards":
- post:
- summary: Apply a gift card to an order
+ description: API key found
+ content:
+ application/json:
+ example:
+ id: key_UkLWZg9DAJ
+ name: Storefront key
+ key_type: publishable
+ token_prefix:
+ scopes: []
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ revoked_at:
+ last_used_at:
+ channel_id:
+ plaintext_token: pk_XyZ9qSxtdtD6Uewb3GXYKkoV
+ created_by_email:
+ patch:
+ summary: Update an API key
tags:
- - Orders
+ - API Keys
security:
- api_key: []
bearer_auth: []
description: |-
- Applies a gift card by code to the order. Returns the gift card.
+ 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.
- **Required scope:** `write_gift_cards` (for API-key authentication).
+ **Required scope:** `write_api_keys` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -12987,12 +2804,11 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.giftCards.apply('or_UkLWZg9DAJ', {
- code: 'GIFT-XXXX-YYYY',
- })
+ // Only `name` is editable — scopes and key_type are fixed at creation.
+ const key = await client.apiKeys.update('key_xxx', { name: 'CI key (renamed)' })
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'
+ source: spree api patch /api_keys/{id} -d '{"name":"CI key (renamed)"}'
parameters:
- name: x-spree-api-key
in: header
@@ -13002,42 +2818,49 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
+ - name: id
in: path
required: true
- description: Order ID
schema:
type: string
responses:
- '201':
- description: gift card applied
+ '200':
+ description: API key renamed
+ content:
+ application/json:
+ example:
+ id: key_gbHJdmfrXB
+ name: Backend integration (renamed)
+ key_type: secret
+ token_prefix: sk_ZPBGFa2TH
+ scopes:
+ - write_all
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ revoked_at:
+ last_used_at:
+ channel_id:
+ plaintext_token:
+ created_by_email:
requestBody:
content:
application/json:
schema:
type: object
- required:
- - code
properties:
- code:
+ name:
type: string
- description: Gift card code
- example: GIFT-XXXX-YYYY
- "/api/v3/admin/orders/{order_id}/gift_cards/{id}":
+ example: Backend integration (renamed)
delete:
- summary: Remove a gift card from an order
+ summary: Delete an API key
tags:
- - Orders
+ - API Keys
security:
- api_key: []
bearer_auth: []
- description: |-
- Removes the gift card from the order.
-
- **Required scope:** `write_gift_cards` (for API-key authentication).
+ description: "**Required scope:** `write_api_keys` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -13049,10 +2872,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')
+ await client.apiKeys.delete('key_xxx')
- lang: bash
label: Spree CLI
- source: spree api delete /orders/{order_id}/gift_cards/{id}
+ source: spree api delete /api_keys/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -13062,36 +2885,27 @@ 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: Gift card ID
schema:
type: string
responses:
'204':
- description: gift card removed
- "/api/v3/admin/orders/{order_id}/items":
+ description: API key deleted
+ "/api/v3/admin/api_keys/current":
get:
- summary: List order items
+ summary: Describe the current API key
tags:
- - Orders
+ - API Keys
security:
- api_key: []
- bearer_auth: []
description: |-
- Returns all line items for an order.
+ 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.
- **Required scope:** `read_orders` (for API-key authentication).
+ **Required scope:** none — any key can describe itself (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -13103,120 +2917,48 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')
+ // Describes the key you authenticated with, including its live scopes.
+ const key = await client.apiKeys.current()
- lang: bash
label: Spree CLI
- source: spree api get /orders/{order_id}/items
+ source: spree api get /api_keys/current
parameters:
- name: x-spree-api-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
responses:
'200':
- description: items found
+ description: current API key
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 69180
- slug: product-69180
- options_text: 'Size: S'
- price: '10.0'
- display_price: "$10.00"
- total: '20.0'
- display_total: "$20.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '20.0'
- display_pre_tax_amount: "$20.00"
- discounted_amount: '20.0'
- display_discounted_amount: "$20.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values:
- - id: optval_UkLWZg9DAJ
- option_type_id: opt_UkLWZg9DAJ
- name: size-2
- label: S
- position: 1
- color_code:
- option_type_name: foo-size-11
- 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'
- cost_price: '17.0'
- 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
+ id: key_EfhxLZ9ck8
+ name: fugiat
+ key_type: secret
+ token_prefix: sk_L5LVfygvH
+ scopes:
+ - write_all
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ revoked_at:
+ last_used_at:
+ channel_id:
+ plaintext_token:
+ created_by_email:
+ "/api/v3/admin/api_keys/{id}/revoke":
+ patch:
+ summary: Revoke an API key
tags:
- - Orders
+ - API Keys
security:
- api_key: []
bearer_auth: []
description: |-
- Adds a new line item to the order.
+ Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `write_api_keys` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -13228,13 +2970,10 @@ paths:
secretKey: 'sk_xxx',
})
- const item = await client.orders.items.create('or_UkLWZg9DAJ', {
- variant_id: 'variant_k5nR8xLq',
- quantity: 2,
- })
+ const key = await client.apiKeys.revoke('key_xxx')
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'
+ source: spree api patch /api_keys/{id}/revoke -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -13244,112 +2983,44 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
+ - name: id
in: path
required: true
- description: Order ID
schema:
type: string
responses:
- '201':
- description: item added
+ '200':
+ description: API key revoked
content:
application/json:
example:
- id: li_gbHJdmfrXB
- variant_id: variant_VqXmZF31wY
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 3
- currency: USD
- name: Product 899
- slug: product-899
- options_text: 'Size: S'
- price: '19.99'
- display_price: "$19.99"
- total: '59.97'
- display_total: "$59.97"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '59.97'
- display_pre_tax_amount: "$59.97"
- discounted_amount: '59.97'
- display_discounted_amount: "$59.97"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values:
- - id: optval_gbHJdmfrXB
- option_type_id: opt_gbHJdmfrXB
- name: size-4
- label: S
- position: 1
- color_code:
- option_type_name: foo-size-13
- 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:
+ id: key_gbHJdmfrXB
+ name: Backend integration
+ key_type: secret
+ token_prefix: sk_11yGX4rad
+ scopes:
+ - write_all
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- catalog_price: '19.99'
- cost_price: '17.0'
- 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}":
+ revoked_at: '2026-01-15T12:00:00.000Z'
+ last_used_at:
+ channel_id:
+ plaintext_token:
+ created_by_email:
+ "/api/v3/admin/categories":
get:
- summary: Show an item
+ summary: List categories
tags:
- - Orders
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Returns details of a specific line item.
-
- **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',
- })
+ Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).
- const item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/items/{id}
+ **Required scope:** `read_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13362,116 +3033,90 @@ 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: Item ID
+ - name: page
+ in: query
+ required: false
+ description: Page number
schema:
- type: string
- - name: expand
+ type: integer
+ - name: limit
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: Number of records per page
schema:
- type: string
- - name: fields
+ type: integer
+ - name: expand
in: query
required: false
- description: Comma-separated list of fields to include (e.g., quantity,price,total).
- id is always included.
+ description: Comma-separated associations to expand (e.g., children, parent,
+ ancestors).
schema:
type: string
responses:
'200':
- description: item found
+ description: categories 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 92714
- slug: product-92714
- options_text: 'Size: S'
- price: '10.0'
- display_price: "$10.00"
- total: '20.0'
- display_total: "$20.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '20.0'
- display_pre_tax_amount: "$20.00"
- discounted_amount: '20.0'
- display_discounted_amount: "$20.00"
- display_compare_at_amount: "$0.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-14
- option_type_label: Size
+ data:
+ - id: ctg_UkLWZg9DAJ
+ name: Clothing
+ permalink: clothing
+ position: 0
+ depth: 0
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ parent_id:
+ description: ''
+ description_html: ''
image_url:
+ square_image_url:
+ is_root: true
+ is_child: false
+ is_leaf: true
+ external_references: {}
metadata: {}
+ pretty_name: Clothing
+ lft: 1
+ rgt: 2
+ products_count: 0
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'
- cost_price: '17.0'
- tax_category_id: taxcat_UkLWZg9DAJ
- patch:
- summary: Update an item
+ 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/Category"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ post:
+ summary: Create a category
tags:
- - Orders
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Updates an order item quantity or metadata.
-
- **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',
- })
+ Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.
- const item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {
- quantity: 5,
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /orders/{order_id}/items/{id} -d '{"quantity":5}'
+ **Required scope:** `write_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13484,112 +3129,89 @@ 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: Item ID
- schema:
- type: string
responses:
- '200':
- description: item updated
+ '201':
+ description: category created
+ content:
+ application/json:
+ example:
+ id: ctg_gbHJdmfrXB
+ name: Shirts
+ permalink: clothing/shirts
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: true
+ external_references: {}
+ metadata: {}
+ pretty_name: Clothing -> Shirts
+ lft: 2
+ rgt: 3
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Category"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
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.
-
- **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',
- })
-
- await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /orders/{order_id}/items/{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: Item ID
- schema:
- type: string
- responses:
- '204':
- description: line item removed
- "/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":
+ name:
+ type: string
+ example: Shirts
+ parent_id:
+ type: string
+ example: ctg_abc123
+ 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: List shipping labels
+ summary: Get a category
tags:
- - Shipping Labels
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Every label bought or uploaded for a parcel, refunded ones included.
-
- **Required scope:** `read_fulfillments` (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 a single category by ID.
- const { data: labels } = await client.orders.fulfillments.labels.list(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- )
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/fulfillments/{fulfillment_id}/labels
+ **Required scope:** `read_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13602,52 +3224,73 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
+ - name: id
in: path
required: true
- description: Order ID
+ description: Category ID
schema:
type: string
- - name: fulfillment_id
- in: path
- required: true
- description: Fulfillment ID
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (e.g., children, parent,
+ ancestors).
schema:
type: string
responses:
'200':
- description: labels found
- post:
- summary: Buy or record a shipping label
+ description: category found
+ content:
+ application/json:
+ example:
+ id: ctg_UkLWZg9DAJ
+ name: Clothing
+ permalink: clothing
+ position: 0
+ depth: 0
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ parent_id:
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: true
+ is_child: false
+ is_leaf: true
+ external_references: {}
+ metadata: {}
+ pretty_name: Clothing
+ lft: 1
+ rgt: 2
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Category"
+ '404':
+ description: category not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Category not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a category
tags:
- - Shipping Labels
+ - Categories
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.
-
- **Required scope:** `write_fulfillments` (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',
- })
-
- // With no body, the parcel's carrier account buys the label.
- const label = await client.orders.fulfillments.labels.create('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+ Updates a category.
- // The tracking number is now on the parcel's first delivery, and the label is
- // ready to print. What the merchant paid the carrier is label.display_cost.
- - lang: bash
- label: Spree CLI
- source: spree api post /orders/{order_id}/fulfillments/{fulfillment_id}/labels
- -d '{ ... }'
+ **Required scope:** `write_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13660,70 +3303,78 @@ paths:
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
+ - name: id
in: path
required: true
- description: Fulfillment ID
+ description: Category ID
schema:
type: string
responses:
- '201':
- description: label purchased
- '422':
- description: provider does not produce labels
+ '200':
+ description: category updated
+ content:
+ application/json:
+ example:
+ id: ctg_UkLWZg9DAJ
+ name: Apparel
+ permalink: clothing
+ position: 0
+ depth: 0
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ parent_id:
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: true
+ is_child: false
+ is_leaf: true
+ external_references: {}
+ metadata: {}
+ pretty_name: Apparel
+ lft: 1
+ rgt: 2
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Category"
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:
+ name:
type: string
- description: Number printed on an uploaded label
- carrier:
+ example: Apparel
+ parent_id:
type: string
- description: Free-text carrier; detected from the number when omitted
- service:
+ description: Prefixed ID of the parent category
+ description:
type: string
- description: Carrier service the label was bought at
- cost:
+ permalink:
type: string
- description: What the merchant paid the carrier
- currency:
+ meta_title:
type: string
- description: Currency of the cost
- file_format:
+ meta_description:
type: string
- enum:
- - pdf
- - png
- - zpl
- description: Label file format; taken from the file when omitted
- tracking_url:
+ meta_keywords:
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
+ delete:
+ summary: Delete a category
tags:
- - Shipping Labels
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- One label, with what it cost and where to print it from.
+ Deletes a category and its descendants.
- **Required scope:** `read_fulfillments` (for API-key authentication).
+ **Required scope:** `write_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13736,38 +3387,27 @@ paths:
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
+ description: Category ID
schema:
type: string
responses:
- '200':
- description: label found
- delete:
- summary: Delete an uploaded label
+ '204':
+ description: category deleted
+ "/api/v3/admin/categories/{id}/reposition":
+ patch:
+ summary: Reposition a category
tags:
- - Shipping Labels
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.
+ Moves a category to a new parent and/or index within the tree.
- **Required scope:** `write_fulfillments` (for API-key authentication).
+ **Required scope:** `write_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13780,63 +3420,71 @@ paths:
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
+ description: Category 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
+ '200':
+ description: category repositioned
+ content:
+ application/json:
+ example:
+ id: ctg_gbHJdmfrXB
+ name: Footwear
+ permalink: clothing/footwear
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: true
+ external_references: {}
+ metadata: {}
+ pretty_name: Clothing -> Footwear
+ lft: 2
+ rgt: 3
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ 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:
- - Shipping Labels
+ - Categories
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.
-
- **Required scope:** `write_fulfillments` (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 label = await client.orders.fulfillments.labels.refund(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
- 'lbl_UkLWZg9DAJ',
- )
+ Products classified under the category, ordered by their classification position.
- // 'refunded' when the carrier settled at once, 'refund_requested' when it
- // will answer later.
- const outcome = label.status
- - lang: bash
- label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund
- -d '{ ... }'
+ **Required scope:** `read_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13849,56 +3497,52 @@ paths:
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
+ - name: category_id
in: path
required: true
- description: Shipping label ID
+ description: Category ID
schema:
type: string
responses:
'200':
- description: refund filed
- '422':
- description: uploaded labels cannot be refunded
- "/api/v3/admin/orders/{order_id}/payments":
- get:
- summary: List payments
+ description: products found
+ content:
+ application/json:
+ example:
+ data: []
+ meta:
+ page: 1
+ limit: 25
+ count: 0
+ pages: 1
+ from: 0
+ to: 0
+ in: 0
+ 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 category
tags:
- - Payments
+ - Categories
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',
- })
+ Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.
- const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/payments
+ **Required scope:** `write_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13911,59 +3555,44 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
+ - name: category_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.
+ description: Category ID
schema:
type: string
responses:
- '200':
- description: payments found
- post:
- summary: Create a payment
+ '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 category
tags:
- - Payments
+ - Categories
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
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.
- 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 /orders/{order_id}/payments -d '{"payment_method_id":"pm_UkLWZg9DAJ","amount":"99.99","source_id":"cc_UkLWZg9DAJ"}'
+ **Required scope:** `write_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -13976,59 +3605,45 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
+ - name: category_id
in: path
required: true
- description: Order ID
+ description: Category ID
schema:
type: string
responses:
- '201':
- description: payment created
+ '200':
+ description: products removed
+ content:
+ application/json:
+ example:
+ removed_count: 1
requestBody:
content:
application/json:
schema:
type: object
- required:
- - payment_method_id
properties:
- payment_method_id:
- type: string
- 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 payment
+ product_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - prod_abc123
+ required:
+ - product_ids
+ "/api/v3/admin/categories/{category_id}/products/{id}/reposition":
+ patch:
+ summary: Reposition a category product
tags:
- - Payments
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Returns details of a specific payment.
-
- **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',
- })
+ Moves a product to a new index among the category's products.
- const payment = await client.orders.payments.get('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /orders/{order_id}/payments/{id}
+ **Required scope:** `write_categories` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -14041,47 +3656,44 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
+ - name: category_id
in: path
required: true
- description: Order ID
+ description: Category 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.
+ required: true
+ description: Product ID
schema:
type: string
responses:
- '200':
- description: payment found
- "/api/v3/admin/orders/{order_id}/payments/{id}/capture":
- patch:
- summary: Capture a payment
+ '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:
- - Payments
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Captures a pending payment.
+ Returns the channels configured for the current store.
- **Required scope:** `write_payments` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14093,11 +3705,10 @@ paths:
secretKey: 'sk_xxx',
})
- const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
+ const { data: channels } = await client.channels.list()
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/payments/{id}/capture -d '{ ...
- }'
+ source: spree api get /channels
parameters:
- name: x-spree-api-key
in: header
@@ -14107,42 +3718,89 @@ 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: page
+ in: query
+ required: false
schema:
- type: string
- - name: id
- in: path
- required: true
- description: Payment ID
+ type: integer
+ - name: limit
+ in: query
+ required: false
schema:
- type: string
+ type: integer
responses:
'200':
- description: payment captured
- '422':
- description: capture failed
+ description: channels found
content:
application/json:
+ example:
+ data:
+ - id: ch_UkLWZg9DAJ
+ name: Online Store
+ code: online
+ active: true
+ default: true
+ storefront_access: public
+ guest_checkout: true
+ preferred_order_routing_strategy:
+ preferred_storefront_access:
+ preferred_guest_checkout:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ stock_location_ids: []
+ default_catalog_id:
+ - id: ch_gbHJdmfrXB
+ name: Wholesale
+ code: wholesale
+ active: true
+ default: false
+ storefront_access: public
+ guest_checkout: true
+ preferred_order_routing_strategy:
+ preferred_storefront_access:
+ preferred_guest_checkout:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ stock_location_ids: []
+ default_catalog_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/orders/{order_id}/payments/{id}/void":
- patch:
- summary: Void a payment
+ 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:
- - Payments
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Voids a payment.
+ Creates a new channel on the current store. `code` is normalized to a
+ URL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's
+ derived from `name`.
- **Required scope:** `write_payments` (for API-key authentication).
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14154,10 +3812,16 @@ paths:
secretKey: 'sk_xxx',
})
- const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
+ // `code` is optional — when omitted it's derived from `name`
+ // ("Point of Sale" → "point-of-sale").
+ const channel = await client.channels.create({
+ name: 'Point of Sale',
+ code: 'pos',
+ active: true,
+ })
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/payments/{id}/void -d '{ ... }'
+ source: spree api post /channels -d '{"name":"Point of Sale","code":"pos","active":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -14167,36 +3831,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: Payment ID
schema:
type: string
responses:
- '200':
- description: payment voided
- "/api/v3/admin/orders/{order_id}/refunds":
+ '201':
+ description: channel created
+ content:
+ application/json:
+ example:
+ id: ch_EfhxLZ9ck8
+ name: Marketplace
+ code: marketplace
+ active: true
+ default: false
+ storefront_access: public
+ guest_checkout: true
+ preferred_order_routing_strategy:
+ preferred_storefront_access:
+ preferred_guest_checkout:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ stock_location_ids: []
+ default_catalog_id:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ example: Point of Sale
+ code:
+ type: string
+ example: pos
+ description: Slug — auto-derived from `name` when blank.
+ active:
+ type: boolean
+ default: true
+ default:
+ type: boolean
+ default: false
+ preferred_order_routing_strategy:
+ type: string
+ nullable: true
+ description: Routing strategy class name. `null` inherits the store
+ setting.
+ preferred_storefront_access:
+ type: string
+ nullable: true
+ enum:
+ - public
+ - prices_hidden
+ - login_required
+ description: Anonymous-visitor access posture. `null` inherits the
+ store setting.
+ preferred_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: List refunds
+ summary: Get a channel
tags:
- - Refunds
+ - Channels
security:
- api_key: []
bearer_auth: []
- description: |-
- Returns all refunds for an order.
-
- **Required scope:** `read_refunds` (for API-key authentication).
+ description: "**Required scope:** `read_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14208,10 +3919,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: refunds } = await client.orders.refunds.list('or_UkLWZg9DAJ')
+ const channel = await client.channels.get('channel_xxx')
- lang: bash
label: Spree CLI
- source: spree api get /orders/{order_id}/refunds
+ source: spree api get /channels/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -14221,43 +3932,36 @@ 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: 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
responses:
'200':
- description: refunds found
- post:
- summary: Create a refund
+ description: channel found
+ content:
+ application/json:
+ example:
+ id: ch_gbHJdmfrXB
+ name: Wholesale
+ code: wholesale
+ active: true
+ default: false
+ storefront_access: public
+ guest_checkout: true
+ preferred_order_routing_strategy:
+ preferred_storefront_access:
+ preferred_guest_checkout:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ stock_location_ids: []
+ default_catalog_id:
+ patch:
+ summary: Update a channel
tags:
- - Refunds
+ - Channels
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).
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14269,14 +3973,13 @@ paths:
secretKey: 'sk_xxx',
})
- const refund = await client.orders.refunds.create('or_UkLWZg9DAJ', {
- payment_id: 'pay_UkLWZg9DAJ',
- amount: '5.00',
- refund_reason_id: 'refrsn_UkLWZg9DAJ',
+ const channel = await client.channels.update('channel_xxx', {
+ name: 'Wholesale (Updated)',
+ 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":"refrsn_UkLWZg9DAJ"}'
+ source: spree api patch /channels/{id} -d '{"name":"Wholesale (Updated)","active":false}'
parameters:
- name: x-spree-api-key
in: header
@@ -14286,48 +3989,69 @@ 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
responses:
- '201':
- description: refund created
+ '200':
+ description: channel updated
+ content:
+ application/json:
+ example:
+ id: ch_gbHJdmfrXB
+ name: Wholesale (Updated)
+ code: wholesale
+ active: true
+ default: false
+ storefront_access: login_required
+ guest_checkout: false
+ preferred_order_routing_strategy:
+ preferred_storefront_access: login_required
+ preferred_guest_checkout: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ stock_location_ids: []
+ default_catalog_id:
requestBody:
content:
application/json:
schema:
type: object
- required:
- - payment_id
- - amount
properties:
- payment_id:
+ name:
type: string
- description: Payment ID
- amount:
+ code:
type: string
- example: '10.00'
- refund_reason_id:
+ active:
+ type: boolean
+ default:
+ type: boolean
+ preferred_order_routing_strategy:
type: string
- description: Refund reason ID
- "/api/v3/admin/orders/{order_id}/store_credits":
- post:
- summary: Apply customer's store credit to an order
+ nullable: true
+ description: Routing strategy class name. `null` inherits the store
+ setting.
+ preferred_storefront_access:
+ type: string
+ nullable: true
+ enum:
+ - public
+ - prices_hidden
+ - login_required
+ description: Anonymous-visitor access posture. `null` inherits the
+ store setting.
+ preferred_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:
- - Orders
+ - Channels
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).
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14339,12 +4063,10 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {
- amount: '25.00',
- })
+ await client.channels.delete('channel_xxx')
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'
+ source: spree api delete /channels/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -14354,128 +4076,32 @@ 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
responses:
- '201':
- description: store credit applied
- content:
- application/json:
- example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '60.0'
- display_amount_due: "$60.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '50.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
- 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
+ '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:
- - Orders
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Removes any applied store credit from the order.
+ Publishes the listed products on this channel. Idempotent — re-publishing
+ an already-published product updates its publication window. Products from
+ sibling stores are silently dropped.
- **Required scope:** `write_store_credits` (for API-key authentication).
+
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14487,10 +4113,16 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.storeCredits.remove('or_UkLWZg9DAJ')
+ // Idempotent — re-publishing an already-published product updates its
+ // publication window. `published_at`/`unpublished_at` are optional:
+ // `null` (or omitted) means live immediately and never come down.
+ const { product_count } = await client.channels.addProducts('channel_xxx', {
+ product_ids: ['prod_xxx', 'prod_yyy'],
+ published_at: '2026-07-01T00:00:00Z',
+ })
- lang: bash
label: Spree CLI
- source: spree api delete /orders/{order_id}/store_credits
+ source: spree api post /channels/{id}/add_products -d '{"product_ids":["prod_xxx","prod_yyy"],"published_at":"2026-07-01T00:00:00Z"}'
parameters:
- name: x-spree-api-key
in: header
@@ -14500,30 +4132,60 @@ 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
responses:
- '204':
- description: store credit removed
- "/api/v3/admin/orders":
- get:
- summary: List orders
+ '200':
+ description: products published
+ content:
+ application/json:
+ example:
+ product_count: 1
+ 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:
- - Orders
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a paginated list of orders for the current store.
+ Unpublishes the listed products from this channel.
- **Required scope:** `read_orders` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14535,15 +4197,12 @@ paths:
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,
+ const { product_count } = await client.channels.removeProducts('channel_xxx', {
+ product_ids: ['prod_xxx', 'prod_yyy'],
})
- 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}'
+ source: spree api post /channels/{id}/remove_products -d '{"product_ids":["prod_xxx","prod_yyy"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -14553,187 +4212,50 @@ 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: sort
- in: query
- required: false
- description: Sort field (e.g., created_at, -created_at, completed_at)
- schema:
- type: string
- - name: q[state_eq]
- in: query
- required: false
- description: Filter by state (cart, address, delivery, payment, confirm, complete,
- canceled)
- schema:
- type: string
- - name: q[email_cont]
- in: query
- required: false
- description: Filter by email (contains)
- schema:
- type: string
- - name: q[number_eq]
- in: query
- required: false
- description: Filter by order number
- schema:
- type: string
- - name: q[completed_at_gt]
- in: query
- required: false
- description: Filter by completed after date
- 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: orders found
- content:
- application/json:
- example:
- data:
- - id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total:
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- '401':
- description: unauthorized
+ description: products unpublished
content:
application/json:
example:
- error:
- code: authentication_required
- message: Authentication required
+ product_count: 1
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a draft order
+ 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:
- - Orders
+ - 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.
+
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -14745,93 +4267,10 @@ 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',
- })
+ const { data: rules } = await client.channels.orderRoutingRules.list('ch_UkLWZg9DAJ')
- 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 get /channels/{channel_id}/order_routing_rules
parameters:
- name: x-spree-api-key
in: header
@@ -14841,221 +4280,71 @@ paths:
- 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
+ '200':
+ description: rules found
content:
application/json:
example:
- id: or_gbHJdmfrXB
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id: sloc_UkLWZg9DAJ
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id: adm_UkLWZg9DAJ
- customer_id:
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- customer_id:
- type: string
- description: 'Customer ID. Alias: user_id (legacy).'
- 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:
- type: string
- description: Optional. Applied non-fatally; invalid codes do not
- block creation.
- "/api/v3/admin/orders/{id}":
- get:
- summary: Show an order
+ data:
+ - id: orule_UkLWZg9DAJ
+ position: 1
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: preferred_location
+ channel_id: ch_UkLWZg9DAJ
+ preferences: {}
+ preference_schema: []
+ label: Preferred location
+ description: Fulfill from the location pinned on the order, when
+ one is set
+ - id: orule_gbHJdmfrXB
+ position: 2
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: minimize_splits
+ channel_id: ch_UkLWZg9DAJ
+ preferences: {}
+ preference_schema: []
+ label: Minimize splits
+ description: Prefer the location that can fulfill the most items
+ on its own, avoiding split shipments
+ - id: orule_EfhxLZ9ck8
+ position: 3
+ active: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: default_location
+ channel_id: ch_UkLWZg9DAJ
+ preferences: {}
+ preference_schema: []
+ label: Default location
+ description: Prefer the stock location marked as default
+ meta:
+ page: 1
+ limit: 25
+ count: 3
+ pages: 1
+ from: 1
+ to: 3
+ in: 3
+ previous:
+ next:
+ post:
+ summary: Create an order routing rule on a channel
tags:
- - Orders
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Returns full order details including admin-only fields.
+ 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.
- **Required scope:** `read_orders` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15067,12 +4356,12 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.get('or_UkLWZg9DAJ', {
- expand: ['items', 'fulfillments', 'payments', 'customer'],
+ const rule = await client.channels.orderRoutingRules.create('ch_UkLWZg9DAJ', {
+ type: 'preferred_location',
})
- lang: bash
label: Spree CLI
- source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'
+ source: spree api post /channels/{channel_id}/order_routing_rules -d '{"type":"preferred_location"}'
parameters:
- name: x-spree-api-key
in: header
@@ -15082,143 +4371,74 @@ 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 (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
+ '201':
+ description: rule created
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total:
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
+ id: orule_VqXmZF31wY
+ position: 3
+ active: true
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
- '404':
- description: order not found
+ type: default_location
+ channel_id: ch_UkLWZg9DAJ
+ preferences: {}
+ preference_schema: []
+ label: Default location
+ description: Prefer the stock location marked as default
+ '422':
+ description: unknown rule type
content:
application/json:
example:
error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ code: unknown_order_routing_rule_type
+ message: Unknown type
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ type:
+ type: string
+ example: preferred_location
+ 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
+ summary: Update an order routing rule
tags:
- - Orders
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Updates an order. Supports updating email, addresses, special instructions, and line items.
+ 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.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15230,14 +4450,14 @@ 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 rule = await client.channels.orderRoutingRules.update('ch_UkLWZg9DAJ', 'orule_k5nR8xLq', {
+ active: false,
+ position: 2,
})
- 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 patch /channels/{channel_id}/order_routing_rules/{id} -d
+ '{"active":false,"position":2}'
parameters:
- name: x-spree-api-key
in: header
@@ -15247,191 +4467,238 @@ 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: order updated
+ description: rule updated
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: draft
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
+ id: orule_UkLWZg9DAJ
+ position: 2
+ active: false
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
+ type: preferred_location
+ channel_id: ch_UkLWZg9DAJ
+ preferences: {}
+ preference_schema: []
+ label: Preferred location
+ description: Fulfill from the location pinned on the order, when one
+ is set
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:
+ active:
+ type: boolean
+ position:
+ type: integer
+ preferences:
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
+ additionalProperties: true
delete:
- summary: Delete a draft order
+ summary: Delete an order routing rule
+ tags:
+ - Channels
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**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.channels.orderRoutingRules.delete('ch_UkLWZg9DAJ', 'orule_k5nR8xLq')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /channels/{channel_id}/order_routing_rules/{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: 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`.
+
+ **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: ruleTypes } = await client.orderRoutingRules.types()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /order_routing_rules/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: types found
+ content:
+ application/json:
+ example:
+ data:
+ - type: default_location
+ label: Default location
+ description: Prefer the stock location marked as default
+ preference_schema: []
+ - type: minimize_splits
+ label: Minimize splits
+ description: Prefer the location that can fulfill the most items
+ on its own, avoiding split shipments
+ preference_schema: []
+ - type: preferred_location
+ label: Preferred location
+ description: Fulfill from the location pinned on the order, when
+ one is set
+ preference_schema: []
+ "/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]=Spree::Product` to narrow to one parent type.
+
+ **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: definitions } = await client.customFieldDefinitions.list({
+ q: { resource_type_eq: 'Spree::Product' },
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /custom_field_definitions -d '{"q":{"resource_type_eq":"Spree::Product"}}'
+ 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. 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: definitions returned
+ content:
+ application/json:
+ example:
+ data:
+ - id: cfdef_UkLWZg9DAJ
+ namespace: specs
+ key: fabric
+ label: Title
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: true
+ searchable: false
+ sortable: false
+ filter_key: cf_specs_fabric
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: cfdef_gbHJdmfrXB
+ namespace: custom
+ key: order_notes
+ label: Order Notes
+ field_type: short_text
+ resource_type: Spree::Order
+ storefront_visible: true
+ searchable: false
+ sortable: false
+ filter_key: cf_custom_order_notes
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
+ post:
+ summary: Create a custom field definition
tags:
- - Orders
+ - Custom Fields
security:
- api_key: []
bearer_auth: []
- description: |-
- Deletes a draft order. Completed orders cannot be deleted.
-
- **Required scope:** `write_orders` (for API-key authentication).
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15443,10 +4710,18 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.delete('or_UkLWZg9DAJ')
+ const definition = await client.customFieldDefinitions.create({
+ namespace: 'specs',
+ key: 'origin',
+ label: 'Country of Origin',
+ field_type: 'short_text',
+ resource_type: 'Spree::Product',
+ storefront_visible: true,
+ })
- lang: bash
label: Spree CLI
- source: spree api delete /orders/{id}
+ source: spree api post /custom_field_definitions -d '{"namespace":"specs","key":"origin","label":"Country
+ of Origin","field_type":"short_text","resource_type":"Spree::Product","storefront_visible":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -15456,33 +4731,72 @@ 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:
- '204':
- description: order deleted
- "/api/v3/admin/orders/{id}/complete":
- patch:
- summary: Complete an order
+ '201':
+ description: definition created
+ content:
+ application/json:
+ example:
+ id: cfdef_EfhxLZ9ck8
+ namespace: specs
+ key: origin
+ label: Country of Origin
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: true
+ searchable: false
+ sortable: false
+ filter_key: cf_specs_origin
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ 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 identifier (one of the registered
+ field-type class names).
+ resource_type:
+ type: string
+ description: Owner class, e.g. `Spree::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:
- - Orders
+ - Custom Fields
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.
-
-
- **Required scope:** `write_orders` (for API-key authentication).
+ description: "**Required scope:** `read_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15494,12 +4808,10 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.complete('or_UkLWZg9DAJ', {
- notify_customer: true,
- })
+ const definition = await client.customFieldDefinitions.get('cfd_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{id}/complete -d '{"notify_customer":true}'
+ source: spree api get /custom_field_definitions/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -15509,157 +4821,53 @@ 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
+ - 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: order completed
+ description: definition found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: placed
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '110.0'
- display_payment_total: "$110.00"
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
+ id: cfdef_UkLWZg9DAJ
+ namespace: specs
+ key: fabric
+ label: Title
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: true
+ searchable: false
+ sortable: false
+ filter_key: cf_specs_fabric
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
- '422':
- description: order cannot be completed
- content:
- application/json:
- example:
- error:
- code: order_cannot_complete
- message: No payment found
- details:
- base:
- - No payment found
- 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
+ summary: Update a custom field definition
tags:
- - Orders
+ - Custom Fields
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.
-
-
- **Required scope:** `write_orders` (for API-key authentication).
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15671,18 +4879,14 @@ 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',
+ const definition = await client.customFieldDefinitions.update('cfd_UkLWZg9DAJ', {
+ label: 'Country of Origin',
+ storefront_visible: false,
})
- 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 patch /custom_field_definitions/{id} -d '{"label":"Country
+ of Origin","storefront_visible":false}'
parameters:
- name: x-spree-api-key
in: header
@@ -15692,145 +4896,56 @@ 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: order canceled
+ description: definition updated
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: "-0.0"
- display_amount_due: "$0.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: canceled
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- metadata: {}
- cancel_note:
- canceled_at: '2026-01-15T12:00:00.000Z'
- approved_at:
+ id: cfdef_UkLWZg9DAJ
+ namespace: specs
+ key: fabric
+ label: Fabric Composition
+ field_type: short_text
+ resource_type: Spree::Product
+ storefront_visible: false
+ searchable: false
+ sortable: false
+ filter_key: cf_specs_fabric
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id: adm_UkLWZg9DAJ
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
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:
+ label:
type: string
- description: Staff-facing note about the cancellation.
- refund_payments:
+ storefront_visible:
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:
+ searchable:
type: boolean
- default: false
- description: Send the order cancellation email after canceling.
- "/api/v3/admin/orders/{id}/approve":
- patch:
- summary: Approve an order
+ sortable:
+ type: boolean
+ delete:
+ summary: Delete a custom field definition
tags:
- - Orders
+ - Custom Fields
security:
- api_key: []
bearer_auth: []
description: |-
- Approves an order (e.g., for fraud review).
+ Deletes the definition and cascades to all custom field values referencing it.
- **Required scope:** `write_orders` (for API-key authentication).
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15842,10 +4957,10 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.approve('or_UkLWZg9DAJ')
+ await client.customFieldDefinitions.delete('cfd_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{id}/approve -d '{ ... }'
+ source: spree api delete /custom_field_definitions/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -15855,119 +4970,34 @@ 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: order approved
- content:
- application/json:
- example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: placed
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- 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'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id: adm_UkLWZg9DAJ
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
- "/api/v3/admin/orders/{id}/resend_confirmation":
- post:
- summary: Resend confirmation email
+ '204':
+ description: definition deleted
+ "/api/v3/admin/customer_groups":
+ get:
+ summary: List customer groups
tags:
- - Orders
+ - Customer Groups
security:
- api_key: []
bearer_auth: []
description: |-
- Publishes the order.completed event to trigger confirmation email delivery.
+ Returns the customer groups configured for the current store. Groups
+ segment customers for targeted promotions (see the `customer_group`
+ promotion rule) and reporting. The list endpoint never embeds the
+ member list — fetch a single group with `?expand=customers` if you
+ need them inline, or query `/admin/customers?customer_group_id_in=…`
+ for paginated membership.
- **Required scope:** `write_orders` (for API-key authentication).
+
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -15979,10 +5009,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.orders.resendConfirmation('or_UkLWZg9DAJ')
+ const { data: groups } = await client.customerGroups.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
- source: spree api post /orders/{id}/resend_confirmation -d '{ ... }'
+ source: spree api get /customer_groups -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -15995,121 +5025,102 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: id
- in: path
- required: true
- description: Order ID
+ - 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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - 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
responses:
'200':
- description: confirmation resent
+ description: customer groups found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_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
- supported_locales:
- - en
- tax_provider:
- created_at: '2026-09-03T20:59:04.067Z'
- updated_at: '2026-09-03T20:59:04.067Z'
- external_references: {}
- status: placed
- last_ip_address:
- considered_risky: false
- confirmation_delivered: false
- store_owner_notification_delivered:
- payment_total: '0.0'
- display_payment_total: "$0.00"
- metadata: {}
- cancel_note:
- canceled_at:
- approved_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- preferred_stock_location_id:
- po_document_url:
- seller_id:
- order_group_id:
- tags: []
- internal_note:
- internal_note_html:
- approver_id:
- canceler_id:
- cancel_reason_id:
- cancel_reason_name:
- created_by_id:
- customer_id: cust_UkLWZg9DAJ
- "/api/v3/admin/auth/password_resets":
+ data:
+ - id: cg_UkLWZg9DAJ
+ name: VIPs
+ description: Top spenders
+ customers_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: cg_gbHJdmfrXB
+ name: Wholesale
+ description:
+ customers_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ 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/CustomerGroup"
+ 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: Request password reset
+ summary: Create a customer group
tags:
- - Authentication
+ - Customer Groups
security:
- api_key: []
- description: |
- Requests a password reset email for an admin user. Always returns `202`
- whether or not the email matches an account, to prevent enumeration.
+ bearer_auth: []
+ description: |-
+ Creates a customer group in the current store. `customer_ids` is
+ optional; when present, customers are attached at create time.
+ Pass prefixed IDs (e.g. `cus_…`) — the server decodes them
+ automatically.
- `redirect_url` is where the emailed link should point (the reset token
- is appended as a `token` query param). It must match one of the store's
- allowed origins — otherwise it is silently ignored and the server-side
- default is used. The email is delivered by Spree itself via the
- `admin_user.password_reset_requested` event; this event is never
- forwarded to webhook endpoints.
+
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16121,59 +5132,96 @@ paths:
secretKey: 'sk_xxx',
})
- // Always resolves (202) whether or not the email exists — no account enumeration.
- // The emailed link points at redirect_url with the reset token appended as ?token=.
- await client.auth.requestPasswordReset({
- email: '[email protected]',
- redirect_url: 'https://admin.your-store.com/reset-password',
+ const group = await client.customerGroups.create({
+ name: 'VIP customers',
+ description: 'Top spenders, eligible for early access',
+ customer_ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
})
- lang: bash
label: Spree CLI
- source: spree api post /auth/password_resets -d '{"email":"[email protected]","redirect_url":"https://admin.your-store.com/reset-password"}'
+ source: spree api post /customer_groups -d '{"name":"VIP customers","description":"Top
+ spenders, eligible for early access","customer_ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"]}'
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
responses:
- '202':
- description: reset requested
+ '201':
+ description: customer group created
content:
application/json:
example:
- message: If an account exists for that email, password reset instructions
- have been sent.
+ id: cg_EfhxLZ9ck8
+ name: Wholesale 2
+ description: B2B accounts
+ customers_count: 1
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/CustomerGroup"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - name
properties:
- email:
+ name:
type: string
- format: email
- redirect_url:
+ example: Wholesale
+ description:
type: string
- example: https://admin.your-store.com/reset-password
- description: Must match an allowed origin of the store; ignored
- otherwise.
- required:
- - email
- "/api/v3/admin/auth/password_resets/{id}":
- patch:
- summary: Reset password
+ example: B2B accounts
+ nullable: true
+ customer_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - cus_UkLWZg9DAJ
+ "/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:
- - Authentication
+ - Customer Groups
security:
- api_key: []
- description: |
- Consumes a password reset token (the `token` query param from the
- emailed link), sets the new password, and signs the admin in: the
- response carries a JWT access token and the rotatable refresh token is
- set in an HttpOnly cookie. The token is single-use — it invalidates as
- soon as the password changes.
+ bearer_auth: []
+ description: |-
+ Returns a single customer group. Pass `?expand=customers` to embed
+ the full member list inline (recommended only for single-record
+ reads — embed cost scales with membership size).
+
+
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16185,90 +5233,99 @@ paths:
secretKey: 'sk_xxx',
})
- // The token comes from the emailed link's ?token= param. On success the admin
- // is signed in: a JWT comes back and the refresh token is set as an HttpOnly cookie.
- const auth = await client.auth.resetPassword('reset-token-from-email', {
- password: 'new-password-123',
- password_confirmation: 'new-password-123',
- })
+ // Pass `expand: ['customers']` to embed the group's customers in the response
+ // — omit it for the much smaller index-payload shape.
+ const group = await client.customerGroups.get('cg_UkLWZg9DAJ', { expand: ['customers'] })
- lang: bash
label: Spree CLI
- source: spree api patch /auth/password_resets/{id} -d '{"password":"new-password-123","password_confirmation":"new-password-123"}'
+ source: spree api get /customer_groups/{id} -d '{"expand":["customers"]}'
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
+ - 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: password reset
+ description: customer group with embedded customers
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjBiZTdhM2RmLWEyYzYtNDZkOC1hNTZiLWE4NDg4MGIyZGZiNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Vo2RzprqsH2XBa8DaSQ6awyXqlBA5QDFA5R7ygTezXY
- user:
- id: adm_UkLWZg9DAJ
- first_name: Olga
- last_name: Schneider
- full_name: Olga Schneider
- selected_locale:
+ id: cg_UkLWZg9DAJ
+ name: VIPs
+ description: Top spenders
+ customers_count: 1
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ customers:
+ - id: cust_UkLWZg9DAJ
+ first_name: Dan
+ last_name: Ebert
+ phone:
+ accepts_email_marketing: false
+ full_name: Dan Ebert
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ failed_attempts: 0
+ metadata: {}
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_18
+ tags: []
+ internal_note:
+ internal_note_html:
+ default_billing_address_id:
+ default_shipping_address_id:
+ orders_count: 0
+ total_spent: '0.0'
+ display_total_spent: "$0.00"
+ last_order_completed_at:
+ customer_group_ids:
+ - cg_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/AuthResponse"
- '422':
- description: invalid or expired token
+ "$ref": "#/components/schemas/CustomerGroup"
+ '404':
+ description: customer group not found
content:
application/json:
example:
error:
- code: password_reset_token_invalid
- message: Password reset token is invalid or has expired.
+ code: record_not_found
+ message: Customer group not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- password:
- type: string
- example: new-password-123
- password_confirmation:
- type: string
- example: new-password-123
- required:
- - password
- - password_confirmation
- "/api/v3/admin/payment_methods":
- get:
- summary: List payment methods
+ patch:
+ summary: Update a customer group
tags:
- - Payment Methods
+ - Customer Groups
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.
+ Updates name, description, or membership. `customer_ids` is a
+ full-set replacement — the server reconciles the membership to
+ match the array, adding new IDs and removing ones not present.
+ Send `customer_ids: []` to clear all members.
- **Required scope:** `read_settings` (for API-key authentication).
+
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16280,10 +5337,15 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: paymentMethods } = await client.paymentMethods.list()
+ // `customer_ids` is a full-set update — the model reconciles the membership
+ // to match the array (adds new IDs, removes ones not present).
+ const group = await client.customerGroups.update('cg_UkLWZg9DAJ', {
+ name: 'VIP customers (Q1)',
+ customer_ids: ['cus_UkLWZg9DAJ'],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /payment_methods
+ source: spree api patch /customer_groups/{id} -d '{"name":"VIP customers (Q1)","customer_ids":["cus_UkLWZg9DAJ"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -16295,66 +5357,63 @@ paths:
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 methods found
+ description: customer group updated
content:
application/json:
example:
- data:
- - id: pm_UkLWZg9DAJ
- name: Check
- 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: {}
- preference_schema: []
- 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
+ id: cg_UkLWZg9DAJ
+ name: VIP customers (Q1)
+ description: Top spenders
+ customers_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/CustomerGroup"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: VIP customers (Q1)
+ description:
+ type: string
+ example: Updated description
+ nullable: true
+ customer_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - cus_UkLWZg9DAJ
+ delete:
+ summary: Delete a customer group
tags:
- - Payment Methods
+ - Customer Groups
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a "Provider" dropdown in admin UIs.
+ Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16366,10 +5425,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: types } = await client.paymentMethods.types()
+ await client.customerGroups.delete('cg_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /payment_methods/types
+ source: spree api delete /customer_groups/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -16382,38 +5441,20 @@ paths:
schema:
type: string
responses:
- '200':
- description: provider types found
- content:
- application/json:
- example:
- data:
- - type: bogus
- label: Bogus
- description:
- preference_schema:
- - key: dummy_key
- type: string
- default: PUBLICKEY123
- - key: dummy_secret_key
- type: password
- default:
- - type: custom_payment_source_method
- label: Custom Payment Source Method
- description:
- preference_schema: []
- "/api/v3/admin/payment_methods/{id}":
+ '204':
+ description: customer group deleted
+ "/api/v3/admin/customers/{customer_id}/addresses":
get:
- summary: Show a payment method
+ summary: List customer addresses
tags:
- - Payment Methods
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a payment method by ID.
+ Returns the customer's saved addresses.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16425,10 +5466,10 @@ paths:
secretKey: 'sk_xxx',
})
- const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')
+ const { data: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /payment_methods/{id}
+ source: spree api get /customers/{customer_id}/addresses
parameters:
- name: x-spree-api-key
in: header
@@ -16440,7 +5481,7 @@ paths:
required: true
schema:
type: string
- - name: id
+ - name: customer_id
in: path
required: true
schema:
@@ -16448,52 +5489,74 @@ paths:
- name: expand
in: query
required: false
- description: Comma-separated associations to expand. Use dot notation for
- nested expand (max 4 levels).
+ 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., name,type,active).
+ description: Comma-separated list of fields to include (e.g., first_name,last_name,address1,city).
id is always included.
schema:
type: string
responses:
'200':
- description: payment method found
+ description: addresses found
content:
application/json:
example:
- id: pm_UkLWZg9DAJ
- name: Check
- 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: {}
- preference_schema: []
- "/api/v3/admin/permissions":
- get:
- summary: List the permission catalog
+ data:
+ - id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 5 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: cust_UkLWZg9DAJ
+ owner_id: cust_UkLWZg9DAJ
+ owner_type: Spree::Customer
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create a customer address
tags:
- - Staff
+ - Customers
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: |-
+ 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.
+
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16505,10 +5568,23 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: permissions } = await client.permissions.list()
+ const address = await client.customers.addresses.create('cus_UkLWZg9DAJ', {
+ 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',
+ label: 'Office',
+ is_default_shipping: true,
+ })
- lang: bash
label: Spree CLI
- source: spree api get /permissions
+ source: spree api post /customers/{customer_id}/addresses -d '{"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","label":"Office","is_default_shipping":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -16520,391 +5596,239 @@ paths:
required: true
schema:
type: string
+ - name: customer_id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
- '200':
- description: catalog returned
+ '201':
+ description: address created
content:
application/json:
example:
- data:
- - 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
- resource: fulfillments
- kind: write
- group: orders
- group_label: Orders
- label: Fulfillments
- description: Pack, ship and track order fulfillments
- - key: read_refunds
- resource: refunds
- kind: read
- group: orders
- group_label: Orders
- label: Refunds
- description: Issue and view refunds
- - key: write_refunds
- resource: refunds
- kind: write
- group: orders
- group_label: Orders
- label: Refunds
- description: Issue and view refunds
- - key: read_gift_cards
- resource: gift_cards
- kind: read
- group: orders
- group_label: Orders
- label: Gift cards
- description: Gift cards and gift card batches
- - key: write_gift_cards
- resource: gift_cards
- kind: write
- group: orders
- group_label: Orders
- label: Gift cards
- description: Gift cards and gift card batches
- - key: read_store_credits
- resource: store_credits
- kind: read
- group: orders
- group_label: Orders
- label: Store credits
- description: Customer store credit balances
- - key: write_store_credits
- resource: store_credits
- kind: write
- group: orders
- group_label: Orders
- label: Store credits
- description: Customer store credit balances
- - key: read_products
- resource: products
- kind: read
- group: catalog
- group_label: Catalog
- label: Products
- description: Products, variants, options, prices and media
- - key: write_products
- resource: products
- kind: write
- group: catalog
- group_label: Catalog
- label: Products
- description: Products, variants, options, prices and media
- - key: read_product_types
- resource: product_types
- kind: read
- group: catalog
- group_label: Catalog
- label: Product types
- description: ''
- - key: write_product_types
- resource: product_types
- kind: write
- group: catalog
- group_label: Catalog
- label: Product types
- description: ''
- - key: read_publishing
- resource: publishing
- kind: read
- group: catalog
- group_label: Catalog
- label: Publishing
- description: ''
- - key: write_publishing
- resource: publishing
- kind: write
- group: catalog
- group_label: Catalog
- label: Publishing
- description: ''
- - key: read_media
- resource: media
- kind: read
- group: catalog
- group_label: Catalog
- label: Media
- description: ''
- - key: write_media
- resource: media
- kind: write
- group: catalog
- group_label: Catalog
- label: Media
- description: ''
- - key: read_categories
- resource: categories
- kind: read
- group: catalog
- group_label: Catalog
- label: Categories
- description: Category tree and taxonomies
- - key: write_categories
- resource: categories
- kind: write
- group: catalog
- group_label: Catalog
- label: Categories
- description: Category tree and taxonomies
- - key: read_collections
- resource: collections
- kind: read
- group: catalog
- group_label: Catalog
- label: Collections
- description: Manual and rule-based product collections
- - key: write_collections
- resource: collections
- kind: write
- group: catalog
- group_label: Catalog
- label: Collections
- description: Manual and rule-based product collections
- - key: read_stock
- resource: stock
- kind: read
- group: catalog
- group_label: Catalog
- label: Inventory
- description: Stock levels, locations, movements and transfers
- - key: write_stock
- resource: stock
- kind: write
- group: catalog
- group_label: Catalog
- label: Inventory
- description: Stock levels, locations, movements and transfers
- - key: read_promotions
- resource: promotions
- kind: read
- group: marketing
- group_label: Marketing
- label: Promotions
- description: Promotions, rules and coupon codes
- - key: write_promotions
- resource: promotions
- kind: write
- group: marketing
- group_label: Marketing
- label: Promotions
- description: Promotions, rules and coupon codes
- - key: read_customers
- resource: customers
- kind: read
- group: customers
- group_label: Customers
- label: Customers
- description: Customer accounts, addresses, cards and groups
- - key: write_customers
- resource: customers
- kind: write
- group: customers
- group_label: Customers
- label: Customers
- description: Customer accounts, addresses, cards and groups
- - key: read_settings
- resource: settings
- kind: read
- group: settings
- group_label: Settings
- label: Store settings
- description: Store, payment, delivery, tax and channel configuration
- - key: write_settings
- resource: settings
- kind: write
- group: settings
- group_label: Settings
- label: Store settings
- description: Store, payment, delivery, tax and channel configuration
- - key: read_delivery_methods
- resource: delivery_methods
- kind: read
- group: settings
- group_label: Settings
- label: Delivery methods
- description: ''
- - key: write_delivery_methods
- resource: delivery_methods
- kind: write
- group: settings
- group_label: Settings
- label: Delivery methods
- description: ''
- - key: read_webhooks
- resource: webhooks
- kind: read
- group: settings
- group_label: Settings
- label: Webhooks
- description: Webhook endpoints and deliveries
- - key: write_webhooks
- resource: webhooks
- kind: write
- group: settings
- group_label: Settings
- label: Webhooks
- description: Webhook endpoints and deliveries
- - key: read_integrations
- resource: integrations
- kind: read
- group: settings
- group_label: Settings
- label: Integrations
- description: ''
- - key: write_integrations
- resource: integrations
- kind: write
- group: settings
- group_label: Settings
- label: Integrations
- description: ''
- - key: read_api_keys
- resource: api_keys
- kind: read
- group: access
- group_label: Access
- label: API keys
- description: Create and revoke API credentials
- - key: write_api_keys
- resource: api_keys
- kind: write
- group: access
- group_label: Access
- label: API keys
- description: Create and revoke API credentials
- - key: read_staff
- resource: staff
- kind: read
- group: access
- group_label: Access
- label: Staff & roles
- description: Team members, invitations, roles and their permissions
- - key: write_staff
- resource: staff
- kind: write
- group: access
- group_label: Access
- label: Staff & roles
- description: Team members, invitations, roles and their permissions
- - key: read_sellers
- resource: sellers
- kind: read
- group: access
- group_label: Access
- label: Sellers
- description: ''
- - key: write_sellers
- resource: sellers
- kind: write
- group: access
- group_label: Access
- label: Sellers
- description: ''
- - key: read_commissions
- resource: commissions
- kind: read
- group: access
- group_label: Access
- label: Commissions
- description: ''
- - key: write_commissions
- resource: commissions
- kind: write
- group: access
- group_label: Access
- label: Commissions
- description: ''
- - key: read_payouts
- resource: payouts
- kind: read
- group: access
- group_label: Access
- label: Payouts
- description: ''
- - key: write_payouts
- resource: payouts
- kind: write
- group: access
- group_label: Access
- label: Payouts
- description: ''
- - key: read_seller_profile
- resource: seller_profile
- kind: read
- group: access
- group_label: Access
- label: Seller profile
- description: ''
- - key: write_seller_profile
- resource: seller_profile
- kind: write
- group: access
- group_label: Access
- label: Seller profile
- description: ''
- - key: read_dashboard
- resource: dashboard
- kind: read
- group: analytics
- group_label: Analytics
- label: Analytics dashboard
- description: Sales and performance analytics
- meta:
- count: 51
- "/api/v3/admin/policies":
- get:
- summary: List policies
+ id: addr_gbHJdmfrXB
+ label: Office
+ first_name: Jane
+ last_name: Doe
+ full_name: Jane Doe
+ address1: 350 Fifth Avenue
+ address2:
+ postal_code: '10118'
+ city: New York
+ phone: "+12125551234"
+ 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: cust_UkLWZg9DAJ
+ owner_id: cust_UkLWZg9DAJ
+ owner_type: Spree::Customer
+ 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.
+
+ **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',
+ })
+
+ const address = await client.customers.addresses.update('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ', {
+ city: 'Manhattan',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /customers/{customer_id}/addresses/{id} -d '{"city":"Manhattan"}'
+ 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:
+ example:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 7 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: Manhattan
+ 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: cust_UkLWZg9DAJ
+ owner_id: cust_UkLWZg9DAJ
+ owner_type: Spree::Customer
+ 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:
- - Policies
+ - Customers
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.
+ Deletes the address. If it was a default, the customer loses that default (no auto-promotion).
- A marketplace seller's own policies are managed by the seller and are
- not listed here.
+ **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',
+ })
- **Required scope:** `read_settings` (for API-key authentication).
+ await client.customers.addresses.delete('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /customers/{customer_id}/addresses/{id}
+ 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 }`.
+
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -16916,10 +5840,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: policies } = await client.policies.list()
+ const { data: cards } = await client.customers.creditCards.list('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /policies
+ source: spree api get /customers/{customer_id}/credit_cards
parameters:
- name: x-spree-api-key
in: header
@@ -16929,124 +5853,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
+ - name: customer_id
+ in: path
+ required: true
schema:
- type: integer
- - name: q[name_cont]
+ type: string
+ - name: expand
in: query
required: false
- description: Filter by name (contains)
+ 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. id is always included.
+ description: Comma-separated list of fields to include (e.g., brand,last4,month,year).
+ id is always included.
schema:
type: string
responses:
'200':
- description: policies listed
+ description: credit cards found
content:
application/json:
example:
data:
- - id: pol_gbHJdmfrXB
- name: Privacy Policy
- slug: privacy-policy
- body: ''
- body_html: ''
- updated_at: '2026-09-03T20:59:05.050Z'
- created_at: '2026-09-03T20:59:05.050Z'
- - 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: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ customer_id: cust_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
- - id: pol_EfhxLZ9ck8
- name: Returns Policy
- slug: returns-policy
- body: ''
- body_html: ''
- updated_at: '2026-09-03T20:59:05.072Z'
- created_at: '2026-09-03T20:59:05.072Z'
- - id: pol_VqXmZF31wY
- name: Shipping Policy
- slug: shipping-policy
- body: ''
- body_html: ''
- updated_at: '2026-09-03T20:59:05.115Z'
- created_at: '2026-09-03T20:59:05.115Z'
- - id: pol_UkLWZg9DAJ
- name: Terms of Service
- slug: terms-of-service
- body: ''
- body_html: ''
- updated_at: '2026-09-03T20:59:04.981Z'
- created_at: '2026-09-03T20:59:04.981Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
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
+ "/api/v3/admin/customers/{customer_id}/credit_cards/{id}":
+ get:
+ summary: Show a customer credit card
tags:
- - Policies
+ - Customers
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.
-
+ Returns a saved credit card by ID.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17058,14 +5927,10 @@ paths:
secretKey: 'sk_xxx',
})
- const policy = await client.policies.create({
- name: 'Wholesale Policy',
- body: '<p>Trade orders ship within five working days.</p>',
- })
+ const card = await client.customers.creditCards.get('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')
- 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 get /customers/{customer_id}/credit_cards/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -17075,73 +5940,113 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ 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:
- '201':
- description: policy created
+ '200':
+ description: credit card found
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: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ customer_id: cust_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/Policy"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Wholesale Policy
- slug:
- type: string
- example: wholesale-policy
- body:
- 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
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delete:
+ summary: Delete a customer credit card
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Deletes a saved credit card.
+
+ **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',
+ })
+
+ await client.customers.creditCards.delete('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /customers/{customer_id}/credit_cards/{id}
+ 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: Get a policy
+ summary: List customer store credits
tags:
- - Policies
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single policy, addressed by prefixed ID or by slug.
+ Returns store credits issued to the customer.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_store_credits` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17153,11 +6058,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Addressable by slug as well as prefixed id.
- const policy = await client.policies.get('returns-policy')
+ const { data: storeCredits } = await client.customers.storeCredits.list('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /policies/{id}
+ source: spree api get /customers/{customer_id}/store_credits
parameters:
- name: x-spree-api-key
in: header
@@ -17167,45 +6071,154 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ 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., 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
responses:
'200':
- description: policy found
+ description: store credits 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
+ data:
+ - id: credit_UkLWZg9DAJ
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.00"
+ currency: USD
+ memo:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ customer_id: cust_UkLWZg9DAJ
+ created_by_id: adm_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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',
+ })
+
+ const credit = await client.customers.storeCredits.create('cus_UkLWZg9DAJ', {
+ amount: '25.00',
+ currency: 'USD',
+ memo: 'Goodwill credit',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /customers/{customer_id}/store_credits -d '{"amount":"25.00","currency":"USD","memo":"Goodwill
+ credit"}'
+ 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:
example:
- error:
- code: record_not_found
- message: Policy not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ id: credit_gbHJdmfrXB
+ amount: '25.0'
+ amount_used: '0.0'
+ amount_remaining: '25.0'
+ display_amount: "$25.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$25.00"
+ currency: USD
+ memo: Goodwill
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ customer_id: cust_UkLWZg9DAJ
+ created_by_id: adm_gbHJdmfrXB
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - amount
+ - currency
+ properties:
+ amount:
+ type: string
+ example: '50.00'
+ currency:
+ type: string
+ example: USD
+ memo:
+ type: string
+ "/api/v3/admin/customers/{customer_id}/store_credits/{id}":
patch:
- summary: Update a policy
+ summary: Update a store credit
tags:
- - Policies
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a policy. `body` accepts HTML and is sanitized before it is stored.
+ Update memo / amount. The amount can only be changed if `amount_used == 0`.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_store_credits` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17217,13 +6230,13 @@ paths:
secretKey: 'sk_xxx',
})
- const policy = await client.policies.update('returns-policy', {
- body: '<p>Return anything unopened within 60 days.</p>',
+ const credit = await client.customers.storeCredits.update('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ', {
+ memo: 'Reissued for damaged shipment',
})
- 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 /customers/{customer_id}/store_credits/{id} -d '{"memo":"Reissued
+ for damaged shipment"}'
parameters:
- name: x-spree-api-key
in: header
@@ -17233,49 +6246,60 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ 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: policy updated
+ description: store credit 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: credit_UkLWZg9DAJ
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.00"
+ currency: USD
+ memo: Updated
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/Policy"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ customer_id: cust_UkLWZg9DAJ
+ created_by_id: adm_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- slug:
+ amount:
type: string
- body:
+ example: '50.00'
+ memo:
type: string
delete:
- summary: Delete a policy
+ summary: Delete a store credit
tags:
- - Policies
+ - Customers
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.
-
+ Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_store_credits` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17287,10 +6311,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.policies.delete('wholesale-policy')
+ await client.customers.storeCredits.delete('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /policies/{id}
+ source: spree api delete /customers/{customer_id}/store_credits/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -17300,24 +6324,33 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
+ 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: policy deleted
- "/api/v3/admin/price_lists":
+ description: store credit deleted
+ "/api/v3/admin/customers":
get:
- summary: List price lists
+ summary: List customers
tags:
- - Pricing
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the price lists configured for the current store.
+ Returns a paginated list of customers. Supports Ransack search/filters.
- **Required scope:** `read_products` (for API-key authentication).
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17329,10 +6362,14 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: priceLists } = await client.priceLists.list()
+ const { data: customers } = await client.customers.list({
+ search: 'jane',
+ sort: '-created_at',
+ limit: 25,
+ })
- lang: bash
label: Spree CLI
- source: spree api get /price_lists
+ source: spree api get /customers -d '{"search":"jane","sort":"-created_at","limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -17342,6 +6379,7 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- name: page
@@ -17354,101 +6392,77 @@ paths:
required: false
schema:
type: integer
- - name: q[name_cont]
- in: query
- required: false
- schema:
- type: string
- - name: q[status_eq]
+ - name: q[search]
in: query
required: false
+ description: Email + name full-text-ish search
schema:
type: string
- - name: sort
+ - 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: expand
+ - name: fields
in: query
required: false
- description: 'Comma-separated associations to embed. Supported: `price_rules`.'
+ 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: price lists found
+ description: customers found
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
- - id: pl_gbHJdmfrXB
- name: Holiday
- description:
- status: draft
- position: 2
- match_policy: all
- adjust_compare_at: false
- starts_at:
- ends_at:
- deleted_at:
+ - id: cust_UkLWZg9DAJ
+ first_name: Jane
+ last_name: Doe
+ phone:
+ accepts_email_marketing: false
+ full_name: Jane Doe
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ failed_attempts: 0
+ metadata: {}
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
+ tags: []
+ internal_note:
+ internal_note_html:
+ default_billing_address_id:
+ default_shipping_address_id:
+ orders_count: 0
+ total_spent: '0'
+ display_total_spent: "$0.00"
+ last_order_completed_at:
+ customer_group_ids: []
meta:
page: 1
limit: 25
- count: 2
+ count: 1
pages: 1
from: 1
- to: 2
- in: 2
+ to: 1
+ in: 1
previous:
next:
- 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
+ summary: Create a customer
tags:
- - Pricing
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new draft price list.
+ Creates a customer. No welcome email is sent automatically.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17460,45 +6474,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',
- },
- ],
+ const customer = await client.customers.create({
+ email: '[email protected]',
+ first_name: 'Jane',
+ last_name: 'Doe',
+ phone: '+1 212 555 1234',
+ tags: ['wholesale'],
+ accepts_email_marketing: true,
})
- 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 post /customers -d '{"email":"[email protected]","first_name":"Jane","last_name":"Doe","phone":"+1
+ 212 555 1234","tags":["wholesale"],"accepts_email_marketing":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -17512,131 +6499,72 @@ paths:
type: string
responses:
'201':
- description: price list created (server-to-server — rules + prices)
+ description: customer created
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: cust_gbHJdmfrXB
+ first_name: New
+ last_name: Customer
+ phone:
+ accepts_email_marketing: false
+ full_name: New Customer
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ failed_attempts: 0
+ metadata: {}
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
- 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:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ tags: []
+ internal_note:
+ internal_note_html:
+ default_billing_address_id:
+ default_shipping_address_id:
+ orders_count: 0
+ total_spent: '0.0'
+ display_total_spent: "$0.00"
+ last_order_completed_at:
+ customer_group_ids: []
requestBody:
content:
application/json:
schema:
type: object
required:
- - name
+ - email
properties:
- name:
+ email:
type: string
- example: EU wholesale
- description:
+ first_name:
type: string
- nullable: true
- starts_at:
+ last_name:
type: string
- nullable: true
- example: '2026-06-01T00:00:00Z'
- ends_at:
+ phone:
type: string
- nullable: true
- example: '2026-09-01T00:00:00Z'
- match_policy:
+ accepts_email_marketing:
+ type: boolean
+ internal_note:
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:
+ tags:
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
+ type: string
+ metadata:
+ type: object
+ "/api/v3/admin/customers/{id}":
get:
- summary: Get a price list
+ summary: Show a customer
tags:
- - Pricing
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_products` (for API-key authentication)."
+ description: |-
+ Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).
+
+ **Required scope:** `read_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17648,10 +6576,12 @@ paths:
secretKey: 'sk_xxx',
})
- const priceList = await client.priceLists.get('pl_xxx')
+ const customer = await client.customers.get('cus_UkLWZg9DAJ', {
+ expand: ['addresses', 'store_credits'],
+ })
- lang: bash
label: Spree CLI
- source: spree api get /price_lists/{id}
+ source: spree api get /customers/{id} -d '{"expand":["addresses","store_credits"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -17663,61 +6593,66 @@ paths:
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: price list found
+ description: customer found
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: cust_UkLWZg9DAJ
+ first_name: Jane
+ last_name: Doe
+ phone:
+ accepts_email_marketing: false
+ full_name: Jane Doe
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ failed_attempts: 0
+ metadata: {}
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
- 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"
+ tags: []
+ internal_note:
+ internal_note_html:
+ default_billing_address_id:
+ default_shipping_address_id:
+ orders_count: 0
+ total_spent: '0'
+ display_total_spent: "$0.00"
+ last_order_completed_at:
+ customer_group_ids: []
patch:
- summary: Update a price list
+ summary: Update a customer
tags:
- - Pricing
+ - Customers
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.
-
+ Updates customer attributes. `tags` replaces the full set.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17729,12 +6664,13 @@ paths:
secretKey: 'sk_xxx',
})
- const priceList = await client.priceLists.update('pl_xxx', {
- name: 'Wholesale (Q3)',
+ const customer = await client.customers.update('cus_UkLWZg9DAJ', {
+ first_name: 'Updated',
+ tags: ['wholesale', 'vip'],
})
- lang: bash
label: Spree CLI
- source: spree api patch /price_lists/{id} -d '{"name":"Wholesale (Q3)"}'
+ source: spree api patch /customers/{id} -d '{"first_name":"Updated","tags":["wholesale","vip"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -17746,113 +6682,75 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: price list updated with nested rules
+ description: customer updated
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: cust_UkLWZg9DAJ
+ first_name: Updated
+ last_name: Doe
+ phone:
+ accepts_email_marketing: false
+ full_name: Updated Doe
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ failed_attempts: 0
+ metadata: {}
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: 1
- schema:
- "$ref": "#/components/schemas/PriceList"
+ tags: []
+ internal_note:
+ internal_note_html:
+ default_billing_address_id:
+ default_shipping_address_id:
+ orders_count: 0
+ total_spent: '0.0'
+ display_total_spent: "$0.00"
+ last_order_completed_at:
+ customer_group_ids: []
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
+ email:
type: string
- description:
+ first_name:
type: string
- nullable: true
- starts_at:
+ last_name:
type: string
- nullable: true
- ends_at:
+ phone:
type: string
- nullable: true
- match_policy:
+ accepts_email_marketing:
+ type: boolean
+ internal_note:
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'
+ tags:
+ type: array
+ items:
+ type: string
+ metadata:
+ type: object
delete:
- summary: Delete a price list
+ summary: Delete a customer
tags:
- - Pricing
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes the price list. Associated prices are removed asynchronously.
+ Deletes a customer. Returns 422 if the customer has any orders.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17864,10 +6762,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.priceLists.delete('pl_xxx')
+ await client.customers.delete('cus_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /price_lists/{id}
+ source: spree api delete /customers/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -17879,30 +6777,30 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ 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
+ description: customer deleted
+ "/api/v3/admin/customers/bulk_add_to_groups":
+ post:
+ summary: Bulk-add customers to groups
tags:
- - Pricing
+ - Customers
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.
+ Attaches each customer in `ids` to every group in `customer_group_ids`.
+ Idempotent — customers already in a group are skipped server-side.
+ Groups from sibling stores are silently ignored. Returns counts of
+ customers and groups that were processed (post store-scoping).
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17914,10 +6812,13 @@ paths:
secretKey: 'sk_xxx',
})
- const priceList = await client.priceLists.activate('pl_xxx')
+ const result = await client.customers.bulkAddToGroups({
+ ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
+ customer_group_ids: ['cg_UkLWZg9DAJ'],
+ })
- lang: bash
label: Spree CLI
- source: spree api patch /price_lists/{id}/activate -d '{ ... }'
+ source: spree api post /customers/bulk_add_to_groups -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -17931,26 +6832,55 @@ paths:
type: string
responses:
'200':
- description: price list activated
+ description: customers added to groups
content:
application/json:
+ example:
+ customer_count: 1
+ customer_group_count: 1
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
+ 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
+ example:
+ - cus_UkLWZg9DAJ
+ - cus_QrLWXg9CAJ
+ customer_group_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - cg_UkLWZg9DAJ
+ "/api/v3/admin/customers/bulk_remove_from_groups":
+ post:
+ summary: Bulk-remove customers from groups
tags:
- - Pricing
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_products` (for API-key authentication)."
+ description: |-
+ Detaches each customer in `ids` from every group in `customer_group_ids`.
+ No-op for non-members. Groups from sibling stores are silently ignored.
+
+
+ **Required scope:** `write_customers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -17962,10 +6892,13 @@ paths:
secretKey: 'sk_xxx',
})
- const priceList = await client.priceLists.deactivate('pl_xxx')
+ const result = await client.customers.bulkRemoveFromGroups({
+ ids: ['cus_UkLWZg9DAJ'],
+ customer_group_ids: ['cg_UkLWZg9DAJ'],
+ })
- lang: bash
label: Spree CLI
- source: spree api patch /price_lists/{id}/deactivate -d '{ ... }'
+ source: spree api post /customers/bulk_remove_from_groups -d '{"ids":["cus_UkLWZg9DAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -17979,27 +6912,72 @@ paths:
type: string
responses:
'200':
- description: price list deactivated
+ description: customers removed from groups
content:
application/json:
example:
- error:
- code: record_not_found
- message: Price list not found
+ customer_count: 1
+ customer_group_count: 1
schema:
- "$ref": "#/components/schemas/PriceList"
- "/api/v3/admin/price_lists/{price_list_id}/products":
- get:
- summary: List price list products
+ 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
+ example:
+ - cus_UkLWZg9DAJ
+ customer_group_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - cg_UkLWZg9DAJ
+ "/api/v3/admin/customers/bulk_add_tags":
+ post:
+ summary: Bulk-add tags to customers
tags:
- - Price Lists
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- The products the list prices, listed by name — membership is derived from the price rows.
+ Adds each tag name in `tags` to every customer in `ids`. Tags are
+ upserted by name; re-adding an existing tag is a no-op.
- **Required scope:** `read_products` (for API-key authentication).
+
+ **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',
+ })
+
+ const result = await client.customers.bulkAddTags({
+ ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],
+ tags: ['vip', 'newsletter'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /customers/bulk_add_tags -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"tags":["vip","newsletter"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -18011,87 +6989,75 @@ paths:
required: true
schema:
type: string
- - name: price_list_id
- in: path
- required: true
- schema:
- type: string
responses:
'200':
- description: products found
+ description: tags added
content:
application/json:
example:
- error:
- code: record_not_found
- message: Price list not found
+ customer_count: 1
+ tag_count: 2
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 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.
-
- **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
+ customer_count:
+ type: integer
+ tag_count:
+ type: integer
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - ids
+ - tags
properties:
- product_ids:
+ ids:
type: array
items:
type: string
example:
- - prod_abc123
- required:
- - product_ids
- delete:
- summary: Remove products from a price list
+ - cus_UkLWZg9DAJ
+ tags:
+ type: array
+ items:
+ type: string
+ example:
+ - vip
+ - newsletter
+ "/api/v3/admin/customers/bulk_remove_tags":
+ post:
+ summary: Bulk-remove tags from customers
tags:
- - Price Lists
+ - Customers
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.
+ Removes each tag name in `tags` from every customer in `ids`. No-op
+ for customers that don't carry the tag.
- **Required scope:** `write_products` (for API-key authentication).
+
+ **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',
+ })
+
+ const result = await client.customers.bulkRemoveTags({
+ ids: ['cus_UkLWZg9DAJ'],
+ tags: ['vip'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /customers/bulk_remove_tags -d '{"ids":["cus_UkLWZg9DAJ"],"tags":["vip"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -18103,46 +7069,54 @@ paths:
required: true
schema:
type: string
- - name: price_list_id
- in: path
- required: true
- schema:
- type: string
responses:
'200':
- description: products removed
+ description: tags removed
+ content:
+ application/json:
+ example:
+ customer_count: 1
+ tag_count: 1
+ schema:
+ type: object
+ properties:
+ customer_count:
+ type: integer
+ tag_count:
+ type: integer
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - ids
+ - tags
properties:
- product_ids:
+ ids:
type: array
items:
type: string
example:
- - prod_abc123
- required:
- - product_ids
- "/api/v3/admin/prices":
+ - cus_UkLWZg9DAJ
+ tags:
+ type: array
+ items:
+ type: string
+ example:
+ - vip
+ "/api/v3/admin/exports":
get:
- summary: List prices
+ summary: List exports
tags:
- - Pricing
+ - Exports
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`.
-
+ Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).
- **Required scope:** `read_products` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18154,14 +7128,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: prices } = await client.prices.list({
- price_list_id_eq: 'pl_xxx',
- currency_eq: 'USD',
- expand: ['variant'],
- })
+ const { data: exports } = await client.exports.list()
- lang: bash
label: Spree CLI
- source: spree api get /prices -d '{"price_list_id_eq":"pl_xxx","currency_eq":"USD","expand":["variant"]}'
+ source: spree api get /exports
parameters:
- name: x-spree-api-key
in: header
@@ -18173,126 +7143,55 @@ paths:
required: true
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: q[price_list_id_eq]
- in: query
- required: false
- schema:
- type: string
- - name: q[price_list_id_null]
- in: query
- required: false
- schema:
- type: boolean
- - name: q[currency_eq]
- in: query
- required: false
- schema:
- type: string
- - name: q[variant_id_eq]
- in: query
- required: false
- schema:
- type: string
- - 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
responses:
'200':
- description: prices found
+ description: exports found
content:
application/json:
example:
data:
- - id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- variant_id: variant_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- - id: price_gbHJdmfrXB
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- variant_id: variant_gbHJdmfrXB
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- - id: price_EfhxLZ9ck8
- amount: '5.0'
- amount_in_cents: 500
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$5.00"
- display_compare_at_amount:
- price_list_id: pl_UkLWZg9DAJ
- variant_id: variant_gbHJdmfrXB
+ - id: exp_UkLWZg9DAJ
+ number: EF1001
+ format: csv
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ type: products
+ user_id: adm_UkLWZg9DAJ
+ done: false
+ store_id: store_UkLWZg9DAJ
+ seller_id:
+ seller_name:
+ filename:
+ byte_size:
+ download_url:
meta:
page: 1
limit: 25
- count: 3
+ count: 1
pages: 1
from: 1
- to: 3
- in: 3
+ to: 1
+ in: 1
previous:
next:
- 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
+ summary: Create an export
tags:
- - Pricing
+ - Exports
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`.
+ Queues a CSV export. The `type` selects the dataset; `search_params` is an
+ optional Ransack query (same shape used by the `q[...]` params on list endpoints)
+ that filters which records are exported. Pass `record_selection: "all"` to
+ clear the filter server-side and export everything in scope.
+
+ Generation is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,
+ then redirect the browser to `download_url` to fetch the file.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18304,14 +7203,13 @@ paths:
secretKey: 'sk_xxx',
})
- const price = await client.prices.create({
- variant_id: 'variant_xxx',
- currency: 'USD',
- amount: '19.99',
+ const exp = await client.exports.create({
+ type: 'Spree::Exports::Products',
+ search_params: { name_cont: 'shirt' },
})
- lang: bash
label: Spree CLI
- source: spree api post /prices -d '{"variant_id":"variant_xxx","currency":"USD","amount":"19.99"}'
+ source: spree api post /exports -d '{"type":"Spree::Exports::Products","search_params":{"name_cont":"shirt"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -18325,53 +7223,76 @@ paths:
type: string
responses:
'201':
- description: price created
+ description: export queued
content:
application/json:
- schema:
- "$ref": "#/components/schemas/Price"
+ example:
+ id: exp_gbHJdmfrXB
+ number: EF1002
+ format: csv
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: products
+ user_id: adm_UkLWZg9DAJ
+ done: false
+ store_id: store_UkLWZg9DAJ
+ seller_id:
+ seller_name:
+ filename:
+ byte_size:
+ download_url:
requestBody:
content:
application/json:
schema:
type: object
required:
- - variant_id
- - currency
+ - type
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:
type: string
- nullable: true
- example: '24.99'
- price_list_id:
+ enum:
+ - products
+ - orders
+ - customers
+ - product_translations
+ - gift_cards
+ - coupon_codes
+ - newsletter_subscribers
+ example: products
+ record_selection:
type: string
- nullable: true
- example: pl_aBc123
- "/api/v3/admin/prices/{id}":
- parameters:
- - name: id
- in: path
- required: true
- schema:
- type: string
+ enum:
+ - filtered
+ - all
+ description: Set to "all" to ignore search_params and export everything
+ in scope.
+ example: filtered
+ search_params:
+ type: object
+ description: Ransack query hash. Same predicates accepted by the
+ list endpoint.
+ example:
+ name_cont: shirt
+ 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.
+ example: https://admin.example.com/store_abc/exports
+ "/api/v3/admin/exports/{id}":
get:
- summary: Get a price
+ summary: Show an export
tags:
- - Pricing
+ - Exports
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_products` (for API-key authentication)."
+ description: |-
+ Returns export status. While `done` is `false`, the SPA continues polling.
+
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18383,10 +7304,10 @@ paths:
secretKey: 'sk_xxx',
})
- const price = await client.prices.get('price_xxx')
+ const exp = await client.exports.get('exp_xxx')
- lang: bash
label: Spree CLI
- source: spree api get /prices/{id}
+ source: spree api get /exports/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -18398,27 +7319,42 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: price found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Price"
- '404':
- description: price not found
+ description: export found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a price
+ example:
+ id: exp_UkLWZg9DAJ
+ number: EF1001
+ format: csv
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: products
+ user_id: adm_UkLWZg9DAJ
+ done: false
+ store_id: store_UkLWZg9DAJ
+ seller_id:
+ seller_name:
+ filename:
+ byte_size:
+ download_url:
+ delete:
+ summary: Delete an export
tags:
- - Pricing
+ - Exports
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_products` (for API-key authentication)."
+ description: |-
+ Removes the export and purges its attachment.
+
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18430,12 +7366,10 @@ paths:
secretKey: 'sk_xxx',
})
- const price = await client.prices.update('price_xxx', {
- amount: '12.34',
- })
+ await client.exports.delete('exp_xxx')
- lang: bash
label: Spree CLI
- source: spree api patch /prices/{id} -d '{"amount":"12.34"}'
+ source: spree api delete /exports/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -18447,36 +7381,26 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ 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
+ '204':
+ description: export deleted
+ "/api/v3/admin/exports/{id}/download":
+ get:
+ summary: Download an export
tags:
- - Pricing
+ - Exports
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes the price (acts_as_paranoid).
+ 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.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18488,10 +7412,21 @@ paths:
secretKey: 'sk_xxx',
})
- await client.prices.delete('price_xxx')
+ // Fetch with the Bearer token, then drive the browser download:
+ const res = await fetch(exp.download_url, {
+ headers: { Authorization: `Bearer ${token}` },
+ })
+ const blob = await res.blob()
+ const url = URL.createObjectURL(blob)
+ const a = Object.assign(document.createElement('a'), {
+ href: url,
+ download: exp.filename,
+ })
+ a.click()
+ URL.revokeObjectURL(url)
- lang: bash
label: Spree CLI
- source: spree api delete /prices/{id}
+ source: spree api get /exports/{id}/download
parameters:
- name: x-spree-api-key
in: header
@@ -18503,31 +7438,32 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
- '204':
- description: price deleted
- "/api/v3/admin/prices/bulk_upsert":
- post:
- summary: Bulk-upsert prices
+ '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:
- - Pricing
+ - Fulfillments
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 shipments for an order.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `read_fulfillments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18539,25 +7475,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: fulfillments } = await client.orders.fulfillments.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}/fulfillments
parameters:
- name: x-spree-api-key
in: header
@@ -18567,74 +7488,108 @@ 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: 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: prices upserted
- content:
- application/json:
- schema:
- type: object
- properties:
- price_count:
- type: integer
- '422':
- description: missing prices key
+ description: fulfillments found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - prices
- properties:
- prices:
- type: array
+ example:
+ data:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
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
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '100.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ documents: []
+ labels: []
+ provider_generates_labels: false
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create a fulfillment
tags:
- - Pricing
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes each price in `ids`. Returns the count actually destroyed.
+ 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. 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).
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_fulfillments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -18646,12 +7601,16 @@ paths:
secretKey: 'sk_xxx',
})
- const { price_count } = await client.prices.bulkDestroy({
- ids: ['price_xxx', 'price_yyy'],
+ const fulfillment = await client.orders.fulfillments.create('or_UkLWZg9DAJ', {
+ stock_location_id: 'sloc_UkLWZg9DAJ',
+ tracking: 'INPOST-12345',
+ delivery_method_id: 'dm_UkLWZg9DAJ',
+ status: 'shipped',
+ items: [{ item_id: 'li_UkLWZg9DAJ', quantity: 1 }],
})
- lang: bash
label: Spree CLI
- source: spree api delete /prices/bulk_destroy -d '{"ids":["price_xxx","price_yyy"]}'
+ source: spree api post /orders/{order_id}/fulfillments -d '{"stock_location_id":"sloc_UkLWZg9DAJ","tracking":"INPOST-12345","delivery_method_id":"dm_UkLWZg9DAJ","status":"shipped","items":[{"item_id":"li_UkLWZg9DAJ","quantity":1}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -18661,47 +7620,162 @@ 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
responses:
- '200':
- description: prices deleted
+ '201':
+ description: fulfillment created
content:
application/json:
- schema:
- type: object
- properties:
- price_count:
- type: integer
+ example:
+ id: ful_gbHJdmfrXB
+ number: R1001-F1
+ tracking: INPOST-12345
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_EfhxLZ9ck8
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: fulfilled
+ fulfillment_type: shipping
+ fulfilled_at: '2026-01-15T12:00:00.000Z'
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_gbHJdmfrXB
+ tracking_number: INPOST-12345
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ documents: []
+ labels: []
+ provider_generates_labels: false
+ '422':
+ description: order not completed
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: Fulfillments can only be created manually on completed
+ orders
requestBody:
content:
application/json:
schema:
type: object
required:
- - ids
+ - stock_location_id
properties:
- ids:
+ stock_location_id:
+ type: string
+ description: Stock location the fulfillment ships from
+ tracking:
+ type: string
+ example: INPOST-12345
+ 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
+ example: '7.42'
+ 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: string
- "/api/v3/admin/product_types":
+ type: object
+ required:
+ - item_id
+ - quantity
+ properties:
+ item_id:
+ type: string
+ description: Line item ID
+ quantity:
+ type: integer
+ example: 1
+ metadata:
+ type: object
+ additionalProperties: true
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}":
get:
- summary: List product types
+ summary: Show a shipment
tags:
- - Product Types
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a paginated list of product types.
+ Returns details of a specific shipment.
- A product type is a back-office template: it seeds option types and
- categories onto products created with it, and defines which custom
- fields those products' forms show. It is not exposed on the Store API.
+ **Required scope:** `read_fulfillments` (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',
+ })
- **Required scope:** `read_products` (for API-key authentication).
+ const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /orders/{order_id}/fulfillments/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -18714,58 +7788,117 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- - name: page
+ - 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: Page number
+ 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: 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., number,status,tracking,cost).
+ id is always included.
schema:
- type: integer
+ type: string
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
+ description: shipment found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a product type
+ example:
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '100.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ documents: []
+ labels: []
+ provider_generates_labels: false
+ patch:
+ summary: Update a shipment
tags:
- - Product Types
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a product type.
+ Updates a fulfillment (tracking, delivery rate).
- `option_type_ids` and `category_ids` seed products created with this
- type. `custom_field_definitions` is a replace-set of the definitions the
- product form renders, in `sort_order`. `required` is advisory — the
- dashboard marks the field, but a blank value is never rejected.
+ **Required scope:** `write_fulfillments` (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',
+ })
- **Required scope:** `write_products` (for API-key authentication).
+ const fulfillment = await client.orders.fulfillments.update('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {
+ tracking: '1Z999AA10123456784',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{id} -d '{"tracking":"1Z999AA10123456784"}'
parameters:
- name: x-spree-api-key
in: header
@@ -18778,78 +7911,116 @@ 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: Fulfillment ID
+ schema:
+ type: string
responses:
- '201':
- description: product type created
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ProductType"
- '422':
- description: unprocessable entity
+ '200':
+ description: shipment updated
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: 1Z999AA10123456784
+ tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: 1Z999AA10123456784
+ carrier: ups
+ carrier_name: UPS
+ service:
+ status: pending
+ tracking_url: https://www.ups.com/track?tracknum=1Z999AA10123456784
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '100.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ documents: []
+ labels: []
+ provider_generates_labels: false
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
+ tracking:
type: string
- example: Hoodie
- delivery_profile_id:
+ example: 1Z999AA10123456784
+ description: Carrier tracking number, or a full https:// tracking
+ link served back as tracking_url unchanged
+ selected_delivery_rate_id:
type: string
- nullable: true
- example: fp_86Rf07xd4z
- 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
+ description: Delivery rate ID (dr_...) to select
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":
+ patch:
+ summary: Fulfill a fulfillment
tags:
- - Product Types
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single product type with its option types, categories and custom fields.
+ Marks a fulfillment as fulfilled.
- **Required scope:** `read_products` (for API-key authentication).
+ **Required scope:** `write_fulfillments` (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 fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{
+ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -18862,34 +8033,106 @@ 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: Fulfillment ID
+ schema:
+ type: string
responses:
'200':
- description: product type found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ProductType"
- '404':
- description: product type not found
+ description: fulfillment fulfilled
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: fulfilled
+ fulfillment_type: shipping
+ fulfilled_at: '2026-01-15T12:00:00.000Z'
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '100.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ documents: []
+ labels: []
+ provider_generates_labels: false
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":
patch:
- summary: Update a product type
+ summary: Mark a fulfillment delivered
tags:
- - Product Types
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a product type.
+ Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.
- Changes never modify products that already carry the type — use
- `apply_to_products` to backfill those.
+ **Required scope:** `write_fulfillments` (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',
+ })
- **Required scope:** `write_products` (for API-key authentication).
+ const fulfillment = await client.orders.fulfillments.markDelivered(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ { delivered_at: '2026-08-11T09:30:00Z' },
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{id}/mark_delivered
+ -d '{"delivered_at":"2026-08-11T09:30:00Z"}'
parameters:
- name: x-spree-api-key
in: header
@@ -18902,55 +8145,124 @@ 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: Fulfillment ID
+ schema:
+ type: string
responses:
'200':
- description: product type updated
+ description: fulfillment delivered
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ProductType"
+ example:
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: delivered
+ fulfillment_type: shipping
+ fulfilled_at: '2026-01-15T12:00:00.000Z'
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: delivered
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '100.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ documents: []
+ labels: []
+ provider_generates_labels: false
+ '422':
+ description: fulfillment has not shipped
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: Only a fulfilled shipment can be marked delivered
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Premium T-Shirt
- delivery_profile_id:
+ delivered_at:
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
+ 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:
- - Product Types
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Deletes a product type. Types still used by products cannot be deleted.
+ Cancels a fulfillment.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_fulfillments` (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 fulfillment = await client.orders.fulfillments.cancel('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{id}/cancel -d '{
+ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -18963,34 +8275,112 @@ 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: Fulfillment ID
+ 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
+ '200':
+ description: fulfillment canceled
+ content:
+ application/json:
+ example:
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: canceled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '100.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_UkLWZg9DAJ
+ documents: []
+ labels: []
+ provider_generates_labels: false
+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
+ patch:
+ summary: Split a fulfillment
tags:
- - Product Types
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Backfills the type's option types and categories onto the products that
- already carry it. Additive and idempotent — nothing is removed, and
- re-running is safe.
+ Transfers items from this shipment to a new shipment at a different stock location.
- Runs in the background; the response reports how many products the type
- currently has.
+ **Required scope:** `write_fulfillments` (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',
+ })
- **Required scope:** `write_products` (for API-key authentication).
+ // Splitting moves a quantity of one variant into its own fulfillment, so the
+ // response is the order's full set: the source is re-shaped, and disappears
+ // when the split drains it. Pass stock_location_id to send the new
+ // fulfillment out from a different origin.
+ const { data: fulfillments } = await client.orders.fulfillments.split(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ {
+ variant_id: 'variant_86Rf07xd4z',
+ quantity: 1,
+ },
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{id}/split -d '{"variant_id":"variant_86Rf07xd4z","quantity":1}'
parameters:
- name: x-spree-api-key
in: header
@@ -19003,28 +8393,96 @@ 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: Fulfillment ID
+ schema:
+ type: string
responses:
- '202':
- description: backfill accepted
+ '200':
+ description: fulfillment split
content:
application/json:
- schema:
- type: object
- properties:
- products_count:
- type: integer
- "/api/v3/admin/products/{product_id}/custom_fields":
+ example:
+ data:
+ - id: ful_gbHJdmfrXB
+ number: R1001-F1
+ tracking:
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_EfhxLZ9ck8
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries: []
+ metadata: {}
+ adjustment_total: '0.0'
+ pre_tax_amount: '0.0'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_id: or_UkLWZg9DAJ
+ stock_location_id: sloc_gbHJdmfrXB
+ documents: []
+ labels: []
+ provider_generates_labels: false
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - variant_id
+ - quantity
+ properties:
+ variant_id:
+ type: string
+ description: Variant ID
+ quantity:
+ type: integer
+ example: 1
+ stock_location_id:
+ type: string
+ description: Target stock location ID
+ "/api/v3/admin/gift_card_batches":
get:
- summary: List product custom fields
+ summary: List gift card batches
tags:
- - Products
+ - Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the product's custom field values.
+ Returns the gift card batches issued by the current store. Each batch
+ groups the cards generated together for a campaign or bulk-issuance
+ — the cards themselves live under `/admin/gift_cards` and reference
+ the batch via `gift_card_batch_id`.
- **Required scope:** `read_products` (for API-key authentication).
+
+ **Required scope:** `read_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19036,10 +8494,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: customFields } = await client.products.customFields.list('prod_UkLWZg9DAJ')
+ const { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
- source: spree api get /products/{product_id}/custom_fields
+ source: spree api get /gift_card_batches -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -19049,41 +8507,87 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: product_id
- in: path
- required: true
+ - name: page
+ in: query
+ required: false
+ description: Page number
schema:
- type: string
- - name: expand
+ type: integer
+ - name: limit
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: Records per page
+ schema:
+ type: integer
+ - name: q[prefix_cont]
+ in: query
+ required: false
+ description: Filter by prefix (contains)
schema:
type: string
- - name: fields
+ - name: sort
in: query
required: false
- description: Comma-separated list of fields to include (e.g., key,value,namespace).
- id is always included.
+ description: Sort by field. Prefix with `-` for descending.
schema:
type: string
responses:
'200':
- description: custom fields found
+ description: gift card batches found
+ content:
+ application/json:
+ example:
+ data:
+ - id: gcb_UkLWZg9DAJ
+ codes_count: 2
+ currency: USD
+ prefix: WELCOME
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '50.0'
+ expires_at:
+ created_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/GiftCardBatch"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Create a product custom field
+ summary: Create a gift card batch
tags:
- - Products
+ - Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
- Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.
+ Issues a batch of gift cards in a single call. The server generates
+ `codes_count` cards inline for small batches (configurable via
+ `Spree.config.gift_card_batch_web_limit`, default 500) or enqueues
+ a background job for larger ones. Each card's code is the batch
+ `prefix` followed by random hex.
- **Required scope:** `write_products` (for API-key authentication).
+
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19094,14 +8598,17 @@ paths:
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
-
- const customField = await client.products.customFields.create('prod_UkLWZg9DAJ', {
- custom_field_definition_id: 'cfdef_AbC123XyZ',
- value: 'wool',
+
+ const batch = await client.giftCardBatches.create({
+ prefix: 'WELCOME',
+ amount: '25.00',
+ currency: 'USD',
+ codes_count: 100,
+ expires_at: '2030-12-31',
})
- 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 /gift_card_batches -d '{"prefix":"WELCOME","amount":"25.00","currency":"USD","codes_count":100,"expires_at":"2030-12-31"}'
parameters:
- name: x-spree-api-key
in: header
@@ -19113,39 +8620,85 @@ paths:
required: true
schema:
type: string
- - name: product_id
- in: path
- required: true
- schema:
- type: string
responses:
'201':
- description: custom field created
+ description: gift card batch created
+ content:
+ application/json:
+ example:
+ id: gcb_gbHJdmfrXB
+ codes_count: 5
+ currency: USD
+ prefix: NEWCAMP
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '25.0'
+ expires_at: '2030-12-31'
+ created_by_id: adm_UkLWZg9DAJ
+ schema:
+ "$ref": "#/components/schemas/GiftCardBatch"
'422':
- description: duplicate definition for the same product
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Prefix can't be blank
+ details:
+ prefix:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
required:
- - custom_field_definition_id
- - value
+ - prefix
+ - amount
+ - codes_count
properties:
- custom_field_definition_id:
+ prefix:
type: string
- description: Prefixed `cfdef_…` id
- value:
- description: Value matching the definition's `field_type`
- "/api/v3/admin/products/{product_id}/custom_fields/{id}":
+ example: WELCOME
+ description: Lowercased and prepended to every generated code.
+ amount:
+ type: string
+ example: '25.00'
+ description: Decimal amount per card, greater than zero.
+ currency:
+ type: string
+ example: USD
+ description: ISO 4217 currency code. Defaults to the store currency.
+ codes_count:
+ type: integer
+ example: 100
+ description: Number of cards to generate. Capped at `gift_card_batch_limit`.
+ expires_at:
+ type: string
+ example: '2030-12-31'
+ 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: Show a product custom field
+ summary: Get a gift card batch
tags:
- - Products
+ - Gift Cards
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_products` (for API-key authentication)."
+ description: |-
+ Returns a single batch.
+
+ **Required scope:** `read_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19157,10 +8710,10 @@ paths:
secretKey: 'sk_xxx',
})
- const customField = await client.products.customFields.get('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
+ const batch = await client.giftCardBatches.get('gcb_K3zr8x')
- lang: bash
label: Spree CLI
- source: spree api get /products/{product_id}/custom_fields/{id}
+ source: spree api get /gift_card_batches/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -19172,44 +8725,48 @@ paths:
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
- patch:
- summary: Update a product custom field
+ description: gift card batch found
+ content:
+ application/json:
+ example:
+ id: gcb_UkLWZg9DAJ
+ codes_count: 2
+ currency: USD
+ prefix: WELCOME
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '50.0'
+ expires_at:
+ created_by_id:
+ schema:
+ "$ref": "#/components/schemas/GiftCardBatch"
+ '404':
+ description: gift card batch not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Gift card batch not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/gift_cards":
+ get:
+ summary: List gift cards
tags:
- - Products
+ - Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
- Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.
+ Returns the gift cards issued by the current store. Filter by
+ `q[code_cont]` for code search, `q[user_id_eq]` for cards issued
+ to a specific customer, or `q[status_eq]` for status filtering.
- **Required scope:** `write_products` (for API-key authentication).
+
+ **Required scope:** `read_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19221,12 +8778,14 @@ paths:
secretKey: 'sk_xxx',
})
- const customField = await client.products.customFields.update('prod_UkLWZg9DAJ', 'cf_AbC123XyZ', {
- value: 'cotton',
+ const { data: giftCards } = await client.giftCards.list({
+ page: 1,
+ limit: 25,
+ expand: ['customer', 'created_by'],
})
- lang: bash
label: Spree CLI
- source: spree api patch /products/{product_id}/custom_fields/{id} -d '{"value":"cotton"}'
+ source: spree api get /gift_cards -d '{"page":1,"limit":25,"expand":["customer","created_by"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -19236,39 +8795,137 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: product_id
- in: path
- required: true
+ - 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[code_cont]
+ in: query
+ required: false
+ description: Filter by gift card code (contains)
schema:
type: string
- - name: id
- in: path
- required: true
+ - name: q[status_eq]
+ in: query
+ required: false
+ description: Filter by status (active, redeemed, partially_redeemed, canceled)
+ schema:
+ type: string
+ - 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
responses:
'200':
- description: custom field updated
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - value
- properties:
- value:
- description: New value
- delete:
- summary: Delete a product custom field
+ description: gift cards found
+ content:
+ application/json:
+ example:
+ data:
+ - id: gc_UkLWZg9DAJ
+ code: C5BC700C4EF16A06
+ status: active
+ currency: USD
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.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:
+ - id: gc_gbHJdmfrXB
+ code: 3BECEA5A776AD146
+ status: active
+ currency: USD
+ amount: '25.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '25.0'
+ display_amount: "$25.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$25.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:
+ 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/GiftCard"
+ 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 gift card
tags:
- - Products
+ - Gift Cards
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_products` (for API-key authentication)."
+ description: |-
+ Issues a gift card scoped to the current store. The code is
+ auto-generated when omitted. `currency` defaults to the store's
+ configured currency. Pass `user_id` (prefixed ID) to attach the
+ card to a specific customer.
+
+
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19280,46 +8937,15 @@ paths:
secretKey: 'sk_xxx',
})
- await client.products.customFields.delete('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
+ const giftCard = await client.giftCards.create({
+ amount: '25.00',
+ currency: 'USD',
+ expires_at: '2030-12-31',
+ user_id: 'cus_UkLWZg9DAJ',
+ })
- lang: bash
label: Spree CLI
- source: spree api delete /products/{product_id}/custom_fields/{id}
- 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.
-
- **Required scope:** `read_products` (for API-key authentication).
+ source: spree api post /gift_cards -d '{"amount":"25.00","currency":"USD","expires_at":"2030-12-31","user_id":"cus_UkLWZg9DAJ"}'
parameters:
- name: x-spree-api-key
in: header
@@ -19331,26 +8957,96 @@ paths:
required: true
schema:
type: string
- - name: product_id
- in: path
- required: true
- schema:
- type: string
responses:
- '200':
- description: translations found
- "/api/v3/admin/products":
+ '201':
+ description: gift card created
+ content:
+ application/json:
+ example:
+ id: gc_EfhxLZ9ck8
+ code: A68048412201A26B
+ status: active
+ currency: USD
+ amount: '25.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '25.0'
+ display_amount: "$25.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$25.00"
+ expires_at: '2030-12-31'
+ 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: adm_UkLWZg9DAJ
+ schema:
+ "$ref": "#/components/schemas/GiftCard"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Amount must be greater than 0
+ details:
+ amount:
+ - must be greater than 0
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - amount
+ properties:
+ amount:
+ type: string
+ example: '25.00'
+ description: Decimal amount, greater than zero.
+ currency:
+ type: string
+ example: USD
+ description: ISO 4217 currency code. Defaults to the store currency.
+ code:
+ type: string
+ example: WELCOME50
+ description: Optional caller-supplied code. Auto-generated when
+ omitted.
+ expires_at:
+ type: string
+ example: '2030-12-31'
+ description: ISO 8601 date.
+ nullable: true
+ user_id:
+ type: string
+ example: cus_UkLWZg9DAJ
+ 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: List products
+ summary: Get a gift card
tags:
- - Products
+ - Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a paginated list of products for the current store.
+ Returns a single gift card.
- **Required scope:** `read_products` (for API-key authentication).
+ **Required scope:** `read_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19362,15 +9058,12 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: products } = await client.products.list({
- name_cont: 'shirt',
- status_eq: 'active',
- sort: '-created_at',
- limit: 25,
+ const giftCard = await client.giftCards.get('gc_K3zr8x', {
+ expand: ['customer', 'created_by', 'orders'],
})
- lang: bash
label: Spree CLI
- source: spree api get /products -d '{"name_cont":"shirt","status_eq":"active","sort":"-created_at","limit":25}'
+ source: spree api get /gift_cards/{id} -d '{"expand":["customer","created_by","orders"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -19380,91 +9073,64 @@ 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: 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[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: q[status_eq]
- in: query
- required: false
- description: Filter by status
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
- description: products found
+ description: gift card 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
+ example:
+ id: gc_UkLWZg9DAJ
+ code: 06BEABE5C26AA7E5
+ status: active
+ currency: USD
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.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:
+ schema:
+ "$ref": "#/components/schemas/GiftCard"
+ '404':
+ description: gift card not found
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Gift card not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a product
+ patch:
+ summary: Update a gift card
tags:
- - Products
+ - Gift Cards
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.
+ Updates an active gift card's editable attributes. Redeemed or
+ partially-redeemed cards cannot be edited.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19476,40 +9142,12 @@ 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: [
- {
- 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 }],
- },
- ],
+ const giftCard = await client.giftCards.update('gc_K3zr8x', {
+ amount: '75.00',
})
- 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 patch /gift_cards/{id} -d '{"amount":"75.00"}'
parameters:
- name: x-spree-api-key
in: header
@@ -19519,154 +9157,65 @@ paths:
- 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
+ '200':
+ description: gift card updated
content:
application/json:
+ example:
+ id: gc_UkLWZg9DAJ
+ code: E34E66F15D82A3CD
+ status: active
+ currency: USD
+ amount: '75.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '75.0'
+ display_amount: "$75.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$75.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:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/GiftCard"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Premium T-Shirt
- description:
- type: string
- slug:
+ amount:
type: string
- status:
+ example: '75.00'
+ expires_at:
type: string
- enum:
- - draft
- - active
- - archived
- tax_category_id:
+ example: '2031-12-31'
+ nullable: true
+ user_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 product
+ example: cus_UkLWZg9DAJ
+ nullable: true
+ delete:
+ summary: Delete a gift card
tags:
- - Products
+ - Gift Cards
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single product by ID.
+ Deletes an unused gift card. Cards that have been redeemed or
+ partially redeemed cannot be deleted and return 422.
- **Required scope:** `read_products` (for API-key authentication).
+
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -19678,12 +9227,10 @@ paths:
secretKey: 'sk_xxx',
})
- const product = await client.products.get('prod_86Rf07xd4z', {
- expand: ['variants', 'option_types'],
- })
+ await client.giftCards.delete('gc_K3zr8x')
- lang: bash
label: Spree CLI
- source: spree api get /products/{id} -d '{"expand":["variants","option_types"]}'
+ source: spree api delete /gift_cards/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -19693,72 +9240,223 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: id
- in: path
+ responses:
+ '204':
+ description: gift card deleted
+ '422':
+ description: redeemed gift card cannot be deleted
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Gift card cannot be deleted
+ "/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.
+
+ **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
- 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.
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: product found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Product"
- '404':
- description: product not found
+ description: imports found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a product
+ 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:
+ owner_type: store
+ owner_id: store_UkLWZg9DAJ
+ user_id: adm_UkLWZg9DAJ
+ processing_errors:
+ preferred_delimiter: ","
+ seller_name:
+ original_filename: products_import.csv
+ original_byte_size: 3627
+ original_file_url: "/api/v3/admin/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: 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: 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:
+ post:
+ summary: Create an import
tags:
- - Products
+ - Imports
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a product. Only provided fields are updated.
+ Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`
+ and pass the returned `signed_id` as `attachment`. On success the import is in the
+ `mapping` state and the response carries the mapping payload: `schema_fields`
+ (the canonical columns for the type), `csv_headers`, a `sample_row`, and the
+ auto-assigned `mappings`.
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Adjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`
+ to start processing. Poll `GET /admin/imports/{id}` while `status` is
+ `completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- 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 /products/{id} -d '{"name":"Updated Name","status":"active","tags":["eco","sale"]}'
+ **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
@@ -19768,172 +9466,454 @@ 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
+ '201':
+ description: import created in mapping state
content:
application/json:
- schema:
- "$ref": "#/components/schemas/Product"
+ example:
+ id: imp_gbHJdmfrXB
+ number: IM1002
+ rows_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: products
+ status: mapping
+ store_id: store_UkLWZg9DAJ
+ seller_id:
+ owner_type: store
+ owner_id: store_UkLWZg9DAJ
+ user_id: adm_UkLWZg9DAJ
+ processing_errors:
+ preferred_delimiter: ","
+ seller_name:
+ original_filename: import.csv
+ original_byte_size: 44
+ original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/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: 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: 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:
+ - slug
+ - sku
+ - name
+ - price
+ sample_row:
+ slug: widget
+ sku: W-1
+ name: Widget
+ price: '10.00'
+ mappings:
+ - id: immap_UkLWZg9DAJ
+ schema_field: slug
+ file_column: slug
+ required: true
+ - id: immap_gbHJdmfrXB
+ schema_field: sku
+ file_column: sku
+ required: true
+ - id: immap_EfhxLZ9ck8
+ schema_field: name
+ file_column: name
+ required: true
+ - id: immap_VqXmZF31wY
+ schema_field: price
+ file_column: price
+ required: true
+ - id: immap_uw2YK1rnl0
+ schema_field: status
+ file_column:
+ required: false
+ - id: immap_OIJLhNcSbf
+ schema_field: description
+ file_column:
+ required: false
+ - id: immap_AXs1igzRC6
+ schema_field: meta_title
+ file_column:
+ required: false
+ - id: immap_p6klVeMgbn
+ schema_field: meta_description
+ file_column:
+ required: false
+ - id: immap_nJqfPa3Cpe
+ schema_field: meta_keywords
+ file_column:
+ required: false
+ - id: immap_98FqgRua4h
+ schema_field: tags
+ file_column:
+ required: false
+ - id: immap_xhoCpeNMWu
+ schema_field: compare_at_price
+ file_column:
+ required: false
+ - id: immap_vEmzDoNU0H
+ schema_field: currency
+ file_column:
+ required: false
+ - id: immap_2KY5XM6frI
+ schema_field: width
+ file_column:
+ required: false
+ - id: immap_HOVtlDrOmL
+ schema_field: height
+ file_column:
+ required: false
+ - id: immap_ed6l8wVqSM
+ schema_field: depth
+ file_column:
+ required: false
+ - id: immap_s18jaGonyx
+ schema_field: dimensions_unit
+ file_column:
+ required: false
+ - id: immap_GZUcnUYI5A
+ schema_field: weight
+ file_column:
+ required: false
+ - id: immap_ROeNhrwyV9
+ schema_field: weight_unit
+ file_column:
+ required: false
+ - id: immap_L3pHOn63Vw
+ schema_field: available_on
+ file_column:
+ required: false
+ - id: immap_PQNMcnNFWw
+ schema_field: discontinue_on
+ file_column:
+ required: false
+ - id: immap_C9SrJgpzQ4
+ schema_field: track_inventory
+ file_column:
+ required: false
+ - id: immap_YHETxCGlb0
+ schema_field: inventory_count
+ file_column:
+ required: false
+ - id: immap_5OQZnCRf8J
+ schema_field: inventory_backorderable
+ file_column:
+ required: false
+ - id: immap_F0GX8NaP3Y
+ schema_field: tax_category
+ file_column:
+ required: false
+ - id: immap_kOKT9MVfb0
+ schema_field: product_type
+ file_column:
+ required: false
+ - id: immap_3uWpPTcf5W
+ schema_field: hs_code
+ file_column:
+ required: false
+ - id: immap_D6Psx31WaT
+ schema_field: country_of_origin
+ file_column:
+ required: false
+ - id: immap_msx3nOJap6
+ schema_field: customs_description
+ file_column:
+ required: false
+ - id: immap_5CQZnCRf8J
+ schema_field: image1_src
+ file_column:
+ required: false
+ - id: immap_M2nyloHRUQ
+ schema_field: image2_src
+ file_column:
+ required: false
+ - id: immap_prklVeMgbn
+ schema_field: image3_src
+ file_column:
+ required: false
+ - id: immap_so8jaGonyx
+ schema_field: option1_name
+ file_column:
+ required: false
+ - id: immap_rsClYtECFI
+ schema_field: option1_value
+ file_column:
+ required: false
+ - id: immap_8DR0I7fEbw
+ schema_field: option2_name
+ file_column:
+ required: false
+ - id: immap_aAtNvLSUAr
+ schema_field: option2_value
+ file_column:
+ required: false
+ - id: immap_QiA48cIW7A
+ schema_field: option3_name
+ file_column:
+ required: false
+ - id: immap_QDA48cIW7A
+ schema_field: option3_value
+ file_column:
+ required: false
+ - id: immap_8cR0I7fEbw
+ schema_field: category1
+ file_column:
+ required: false
+ - id: immap_oqlrKdXjaP
+ schema_field: category2
+ file_column:
+ required: false
+ - id: immap_48Olu6p4zZ
+ schema_field: category3
+ file_column:
+ required: false
'422':
- description: validation error
+ description: unknown import type
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ error:
+ code: validation_error
+ message: Type can't be blank
+ details:
+ type:
+ - can't be blank
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - type
+ - attachment
properties:
- name:
- type: string
- example: Premium T-Shirt
- description:
+ type:
type: string
- slug:
+ enum:
+ - products
+ - customers
+ - product_translations
+ example: products
+ attachment:
type: string
- status:
+ description: ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads.
+ example: eyJfcmFpbHMiOnsiZGF0YSI6MX0=--signed
+ preferred_delimiter:
type: string
enum:
- - draft
- - active
- - archived
- tax_category_id:
+ - ","
+ - ";"
+ - "|"
+ - "\t"
+ description: CSV column separator. Defaults to a comma.
+ example: ","
+ results_url:
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 product
+ 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.
+ example: https://admin.example.com/store_abc/settings/imports
+ "/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.
+
+ **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:
- - Products
+ - Imports
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes a product.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ 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.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ **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`.
- await client.products.delete('prod_86Rf07xd4z')
- - lang: bash
- label: Spree CLI
- source: spree api delete /products/{id}
+ **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
@@ -19943,56 +9923,174 @@ 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
+ '200':
+ description: import found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/products/bulk_status_update":
- post:
- summary: Bulk-update product status
+ example:
+ 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:
+ owner_type: store
+ owner_id: store_UkLWZg9DAJ
+ user_id: adm_UkLWZg9DAJ
+ processing_errors:
+ preferred_delimiter: ","
+ seller_name:
+ original_filename: products_import.csv
+ original_byte_size: 3627
+ original_file_url: "/api/v3/admin/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: 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: 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: []
+ delete:
+ summary: Delete an import
tags:
- - Products
+ - Imports
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.
-
-
- **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',
- })
+ Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.
- const result = await client.products.bulkStatusUpdate({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- status: 'archived',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /products/bulk_status_update -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"status":"archived"}'
+ **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
@@ -20004,78 +10102,26 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ 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
- 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
+ '204':
+ description: import deleted
+ "/api/v3/admin/imports/{id}/download":
+ get:
+ summary: Download the originally uploaded file
tags:
- - Products
+ - Imports
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).
- 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',
- })
+ 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.
- const result = await client.products.bulkAddToCategories({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- category_ids: ['cat_AbC123XyZ'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /products/bulk_add_to_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
+ **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
@@ -20087,65 +10133,36 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: products added to categories
+ description: CSV file
content:
- application/json:
+ application/json: {}
+ text/csv:
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
+ type: string
+ format: binary
+ "/api/v3/admin/imports/{id}/complete_mapping":
+ patch:
+ summary: Complete mapping and start processing
tags:
- - Products
+ - Imports
security:
- api_key: []
bearer_auth: []
description: |-
- Detaches each product in `ids` from every category in `category_ids`.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Applies the submitted column mappings, then starts row processing. Omit `mappings`
+ to accept the auto-assigned ones from the create response. Returns 422 when a
+ required schema field is left unmapped (`details.missing_required_fields`) or a
+ file column is assigned twice.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const result = await client.products.bulkRemoveFromCategories({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- category_ids: ['cat_AbC123XyZ'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /products/bulk_remove_from_categories -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"category_ids":["cat_AbC123XyZ"]}'
+ **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
@@ -20157,40 +10174,355 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: products removed from categories
+ description: mapping completed, processing queued
+ content:
+ application/json:
+ example:
+ id: imp_gbHJdmfrXB
+ number: IM1002
+ rows_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: products
+ status: completed_mapping
+ store_id: store_UkLWZg9DAJ
+ seller_id:
+ owner_type: store
+ owner_id: store_UkLWZg9DAJ
+ user_id: adm_UkLWZg9DAJ
+ processing_errors:
+ preferred_delimiter: ","
+ seller_name:
+ original_filename: products_import.csv
+ original_byte_size: 3627
+ original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/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: 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: 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:
+ - id: immap_UkLWZg9DAJ
+ schema_field: slug
+ file_column: slug
+ required: true
+ - id: immap_gbHJdmfrXB
+ schema_field: sku
+ file_column: sku
+ required: true
+ - id: immap_EfhxLZ9ck8
+ schema_field: name
+ file_column: name
+ required: true
+ - id: immap_VqXmZF31wY
+ schema_field: price
+ file_column: price
+ required: true
+ - id: immap_uw2YK1rnl0
+ schema_field: status
+ file_column: status
+ required: false
+ - id: immap_OIJLhNcSbf
+ schema_field: description
+ file_column: description
+ required: false
+ - id: immap_AXs1igzRC6
+ schema_field: meta_title
+ file_column: meta_title
+ required: false
+ - id: immap_p6klVeMgbn
+ schema_field: meta_description
+ file_column: meta_description
+ required: false
+ - id: immap_nJqfPa3Cpe
+ schema_field: meta_keywords
+ file_column: meta_keywords
+ required: false
+ - id: immap_98FqgRua4h
+ schema_field: tags
+ file_column: tags
+ required: false
+ - id: immap_xhoCpeNMWu
+ schema_field: compare_at_price
+ file_column: compare_at_price
+ required: false
+ - id: immap_vEmzDoNU0H
+ schema_field: currency
+ file_column: currency
+ required: false
+ - id: immap_2KY5XM6frI
+ schema_field: width
+ file_column: width
+ required: false
+ - id: immap_HOVtlDrOmL
+ schema_field: height
+ file_column: height
+ required: false
+ - id: immap_ed6l8wVqSM
+ schema_field: depth
+ file_column: depth
+ required: false
+ - id: immap_s18jaGonyx
+ schema_field: dimensions_unit
+ file_column: dimensions_unit
+ required: false
+ - id: immap_GZUcnUYI5A
+ schema_field: weight
+ file_column: weight
+ required: false
+ - id: immap_ROeNhrwyV9
+ schema_field: weight_unit
+ file_column: weight_unit
+ required: false
+ - id: immap_L3pHOn63Vw
+ schema_field: available_on
+ file_column: available_on
+ required: false
+ - id: immap_PQNMcnNFWw
+ schema_field: discontinue_on
+ file_column: discontinue_on
+ required: false
+ - id: immap_C9SrJgpzQ4
+ schema_field: track_inventory
+ file_column: track_inventory
+ required: false
+ - id: immap_YHETxCGlb0
+ schema_field: inventory_count
+ file_column: inventory_count
+ required: false
+ - id: immap_5OQZnCRf8J
+ schema_field: inventory_backorderable
+ file_column: inventory_backorderable
+ required: false
+ - id: immap_F0GX8NaP3Y
+ schema_field: tax_category
+ file_column: tax_category
+ required: false
+ - id: immap_kOKT9MVfb0
+ schema_field: product_type
+ file_column:
+ required: false
+ - id: immap_3uWpPTcf5W
+ schema_field: hs_code
+ file_column:
+ required: false
+ - id: immap_D6Psx31WaT
+ schema_field: country_of_origin
+ file_column:
+ required: false
+ - id: immap_msx3nOJap6
+ schema_field: customs_description
+ file_column:
+ required: false
+ - id: immap_5CQZnCRf8J
+ schema_field: image1_src
+ file_column: image1_src
+ required: false
+ - id: immap_M2nyloHRUQ
+ schema_field: image2_src
+ file_column: image2_src
+ required: false
+ - id: immap_prklVeMgbn
+ schema_field: image3_src
+ file_column: image3_src
+ required: false
+ - id: immap_so8jaGonyx
+ schema_field: option1_name
+ file_column: option1_name
+ required: false
+ - id: immap_rsClYtECFI
+ schema_field: option1_value
+ file_column: option1_value
+ required: false
+ - id: immap_8DR0I7fEbw
+ schema_field: option2_name
+ file_column: option2_name
+ required: false
+ - id: immap_aAtNvLSUAr
+ schema_field: option2_value
+ file_column: option2_value
+ required: false
+ - id: immap_QiA48cIW7A
+ schema_field: option3_name
+ file_column: option3_name
+ required: false
+ - id: immap_QDA48cIW7A
+ schema_field: option3_value
+ file_column: option3_value
+ required: false
+ - id: immap_8cR0I7fEbw
+ schema_field: category1
+ file_column: category1
+ required: false
+ - id: immap_oqlrKdXjaP
+ schema_field: category2
+ file_column: category2
+ required: false
+ - id: immap_48Olu6p4zZ
+ schema_field: category3
+ file_column: category3
+ required: false
requestBody:
content:
application/json:
schema:
type: object
- required:
- - ids
- - category_ids
properties:
- ids:
- type: array
- items:
- type: string
- category_ids:
+ mappings:
type: array
+ description: 'Column assignments to apply before starting. `file_column:
+ null` unmaps a field.'
items:
- type: string
- "/api/v3/admin/products/bulk_add_to_collections":
- post:
- summary: Bulk-add products to collections
+ type: object
+ required:
+ - schema_field
+ properties:
+ schema_field:
+ type: string
+ example: slug
+ file_column:
+ type: string
+ nullable: true
+ example: Product Handle
+ "/api/v3/admin/imports/{id}/retry_failed_rows":
+ patch:
+ summary: Retry failed rows
tags:
- - Products
+ - Imports
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.
-
+ 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.
- **Required scope:** `write_products` (for API-key authentication).
+ **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
@@ -20202,47 +10534,173 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: products added to collections
+ description: retry queued
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
+ example:
+ id: imp_gbHJdmfrXB
+ number: IM1002
+ rows_count: 1
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: products
+ status: processing
+ store_id: store_UkLWZg9DAJ
+ seller_id:
+ owner_type: store
+ owner_id: store_UkLWZg9DAJ
+ user_id: adm_UkLWZg9DAJ
+ processing_errors:
+ preferred_delimiter: ","
+ seller_name:
+ original_filename: products_import.csv
+ original_byte_size: 3627
+ original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
+ completed_rows_count: 0
+ failed_rows_count: 1
+ 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: 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: 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: []
+ "/api/v3/admin/imports/{import_id}/rows":
+ get:
+ summary: List import rows
tags:
- - Products
+ - Imports
security:
- api_key: []
bearer_auth: []
description: |-
- Detaches each product in `ids` from every collection in `collection_ids`.
+ 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`.
- **Required scope:** `write_products` (for API-key authentication).
+ **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
@@ -20254,41 +10712,62 @@ paths:
required: true
schema:
type: string
+ - name: import_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: q[status_eq]
+ in: query
+ required: false
+ description: 'Filter rows by status: pending, processing, completed, failed.'
+ schema:
+ type: string
responses:
'200':
- description: products removed from collections
- 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
+ description: rows found
+ content:
+ application/json:
+ example:
+ data:
+ - id: imrow_gbHJdmfrXB
+ row_number: 2
+ status: failed
+ validation_errors: boom
+ 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:
+ "/api/v3/admin/markets":
+ get:
+ summary: List markets
tags:
- - Products
+ - Markets
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.
+ Returns the markets configured for the current store. Markets are
+ store-scoped and ordered by `position` (an `acts_as_list` column —
+ update the order via `PATCH /markets/{id}` with `position`).
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20300,13 +10779,10 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkAddToChannels({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- channel_ids: ['channel_AbC123XyZ'],
- })
+ const { data: markets } = await client.markets.list()
- 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 get /markets
parameters:
- name: x-spree-api-key
in: header
@@ -20318,47 +10794,107 @@ paths:
required: true
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ schema:
+ type: string
+ - 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
responses:
'200':
- description: products published on channels
+ description: markets found
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":
+ example:
+ data:
+ - id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: mkt_gbHJdmfrXB
+ name: EU
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: false
+ country_codes:
+ - DE
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ 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/Market"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Bulk-remove products from channels
+ summary: Create a market
tags:
- - Products
+ - Markets
security:
- api_key: []
bearer_auth: []
description: |-
- Unpublishes each product in `ids` from every channel in `channel_ids`.
+ Creates a new market for the current store.
- **Required scope:** `write_products` (for API-key authentication).
+ - `country_codes` accepts 2-letter ISO country codes (e.g. `["DE", "FR"]`);
+ the market must contain at least one country. Unknown codes are
+ silently dropped.
+ - `supported_locales` accepts an array of locale codes; the
+ `default_locale` is always implicitly included.
+ - Setting `default: true` automatically demotes the previous default
+ market in the store.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20370,13 +10906,17 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkRemoveFromChannels({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- channel_ids: ['channel_AbC123XyZ'],
+ const market = await client.markets.create({
+ name: 'Europe',
+ currency: 'EUR',
+ default_locale: 'de',
+ supported_locales: ['de', 'en', 'fr'],
+ tax_inclusive: true,
+ country_codes: ['DE', 'FR', 'IT'],
})
- 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 post /markets -d '{"name":"Europe","currency":"EUR","default_locale":"de","supported_locales":["de","en","fr"],"tax_inclusive":true,"country_codes":["DE","FR","IT"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -20389,48 +10929,113 @@ paths:
schema:
type: string
responses:
- '200':
- description: products unpublished from channels
+ '201':
+ description: market created
content:
application/json:
+ example:
+ id: mkt_EfhxLZ9ck8
+ name: France only
+ currency: EUR
+ default_locale: fr
+ tax_inclusive: true
+ default: false
+ country_codes:
+ - FR
+ supported_locales:
+ - en
+ - fr
+ tax_provider:
+ 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
- removed:
- type: integer
+ "$ref": "#/components/schemas/Market"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank, Currency can't be blank, Default locale
+ can't be blank, and Countries can't be blank
+ details:
+ name:
+ - can't be blank
+ currency:
+ - can't be blank
+ default_locale:
+ - can't be blank
+ countries:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
- required:
- - ids
- - channel_ids
properties:
- ids:
+ name:
+ type: string
+ example: Europe
+ currency:
+ type: string
+ example: EUR
+ description: ISO 4217 currency code.
+ default_locale:
+ type: string
+ example: de
+ description: IETF locale tag used as the market default.
+ supported_locales:
type: array
items:
type: string
- channel_ids:
+ description: Locale codes available in this market. The default
+ is always implicitly included.
+ example:
+ - de
+ - en
+ 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
- "/api/v3/admin/products/bulk_add_tags":
- post:
- summary: Bulk-add tags to products
+ description: 2-letter ISO country codes assigned to this market.
+ At least one is required.
+ example:
+ - DE
+ - FR
+ 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:
- - Products
+ - Markets
security:
- api_key: []
bearer_auth: []
- description: |-
- Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.
-
- **Required scope:** `write_products` (for API-key authentication).
+ description: "**Required scope:** `read_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20442,13 +11047,10 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkAddTags({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- tags: ['summer', 'sale'],
- })
+ const market = await client.markets.get('market_xxx')
- 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 get /markets/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -20460,50 +11062,59 @@ paths:
required: true
schema:
type: string
+ - name: expand
+ in: query
+ required: false
+ schema:
+ type: string
responses:
'200':
- description: tags added
+ description: market found
content:
application/json:
+ example:
+ id: mkt_gbHJdmfrXB
+ name: EU
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: false
+ country_codes:
+ - DE
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
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
- example:
- - summer
- - sale
- "/api/v3/admin/products/bulk_remove_tags":
- post:
- summary: Bulk-remove tags from products
+ "$ref": "#/components/schemas/Market"
+ '404':
+ description: market not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Market not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a market
tags:
- - Products
+ - Markets
security:
- api_key: []
bearer_auth: []
description: |-
- Removes each tag in `tags` from every product in `ids`.
+ Updates an existing market. Pass `country_codes` to replace the
+ market's country list (full-set update), `supported_locales` to
+ replace the supported locales, or `position` to reorder the market
+ within the store.
- **Required scope:** `write_products` (for API-key authentication).
+ Setting `default: true` automatically demotes the previous default.
+
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20515,13 +11126,17 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkRemoveTags({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- tags: ['summer'],
+ // `country_codes` is a full-set update — the market is reconciled to match
+ // the array (adds new countries, removes ones not present). Setting
+ // `default: true` demotes the previous default market in the store.
+ const market = await client.markets.update('market_UkLWZg9DAJ', {
+ name: 'European Union',
+ tax_inclusive: true,
+ country_codes: ['DE', 'FR'],
})
- lang: bash
label: Spree CLI
- source: spree api post /products/bulk_remove_tags -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"tags":["summer"]}'
+ source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_codes":["DE","FR"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -20535,36 +11150,78 @@ paths:
type: string
responses:
'200':
- description: tags removed
+ description: market updated
+ content:
+ application/json:
+ example:
+ id: mkt_gbHJdmfrXB
+ name: European Union
+ currency: USD
+ default_locale: en
+ tax_inclusive: true
+ default: false
+ country_codes:
+ - DE
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Market"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
- required:
- - ids
- - tags
properties:
- ids:
+ name:
+ type: string
+ currency:
+ type: string
+ default_locale:
+ type: string
+ supported_locales:
type: array
items:
type: string
- tags:
+ tax_inclusive:
+ type: boolean
+ default:
+ type: boolean
+ position:
+ type: integer
+ country_codes:
type: array
items:
type: string
- "/api/v3/admin/products/bulk_destroy":
delete:
- summary: Bulk-delete products
+ summary: Delete a market
tags:
- - Products
+ - Markets
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes each product in `ids`. Returns the count actually destroyed.
+ Soft-deletes the market (sets `deleted_at`). The default market and
+ the last remaining market in a store cannot be deleted — both return
+ 422 with a `validation_error`.
- **Required scope:** `write_products` (for API-key authentication).
+
+ **Required scope:** `write_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20576,12 +11233,12 @@ paths:
secretKey: 'sk_xxx',
})
- const result = await client.products.bulkDestroy({
- ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
- })
+ // Soft-deletes the market (sets `deleted_at`). The default market and the
+ // last remaining market in a store cannot be deleted — both return 422.
+ await client.markets.delete('market_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /products/bulk_destroy -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"]}'
+ source: spree api delete /markets/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -20594,42 +11251,28 @@ paths:
schema:
type: string
responses:
- '200':
- description: products deleted
+ '204':
+ description: market deleted
+ '422':
+ description: cannot delete default or last market
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/promotions/{promotion_id}/promotion_actions":
- parameters:
- - name: promotion_id
- in: path
- required: true
- schema:
- type: string
+ example:
+ error:
+ code: validation_error
+ message: Market cannot be deleted
+ "/api/v3/admin/option_types":
get:
- summary: List actions for a promotion
+ summary: List option types
tags:
- - Promotions
+ - Option Types
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_promotions` (for API-key authentication)."
+ description: |-
+ Returns a paginated list of option types.
+
+ **Required scope:** `read_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20641,10 +11284,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: actions } = await client.promotions.actions.list('promo_UkLWZg9DAJ')
+ const { data: optionTypes } = await client.optionTypes.list()
- lang: bash
label: Spree CLI
- source: spree api get /promotions/{promotion_id}/promotion_actions
+ source: spree api get /option_types
parameters:
- name: x-spree-api-key
in: header
@@ -20654,22 +11297,103 @@ 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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ 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: actions found
+ description: option types found
+ content:
+ application/json:
+ example:
+ data:
+ - id: opt_UkLWZg9DAJ
+ name: foo-size-7
+ label: Size
+ position: 1
+ kind: dropdown
+ metadata: {}
+ filterable: 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/OptionType"
+ 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 an option type
tags:
- - Promotions
+ - Option Types
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`). Fully-qualified Ruby class names are also accepted for backward compatibility.
+ Creates a new option type. Supports nested option values.
- **Required scope:** `write_promotions` (for API-key authentication).
+ Option values can be provided inline and will be created or updated by name.
+
+
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20681,12 +11405,17 @@ paths:
secretKey: 'sk_xxx',
})
- const action = await client.promotions.actions.create('promo_UkLWZg9DAJ', {
- type: 'free_shipping',
+ const optionType = await client.optionTypes.create({
+ name: 'color',
+ label: 'Color',
+ option_values: [
+ { name: 'red', label: 'Red' },
+ { name: 'navy', label: 'Navy' },
+ ],
})
- lang: bash
label: Spree CLI
- source: spree api post /promotions/{promotion_id}/promotion_actions -d '{"type":"free_shipping"}'
+ source: spree api post /option_types -d '{"name":"color","label":"Color","option_values":[{"name":"red","label":"Red"},{"name":"navy","label":"Navy"}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -20696,47 +11425,87 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: action created
+ description: option type created
+ content:
+ application/json:
+ example:
+ id: opt_gbHJdmfrXB
+ name: material
+ label: Material
+ position: 2
+ kind: dropdown
+ metadata: {}
+ filterable: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/OptionType"
'422':
- description: unknown action type
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank and Label can't be blank
+ details:
+ name:
+ - can't be blank
+ label:
+ - can't be blank
+ 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: color
+ label:
+ type: string
+ example: Color
+ position:
+ type: integer
+ example: 1
+ filterable:
+ type: boolean
+ example: true
+ option_values:
+ type: array
+ items:
+ type: object
+ properties:
+ name:
+ type: string
+ example: red
+ label:
+ type: string
+ example: Red
+ position:
+ type: integer
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
+ - name
+ - label
+ "/api/v3/admin/option_types/{id}":
+ get:
+ summary: Get an option type
tags:
- - Promotions
+ - Option Types
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ description: |-
+ Returns a single option type by ID, including its option values.
+
+ **Required scope:** `read_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20748,10 +11517,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.promotions.actions.delete('promo_UkLWZg9DAJ', 'promoact_k5nR8xLq')
+ const optionType = await client.optionTypes.get('ot_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /promotions/{promotion_id}/promotion_actions/{id}
+ source: spree api get /option_types/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -20761,66 +11530,67 @@ 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
- tags:
- - Promotions
- security:
- - api_key: []
- bearer_auth: []
- 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: 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
+ - name: id
+ in: path
required: true
+ description: Option type ID
schema:
type: string
- - name: Authorization
- in: header
- required: true
+ - 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: rules found
- post:
- summary: Create a rule on a promotion
+ description: option type found
+ content:
+ application/json:
+ example:
+ id: opt_UkLWZg9DAJ
+ name: foo-size-11
+ label: Size
+ position: 1
+ kind: dropdown
+ metadata: {}
+ filterable: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/OptionType"
+ '404':
+ description: option type not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Option type not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update an option type
tags:
- - Promotions
+ - Option Types
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`). Fully-qualified Ruby class names are also accepted for backward compatibility.
+ Updates an option type. Supports updating nested option values.
- **Required scope:** `write_promotions` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20832,13 +11602,13 @@ paths:
secretKey: 'sk_xxx',
})
- const rule = await client.promotions.rules.create('promo_UkLWZg9DAJ', {
- type: 'currency',
- preferences: { currency: 'EUR' },
+ const optionType = await client.optionTypes.update('ot_UkLWZg9DAJ', {
+ label: 'Updated Label',
+ option_values: [{ name: 'red', label: 'Crimson' }],
})
- lang: bash
label: Spree CLI
- source: spree api post /promotions/{promotion_id}/promotion_rules -d '{"type":"currency","preferences":{"currency":"EUR"}}'
+ source: spree api patch /option_types/{id} -d '{"label":"Updated Label","option_values":[{"name":"red","label":"Crimson"}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -20848,47 +11618,90 @@ paths:
- 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:
- '201':
- description: rule created with preferences
+ '200':
+ description: option type updated
+ content:
+ application/json:
+ example:
+ id: opt_UkLWZg9DAJ
+ name: foo-size-13
+ label: Updated Label
+ position: 1
+ kind: dropdown
+ metadata: {}
+ filterable: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/OptionType"
'422':
- description: unknown rule type
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Label can't be blank
+ details:
+ label:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- type:
+ name:
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 rule's preferences
+ example: color
+ label:
+ type: string
+ example: Color
+ position:
+ type: integer
+ example: 1
+ filterable:
+ type: boolean
+ example: true
+ option_values:
+ type: array
+ items:
+ type: object
+ properties:
+ id:
+ type: string
+ description: Existing option value ID to update
+ name:
+ type: string
+ example: red
+ label:
+ type: string
+ example: Red
+ position:
+ type: integer
+ delete:
+ summary: Delete an option type
tags:
- - Promotions
+ - Option Types
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ description: |-
+ Deletes an option type.
+
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20900,13 +11713,10 @@ paths:
secretKey: 'sk_xxx',
})
- const rule = await client.promotions.rules.update('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq', {
- preferences: { currency: 'USD' },
- })
+ await client.optionTypes.delete('ot_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /promotions/{promotion_id}/promotion_rules/{id} -d
- '{"preferences":{"currency":"USD"}}'
+ source: spree api delete /option_types/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -20916,28 +11726,30 @@ paths:
- 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: rule updated
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- preferences:
- type: object
- additionalProperties: true
- delete:
- summary: Delete a rule from a promotion
+ '204':
+ description: option type deleted
+ "/api/v3/admin/orders/{order_id}/tax_lines":
+ get:
+ summary: List tax lines
tags:
- - Promotions
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ description: |-
+ Typed tax rows on the order. Read-only — written exclusively by the tax provider.
+
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20949,10 +11761,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.promotions.rules.delete('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq')
+ const { data: taxLines } = await client.orders.taxLines.list('or_abc123')
- lang: bash
label: Spree CLI
- source: spree api delete /promotions/{promotion_id}/promotion_rules/{id}
+ source: spree api get /orders/{order_id}/tax_lines
parameters:
- name: x-spree-api-key
in: header
@@ -20964,21 +11776,59 @@ paths:
required: true
schema:
type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
responses:
- '204':
- description: rule deleted
- "/api/v3/admin/promotions":
+ '200':
+ description: tax lines found
+ content:
+ application/json:
+ example:
+ data:
+ - id: tl_UkLWZg9DAJ
+ label: VAT 15%
+ included: false
+ rate: '0.15'
+ tax_rate_id:
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ fee_id:
+ amount: '1.5'
+ display_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'
+ 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 promotions
+ summary: List discounts
tags:
- - Promotions
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the store's promotions, including manual coupon and automatic promotions.
+ Typed discount rows (promotion-sourced and manual) on the order.
- **Required scope:** `read_promotions` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -20990,10 +11840,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: promotions } = await client.promotions.list()
+ const { data: discounts } = await client.orders.discounts.list('or_abc123')
- lang: bash
label: Spree CLI
- source: spree api get /promotions
+ source: spree api get /orders/{order_id}/discounts
parameters:
- name: x-spree-api-key
in: header
@@ -21005,26 +11855,54 @@ paths:
required: true
schema:
type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
responses:
'200':
- description: promotions found
+ description: discounts 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.0"
+ display_amount: "-$2.00"
+ 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:
post:
- summary: Create a promotion
+ summary: Create manual discount
tags:
- - Promotions
+ - Orders
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.
-
+ 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_promotions` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21036,51 +11914,17 @@ 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, 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' },
- ],
+ // 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 /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 /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
@@ -21092,137 +11936,79 @@ paths:
required: true
schema:
type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order prefixed ID
+ schema:
+ type: string
responses:
'201':
- description: promotion created with rules and actions
+ description: discount created
content:
application/json:
example:
- id: promo_gbHJdmfrXB
- name: Black Friday
- description:
- code: blackfriday
- 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'
- action_ids: []
- rule_ids: []
+ data:
+ - id: disc_UkLWZg9DAJ
+ label: Appeasement
+ kind: manual
+ code:
+ value_type: flat
+ value: '3.0'
+ promotion_id:
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ amount: "-3.0"
+ display_amount: "-$3.00"
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
'422':
- description: invalid params
+ description: invalid discount
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: discount value must be a positive number
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:
+ label:
type: string
- enum:
- - all
- - any
- kind:
+ example: Customer appeasement
+ value:
+ type: number
+ example: 10
+ value_type:
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:
+ - flat
+ - percent
+ example: flat
+ line_item_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
+ example: item_abc123
+ description: Target line item; omit to distribute order-level
required:
- - name
- "/api/v3/admin/promotions/{id}":
- get:
- summary: Show a promotion
+ - label
+ - value
+ "/api/v3/admin/orders/{order_id}/fees":
+ post:
+ summary: Create fee
tags:
- - Promotions
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `read_promotions` (for API-key authentication)."
+ 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
@@ -21234,10 +12020,14 @@ paths:
secretKey: 'sk_xxx',
})
- const promotion = await client.promotions.get('promo_UkLWZg9DAJ')
+ const fee = await client.orders.fees.create('or_abc123', {
+ label: 'Gift wrap',
+ amount: 4,
+ kind: 'gift_wrap',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /promotions/{id}
+ source: spree api post /orders/{order_id}/fees -d '{"label":"Gift wrap","amount":4,"kind":"gift_wrap"}'
parameters:
- name: x-spree-api-key
in: header
@@ -21249,29 +12039,83 @@ paths:
required: true
schema:
type: string
- - name: id
+ - name: order_id
in: path
required: true
+ description: Order prefixed ID
schema:
type: string
responses:
- '200':
- description: promotion found
- patch:
- summary: Update a promotion
+ '201':
+ description: fee created
+ content:
+ application/json:
+ example:
+ id: fee_UkLWZg9DAJ
+ label: Gift wrap
+ kind: gift_wrap
+ line_item_id:
+ fulfillment_id:
+ amount: '4.0'
+ display_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:
+ - is not included in the list
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ label:
+ type: string
+ example: Gift wrap
+ amount:
+ type: number
+ example: 4
+ kind:
+ type: string
+ enum:
+ - surcharge
+ - handling
+ - gift_wrap
+ - cod
+ - payment
+ - duty
+ 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:
- - Promotions
+ - Orders
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.
-
+ Applies a gift card by code to the order. Returns the gift card.
- **Required scope:** `write_promotions` (for API-key authentication).
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21283,48 +12127,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, 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: [],
+ await client.orders.giftCards.apply('or_UkLWZg9DAJ', {
+ code: 'GIFT-XXXX-YYYY',
})
- lang: bash
label: Spree CLI
- source: spree api patch /promotions/{id} -d '{"description":"Updated description"}'
+ source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'
parameters:
- name: x-spree-api-key
in: header
@@ -21334,117 +12142,64 @@ paths:
- name: Authorization
in: header
required: true
+ 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: rules and actions cleared with empty arrays
+ '201':
+ description: gift card applied
+ content:
+ application/json:
+ example:
+ id: gc_UkLWZg9DAJ
+ code: 16C1B414C44A2F41
+ status: active
+ currency: USD
+ amount: '10.0'
+ amount_used: '10.0'
+ amount_authorized: '0.0'
+ amount_remaining: '0.0'
+ display_amount: "$10.00"
+ display_amount_used: "$10.00"
+ display_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:
- 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
+ description: Gift card code
+ example: GIFT-XXXX-YYYY
+ "/api/v3/admin/orders/{order_id}/gift_cards/{id}":
delete:
- summary: Delete a promotion
+ summary: Remove a gift card from an order
tags:
- - Promotions
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: "**Required scope:** `write_promotions` (for API-key authentication)."
+ 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
@@ -21456,10 +12211,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.promotions.delete('promo_UkLWZg9DAJ')
+ await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /promotions/{id}
+ source: spree api delete /orders/{order_id}/gift_cards/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -21469,28 +12224,36 @@ 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: Gift card ID
schema:
type: string
responses:
'204':
- description: promotion deleted
- "/api/v3/admin/promotion_actions/types":
+ description: gift card removed
+ "/api/v3/admin/orders/{order_id}/items":
get:
- summary: List available promotion action types
+ summary: List order items
tags:
- - Promotions
+ - Orders
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.
+ Returns all line items for an order.
- **Required scope:** `read_promotions` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21502,10 +12265,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: actionTypes } = await client.promotionActions.types()
+ const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /promotion_actions/types
+ source: spree api get /orders/{order_id}/items
parameters:
- name: x-spree-api-key
in: header
@@ -21515,23 +12278,107 @@ 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: 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: action types found
- "/api/v3/admin/promotion_rules/types":
- get:
- summary: List available promotion rule types
+ description: items found
+ 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 539180
+ slug: product-539180
+ options_text: 'Size: S'
+ price: '10.0'
+ display_price: "$10.00"
+ total: '20.0'
+ display_total: "$20.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '20.0'
+ display_pre_tax_amount: "$20.00"
+ discounted_amount: '20.0'
+ display_discounted_amount: "$20.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-7
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-16
+ 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'
+ cost_price: '17.0'
+ 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:
- - Promotions
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the registered Spree::PromotionRule subclasses with their preference schemas.
+ Adds a new line item to the order.
- **Required scope:** `read_promotions` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21543,10 +12390,13 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: ruleTypes } = await client.promotionRules.types()
+ const item = await client.orders.items.create('or_UkLWZg9DAJ', {
+ variant_id: 'variant_k5nR8xLq',
+ quantity: 2,
+ })
- lang: bash
label: Spree CLI
- source: spree api get /promotion_rules/types
+ source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'
parameters:
- name: x-spree-api-key
in: header
@@ -21556,28 +12406,97 @@ 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
responses:
- '200':
- description: rule types found
- "/api/v3/admin/refund_reasons":
+ '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
+ name: Product 5599
+ slug: product-5599
+ options_text: 'Size: S'
+ price: '19.99'
+ display_price: "$19.99"
+ total: '59.97'
+ display_total: "$59.97"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '59.97'
+ display_pre_tax_amount: "$59.97"
+ discounted_amount: '59.97'
+ display_discounted_amount: "$59.97"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_gbHJdmfrXB
+ option_type_id: opt_gbHJdmfrXB
+ name: size-9
+ 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'
+ cost_price: '17.0'
+ 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}":
get:
- summary: List refund reasons
+ summary: Show an item
tags:
- - Reasons
+ - Orders
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.
-
+ Returns details of a specific line item.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21589,10 +12508,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: reasons } = await client.refundReasons.list()
+ const item = await client.orders.items.get('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /refund_reasons
+ source: spree api get /orders/{order_id}/items/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -21605,56 +12524,99 @@ paths:
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
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
schema:
- type: integer
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Item ID
schema:
type: string
- - name: q[active_eq]
+ - name: expand
in: query
required: false
- description: Filter by active flag
+ description: Comma-separated associations to expand (e.g., variant, variant.product).
+ Use dot notation for nested expand (max 4 levels).
schema:
- type: boolean
- - name: sort
+ type: string
+ - name: fields
in: query
required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ description: Comma-separated list of fields to include (e.g., quantity,price,total).
+ id is always included.
schema:
type: string
responses:
'200':
- description: refund reasons found
- '401':
- description: unauthorized
+ description: item found
content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a refund reason
+ application/json:
+ example:
+ id: li_UkLWZg9DAJ
+ variant_id: variant_gbHJdmfrXB
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 2
+ currency: USD
+ name: Product 562714
+ slug: product-562714
+ options_text: 'Size: S'
+ price: '10.0'
+ display_price: "$10.00"
+ total: '20.0'
+ display_total: "$20.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '20.0'
+ display_pre_tax_amount: "$20.00"
+ discounted_amount: '20.0'
+ display_discounted_amount: "$20.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-10
+ 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'
+ 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'
+ cost_price: '17.0'
+ tax_category_id: taxcat_UkLWZg9DAJ
+ patch:
+ summary: Update an item
tags:
- - Reasons
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Adds a refund reason to this store. Names are unique per store, ignoring case.
+ Updates an order item quantity or metadata.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21666,12 +12628,12 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.refundReasons.create({
- name: 'Goodwill gesture',
+ const item = await client.orders.items.update('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ', {
+ quantity: 5,
})
- lang: bash
label: Spree CLI
- source: spree api post /refund_reasons -d '{"name":"Goodwill gesture"}'
+ source: spree api patch /orders/{order_id}/items/{id} -d '{"quantity":5}'
parameters:
- name: x-spree-api-key
in: header
@@ -21684,50 +12646,93 @@ 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: Item ID
+ schema:
+ type: string
responses:
- '201':
- description: refund reason created
- '422':
- description: validation error
+ '200':
+ description: item updated
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ id: li_UkLWZg9DAJ
+ variant_id: variant_gbHJdmfrXB
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 5
+ currency: USD
+ name: Product 579758
+ slug: product-579758
+ options_text: 'Size: S'
+ price: '19.99'
+ display_price: "$19.99"
+ total: '99.95'
+ display_total: "$99.95"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '99.95'
+ display_pre_tax_amount: "$99.95"
+ discounted_amount: '99.95'
+ display_discounted_amount: "$99.95"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-11
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-20
+ 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'
+ cost_price: '17.0'
+ tax_category_id: taxcat_UkLWZg9DAJ
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: Get a refund reason
+ quantity:
+ type: integer
+ delete:
+ summary: Remove an item
tags:
- - Reasons
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single refund reason by prefixed ID.
+ Removes an item from the order.
- **Required scope:** `read_settings` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21739,10 +12744,10 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.refundReasons.get('rr_UkLWZg9DAJ')
+ await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /refund_reasons/{id}
+ source: spree api delete /orders/{order_id}/items/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -21755,28 +12760,33 @@ 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: Item ID
+ schema:
+ type: string
responses:
- '200':
- description: refund reason found
- '404':
- description: refund reason not found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a refund reason
+ '204':
+ description: line item removed
+ "/api/v3/admin/orders/{order_id}/store_credits":
+ post:
+ summary: Apply customer's store credit to an order
tags:
- - Reasons
+ - Orders
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.
-
+ Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_store_credits` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21788,12 +12798,12 @@ paths:
secretKey: 'sk_xxx',
})
- const reason = await client.refundReasons.update('rr_UkLWZg9DAJ', {
- active: false,
+ const order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {
+ amount: '25.00',
})
- lang: bash
label: Spree CLI
- source: spree api patch /refund_reasons/{id} -d '{"active":false}'
+ source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'
parameters:
- name: x-spree-api-key
in: header
@@ -21806,33 +12816,125 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
responses:
- '200':
- description: refund reason updated
+ '201':
+ description: store credit applied
+ content:
+ application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '60.0'
+ display_amount_due: "$60.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '50.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
+ amount:
type: string
- active:
- type: boolean
+ description: Optional explicit amount; defaults to order outstanding
+ balance
delete:
- summary: Delete a refund reason
+ summary: Remove store credit from an order
tags:
- - Reasons
+ - Orders
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.
-
+ Removes any applied store credit from the order.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_store_credits` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -21844,10 +12946,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.refundReasons.delete('rr_UkLWZg9DAJ')
+ await client.orders.storeCredits.remove('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /refund_reasons/{id}
+ source: spree api delete /orders/{order_id}/store_credits
parameters:
- name: x-spree-api-key
in: header
@@ -21860,26 +12962,27 @@ paths:
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: refund reason deleted
- "/api/v3/admin/return_reasons":
+ description: store credit removed
+ "/api/v3/admin/orders":
get:
- summary: List return reasons
+ summary: List orders
tags:
- - Reasons
+ - Orders
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.
-
+ 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
@@ -21891,10 +12994,15 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: reasons } = await client.returnReasons.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 /return_reasons
+ 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
@@ -21919,117 +13027,172 @@ paths:
description: Number of records per page
schema:
type: integer
- - name: q[name_cont]
+ - name: sort
in: query
required: false
- description: Filter by name (contains)
+ description: Sort field (e.g., created_at, -created_at, completed_at)
schema:
type: string
- - name: q[active_eq]
+ - name: q[state_eq]
in: query
required: false
- description: Filter by active flag
+ description: Filter by state (cart, address, delivery, payment, confirm, complete,
+ canceled)
schema:
- type: boolean
- - name: sort
+ type: string
+ - name: q[email_cont]
in: query
required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ description: Filter by email (contains)
schema:
type: string
- responses:
- '200':
- description: return reasons found
- '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.
-
- **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 reason = await client.returnReasons.create({
- name: 'Damaged in transit',
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /return_reasons -d '{"name":"Damaged in transit"}'
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ - name: q[number_eq]
+ in: query
+ required: false
+ description: Filter by order number
schema:
type: string
- - name: Authorization
- in: header
- required: true
- description: Bearer token for admin authentication
+ - name: q[completed_at_gt]
+ in: query
+ required: false
+ description: Filter by completed after date
+ 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:
- '201':
- description: return reason created
- '422':
- description: validation error
+ '200':
+ description: orders found
+ content:
+ application/json:
+ example:
+ data:
+ - id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total:
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
+ 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"
- 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
+ post:
+ summary: Create a draft order
tags:
- - Reasons
+ - Orders
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
@@ -22041,61 +13204,93 @@ paths:
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
- 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
- '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
- that already carry it while removing it from the pickers.
+ // 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',
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ // 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',
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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',
+ },
- const reason = await client.returnReasons.update('rar_UkLWZg9DAJ', {
- active: false,
+ // 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 patch /return_reasons/{id} -d '{"active":false}'
+ 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
@@ -22109,32 +13304,217 @@ paths:
schema:
type: string
responses:
- '200':
- description: return reason updated
+ '201':
+ description: order created with preferred_stock_location_id
+ content:
+ application/json:
+ example:
+ id: or_gbHJdmfrXB
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferred_stock_location_id: sloc_UkLWZg9DAJ
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id: adm_UkLWZg9DAJ
+ customer_id:
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
+ email:
type: string
- active:
+ customer_id:
+ type: string
+ description: 'Customer ID. Alias: user_id (legacy).'
+ use_customer_default_address:
type: boolean
- delete:
- summary: Delete a return reason
+ 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:
+ type: string
+ description: Optional. Applied non-fatally; invalid codes do not
+ block creation.
+ "/api/v3/admin/orders/{id}":
+ get:
+ summary: Show an order
tags:
- - Reasons
+ - Orders
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.
-
+ Returns full order details including admin-only fields.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `read_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22146,10 +13526,12 @@ paths:
secretKey: 'sk_xxx',
})
- await client.returnReasons.delete('rar_UkLWZg9DAJ')
+ const order = await client.orders.get('or_UkLWZg9DAJ', {
+ expand: ['items', 'fulfillments', 'payments', 'customer'],
+ })
- lang: bash
label: Spree CLI
- source: spree api delete /return_reasons/{id}
+ source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -22162,61 +13544,140 @@ paths:
description: Bearer token for admin authentication
schema:
type: string
- responses:
- '204':
- description: return reason deleted
- "/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.
-
- **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: roles } = await client.roles.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /roles
- parameters:
- - name: x-spree-api-key
- in: header
+ - name: id
+ in: path
required: true
+ description: Order ID (e.g., or_xxx)
schema:
type: string
- - name: Authorization
- in: header
- required: true
+ - 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: roles found
- post:
- summary: Create a role
+ description: order found
+ content:
+ application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total:
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
+ '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
tags:
- - Staff
+ - Orders
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.
+ Updates an order. Supports updating email, addresses, special instructions, and line items.
- **Required scope:** `write_staff` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22228,15 +13689,14 @@ paths:
secretKey: 'sk_xxx',
})
- const role = await client.roles.create({
- name: 'order_manager',
- description: 'Handles daily orders',
- permissions: ['write_orders', 'read_customers'],
+ 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 post /roles -d '{"name":"order_manager","description":"Handles
- daily orders","permissions":["write_orders","read_customers"]}'
+ 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
@@ -22246,110 +13706,191 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- responses:
- '201':
- description: role created
- '422':
- description: invalid request
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: order_manager
- description:
- type: string
- nullable: true
- example: Handles daily orders
- permissions:
- type: array
- items:
- type: string
- example:
- - write_orders
- - read_customers
- 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.
-
- **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 role = await client.roles.update('role_abc123', {
- permissions: ['write_orders', 'write_payments', 'read_customers'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /roles/{id} -d '{"permissions":["write_orders","write_payments","read_customers"]}'
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
+ - name: id
+ in: path
required: true
+ description: Order ID
schema:
type: string
responses:
'200':
- description: role updated
+ description: order updated
+ content:
+ application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: draft
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
+ email:
type: string
- description:
+ customer_note:
type: string
- nullable: true
- permissions:
+ 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: string
+ 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 role
+ summary: Delete a draft order
tags:
- - Staff
+ - Orders
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.
+ Deletes a draft order. Completed orders cannot be deleted.
- **Required scope:** `write_staff` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22361,10 +13902,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.roles.delete('role_abc123')
+ await client.orders.delete('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /roles/{id}
+ source: spree api delete /orders/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -22374,32 +13915,33 @@ 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:
'204':
- description: role deleted
- '422':
- description: role cannot be deleted
- "/api/v3/admin/seller_requirements":
- get:
- summary: List seller requirements
+ description: order deleted
+ "/api/v3/admin/orders/{id}/complete":
+ patch:
+ summary: Complete an order
tags:
- - Seller Requirements
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- What this marketplace asks of a seller before it will let them trade,
- in the order sellers work through it.
+ Completes an order in the `confirm` state, marking it as placed.
- Each row is one configured requirement. `required` says whether it
- stands between the seller and approval — the others are shown as
- recommended and counted in their progress, but never block. `active`
- switches one off without losing how it was worded.
+ Set `notify_customer: true` to send the order confirmation email.
- **Required scope:** `read_sellers` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22411,12 +13953,12 @@ paths:
secretKey: 'sk_xxx',
})
- // The checklist in the order sellers work through it. `required` items block
- // approval; the rest are shown as recommended.
- const { data: sellerRequirements } = await client.sellerRequirements.list({ page: 1, limit: 25 })
+ const order = await client.orders.complete('or_UkLWZg9DAJ', {
+ notify_customer: true,
+ })
- lang: bash
label: Spree CLI
- source: spree api get /seller_requirements -d '{"page":1,"limit":25}'
+ source: spree api patch /orders/{id}/complete -d '{"notify_customer":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -22426,55 +13968,157 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
+ - name: id
+ in: path
+ required: true
+ description: Order ID
schema:
- type: integer
+ type: string
responses:
'200':
- description: seller requirements found
+ description: order completed
+ content:
+ application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: placed
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '110.0'
+ display_payment_total: "$110.00"
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
+ '422':
+ description: order cannot be completed
content:
application/json:
+ example:
+ error:
+ code: order_cannot_complete
+ message: No payment found
+ details:
+ base:
+ - No payment found
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/SellerRequirement"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- post:
- summary: Add a seller requirement
+ "$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:
- - Seller Requirements
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Adds something the marketplace asks of its sellers.
+ Cancels a completed order.
- `type` comes from `GET /seller_requirements/types`, which also
- describes the configuration each kind takes. Most kinds answer one
- question and can be added once; the open-ended ones — a seller
- confirmation, a manual check, a document — carry the question in your
- own `name` and `description`, so a store may add as many as it needs.
+ `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.
- A kind that reads the seller's own data (their addresses, their
- products, whether they accepted the terms) needs nothing from the
- seller beyond doing it. The others wait for the seller to submit
- something, and the ones you review wait for you.
+ Set `notify_customer: true` to send the order cancellation email.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22486,20 +14130,18 @@ paths:
secretKey: 'sk_xxx',
})
- // Asks every seller for a business registration before they can be approved.
- // The wording is yours — `document` is one of the open-ended kinds, so a store
- // can add as many as it needs, each with its own instructions.
- const sellerRequirement = await client.sellerRequirements.create({
- type: 'document',
- name: 'Business registration',
- description: 'A copy of your certificate of incorporation.',
- required: true,
- preferences: { accepted_content_types: ['application/pdf'] },
+ // 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 /seller_requirements -d '{"type":"document","name":"Business
- registration","description":"A copy of your certificate of incorporation.","required":true,"preferences":{"accepted_content_types":["application/pdf"]}}'
+ 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
@@ -22509,81 +14151,145 @@ 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: seller requirement created
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/SellerRequirement"
- '422':
- description: kind is not registered
+ '200':
+ description: order canceled
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: "-0.0"
+ display_amount_due: "$0.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: canceled
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ 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'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id: adm_UkLWZg9DAJ
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
- required:
- - type
properties:
- type:
- type: string
- example: document
- description: The kind, from `GET /seller_requirements/types`.
- name:
+ cancel_reason_id:
type: string
- example: Business registration
- 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:
+ description: Why the order was canceled — the id of one of the store's
+ cancellation reasons.
+ cancel_note:
type: string
- example: A copy of your certificate of incorporation.
- description: Instructions shown to the seller.
- required:
+ description: Staff-facing note about the cancellation.
+ refund_payments:
type: boolean
- example: true
- description: Whether this blocks approval. Off means recommended.
- active:
+ 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
- example: true
- position:
- type: integer
- example: 1
- description: Place in the checklist.
- preferences:
- type: object
- example:
- accepted_content_types:
- - application/pdf
- description: Configuration for this kind, per its `preference_schema`.
- "/api/v3/admin/seller_requirements/types":
- get:
- summary: List seller requirement kinds
+ default: false
+ description: Send the order cancellation email after canceling.
+ "/api/v3/admin/orders/{id}/approve":
+ patch:
+ summary: Approve an order
tags:
- - Seller Requirements
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- The kinds you can add, and the shape of each one's configuration form.
-
- `configured` says the store already has this kind — meaningful only
- where `allow_multiple` is false. `accepts_submissions` says the seller
- records having done it rather than it being read from their data, and
- `reviewed_by_operator` says what they send waits for you.
-
- A marketplace that registers its own kind server-side sees it here
- without this endpoint changing.
-
+ Approves an order (e.g., for fraud review).
- **Required scope:** `read_sellers` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22595,12 +14301,10 @@ paths:
secretKey: 'sk_xxx',
})
- // What you can ask for, and the configuration each kind takes. A kind your own
- // code registers server-side shows up here too.
- const { data: requirementTypes } = await client.sellerRequirements.types()
+ const order = await client.orders.approve('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /seller_requirements/types
+ source: spree api patch /orders/{id}/approve -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -22610,75 +14314,119 @@ 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: kinds found
+ description: order approved
content:
application/json:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- type: object
- properties:
- type:
- type: string
- example: document
- name:
- type: string
- example: Document
- description:
- type: string
- example: A file the seller uploads and you review
- allow_multiple:
- type: boolean
- example: true
- accepts_submissions:
- type: boolean
- example: true
- reviewed_by_operator:
- type: boolean
- example: true
- configured:
- type: boolean
- example: false
- addable:
- type: boolean
- example: true
- description: Whether the operator may add one now. The uniqueness
- rule is the server's, so clients filter on this rather
- than deriving it.
- preference_schema:
- type: array
- items:
- type: object
- "/api/v3/admin/seller_requirements/{id}":
- parameters:
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Update a seller requirement
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: placed
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ 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'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id: adm_UkLWZg9DAJ
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
+ "/api/v3/admin/orders/{id}/resend_confirmation":
+ post:
+ summary: Resend confirmation email
tags:
- - Seller Requirements
+ - Orders
security:
- api_key: []
bearer_auth: []
description: |-
- Changes how a requirement is worded, what it asks for, where it sits in
- the checklist, and whether it blocks approval.
-
- `type` is not accepted: a saved row's kind never changes, because
- anything a seller already submitted answered the old one.
-
+ Publishes the order.completed event to trigger confirmation email delivery.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22690,14 +14438,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Asks for three products instead of one. Sellers who already met the old
- // number see this return to their checklist.
- const sellerRequirement = await client.sellerRequirements.update('selreq_a1b2c3', {
- preferences: { minimum_count: 3 },
- })
+ await client.orders.resendConfirmation('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /seller_requirements/{id} -d '{"preferences":{"minimum_count":3}}'
+ source: spree api post /orders/{id}/resend_confirmation -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -22707,54 +14451,119 @@ 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: seller requirement updated
+ description: confirmation resent
content:
application/json:
- schema:
- "$ref": "#/components/schemas/SellerRequirement"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Proof of business registration
- description:
- type: string
- example: A copy of your certificate of incorporation.
- required:
- type: boolean
- example: false
- active:
- type: boolean
- example: true
- position:
- type: integer
- example: 2
- preferences:
- type: object
- example:
- minimum_count: 3
- delete:
- summary: Delete a seller requirement
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_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
+ supported_locales:
+ - en
+ tax_provider:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ external_references: {}
+ status: placed
+ last_ip_address:
+ considered_risky: false
+ confirmation_delivered: false
+ store_owner_notification_delivered:
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ metadata: {}
+ cancel_note:
+ canceled_at:
+ approved_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preferred_stock_location_id:
+ po_document_url:
+ seller_id:
+ order_group_id:
+ tags: []
+ internal_note:
+ internal_note_html:
+ approver_id:
+ canceler_id:
+ cancel_reason_id:
+ cancel_reason_name:
+ created_by_id:
+ customer_id: cust_UkLWZg9DAJ
+ "/api/v3/admin/payment_methods":
+ get:
+ summary: List payment methods
tags:
- - Seller Requirements
+ - Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
- Stops asking for this. Anything sellers already submitted against it
- goes too — to keep the record while pausing the ask, set `active` to
- false instead.
-
+ Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22765,13 +14574,11 @@ paths:
baseUrl: 'https://your-store.com',
secretKey: 'sk_xxx',
})
-
- // Stops asking for this, and deletes what sellers submitted against it. To
- // keep the record while pausing the ask, update it with `active: false`.
- await client.sellerRequirements.delete('selreq_a1b2c3')
+
+ const { data: paymentMethods } = await client.paymentMethods.list()
- lang: bash
label: Spree CLI
- source: spree api delete /seller_requirements/{id}
+ source: spree api get /payment_methods
parameters:
- name: x-spree-api-key
in: header
@@ -22783,25 +14590,66 @@ paths:
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: seller requirement deleted
- "/api/v3/admin/sellers":
+ '200':
+ description: payment methods found
+ content:
+ application/json:
+ example:
+ data:
+ - id: pm_UkLWZg9DAJ
+ name: Check
+ 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: {}
+ preference_schema: []
+ 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 sellers
+ summary: List available payment provider types
tags:
- - Sellers
+ - Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the sellers on this marketplace. `status` says where each one
- is in its life on the marketplace, and `sellable` answers the question
- the status alone cannot: an approved seller who is away cannot be
- bought from either.
-
+ Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a "Provider" dropdown in admin UIs.
- **Required scope:** `read_sellers` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22813,12 +14661,10 @@ paths:
secretKey: 'sk_xxx',
})
- // `sellable` is the one to read for "can this seller be bought from" — an
- // approved seller who is away answers false.
- const { data: sellers } = await client.sellers.list({ page: 1, limit: 25 })
+ const { data: types } = await client.paymentMethods.types()
- lang: bash
label: Spree CLI
- source: spree api get /sellers -d '{"page":1,"limit":25}'
+ source: spree api get /payment_methods/types
parameters:
- name: x-spree-api-key
in: header
@@ -22828,79 +14674,41 @@ 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[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: q[status_eq]
- in: query
- required: false
- description: Filter by status
- schema:
- type: string
- - name: sort
- in: query
- required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
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
+ description: provider types found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- post:
- summary: Create a seller
+ example:
+ data:
+ - type: bogus
+ label: Bogus
+ description:
+ preference_schema:
+ - key: dummy_key
+ type: string
+ default: PUBLICKEY123
+ - key: dummy_secret_key
+ type: password
+ default:
+ - type: custom_payment_source_method
+ label: Custom Payment Source Method
+ description:
+ preference_schema: []
+ "/api/v3/admin/payment_methods/{id}":
+ get:
+ summary: Show a payment method
tags:
- - Sellers
+ - Payment Methods
security:
- api_key: []
bearer_auth: []
description: |-
- Opens a seller record. The seller starts as `pending` and has no team
- yet — invite someone to run it with the `invite` action below.
-
- `status` is deliberately not writable here or on update: every move
- through the lifecycle is its own action, because each one does more
- than set a column.
-
+ Returns a payment method by ID.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `read_settings` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -22912,15 +14720,10 @@ paths:
secretKey: 'sk_xxx',
})
- // The seller starts as `pending` and has no team yet — invite someone to run
- // it next.
- const seller = await client.sellers.create({
- name: 'Northwind Books',
- contact_email: '[email protected]',
- })
+ const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api post /sellers -d '{"name":"Northwind Books","contact_email":"[email protected]"}'
+ source: spree api get /payment_methods/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -22932,84 +14735,60 @@ 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:
- '201':
- description: seller created
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Seller"
- '422':
- description: validation error
+ '200':
+ description: payment method found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - name
- properties:
- name:
- type: string
- example: Northwind Books
- slug:
- type: string
- example: northwind-books
- description: Derived from the name when omitted.
- contact_email:
- type: string
- nullable: true
- billing_email:
- type: string
- nullable: true
- about:
- type: string
- example: "<p>Independent bookshop.</p>"
- nullable: true
- tax_remittance:
- type: string
- enum:
- - seller
- - platform
- example: seller
- payouts_schedule_interval:
- type: string
- enum:
- - daily
- - weekly
- - biweekly
- - monthly
- - manual
- nullable: true
- minimum_payout_amount:
- type: string
- example: '25.0'
- nullable: true
- "/api/v3/admin/sellers/{id}":
- parameters:
- - name: id
- in: path
- required: true
- description: Seller prefixed ID
- schema:
- type: string
+ example:
+ id: pm_UkLWZg9DAJ
+ name: Check
+ 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: {}
+ preference_schema: []
+ "/api/v3/admin/orders/{order_id}/payments":
get:
- summary: Get a seller
+ summary: List payments
tags:
- - Sellers
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single seller, including its settlement and tax configuration.
+ Returns all payments for an order.
- **Required scope:** `read_sellers` (for API-key authentication).
+ **Required scope:** `read_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23021,10 +14800,10 @@ paths:
secretKey: 'sk_xxx',
})
- const seller = await client.sellers.get('sel_UkLWZg9DAJ')
+ const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /sellers/{id}
+ source: spree api get /orders/{order_id}/payments
parameters:
- name: x-spree-api-key
in: header
@@ -23034,35 +14813,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
+ 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: seller found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Seller"
- '404':
- description: seller not found
+ description: payments found
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a seller
+ example:
+ data:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: BGS-343039b69b86
+ number: R1001-P1
+ status: completed
+ amount: '110.0'
+ display_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.0'
+ order_id: or_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create a payment
tags:
- - Sellers
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Updates the seller's profile and the settlement configuration the
- operator owns. A `status` sent here is ignored — use the lifecycle
- actions.
-
+ Creates a new payment for the order.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `write_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23074,16 +14906,14 @@ paths:
secretKey: 'sk_xxx',
})
- // `status` is not writable here: each move through the lifecycle is its own
- // action, because each one does more than set a column.
- const seller = await client.sellers.update('sel_UkLWZg9DAJ', {
- billing_email: '[email protected]',
- payouts_schedule_interval: 'weekly',
- minimum_payout_amount: '25.0',
+ 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 patch /sellers/{id} -d '{"billing_email":"[email protected]","payouts_schedule_interval":"weekly","minimum_payout_amount":"25.0"}'
+ 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
@@ -23093,161 +14923,68 @@ 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
responses:
- '200':
- description: seller address written inline
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Seller"
- '422':
- description: validation error
+ '201':
+ description: payment created
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ id: py_gbHJdmfrXB
+ payment_method_id: pm_EfhxLZ9ck8
+ response_code:
+ number: R1002-P1
+ status: checkout
+ amount: '110.0'
+ display_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'
+ captured_amount: '0.0'
+ order_id: or_gbHJdmfrXB
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - payment_method_id
properties:
- name:
- type: string
- example: Sparks Audio Ltd
- billing_email:
- type: string
- nullable: true
- payouts_schedule_interval:
- type: string
- enum:
- - daily
- - weekly
- - biweekly
- - monthly
- - manual
- nullable: true
- minimum_payout_amount:
- type: string
- example: '25.0'
- nullable: true
- holiday_mode_until:
- type: string
- format: date-time
- nullable: true
- logo:
+ payment_method_id:
type: string
- nullable: true
- description: ActiveStorage signed id of a direct-uploaded file.
- Send `null` to remove the attachment, or omit the key to leave
- it alone. Same for `square_logo` and `cover_photo`.
- square_logo:
+ description: Payment method ID
+ amount:
type: string
- nullable: true
- cover_photo:
+ example: '99.99'
+ source_id:
type: string
- nullable: true
- billing_address:
- type: object
- description: The seller's own address, written inline. There is
- no `billing_address_id` — an address belongs to whoever it was
- created for, so it is never referenced by id here.
- properties:
- first_name:
- type: string
- example: Ada
- last_name:
- type: string
- example: Lovelace
- company:
- type: string
- example: Sparks Audio Ltd
- address1:
- type: string
- example: 1 Seller Way
- address2:
- type: string
- example: Unit 4
- city:
- type: string
- example: London
- postal_code:
- type: string
- example: EC1A 1BB
- phone:
- type: string
- example: "+44 20 7946 0000"
- country_code:
- type: string
- example: GB
- state_code:
- type: string
- example: NY
- state_name:
- type: string
- example: New York
- label:
- type: string
- example: Head office
- 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
- example: Ada
- last_name:
- type: string
- example: Lovelace
- company:
- type: string
- example: Sparks Audio Ltd
- address1:
- type: string
- example: 1 Seller Way
- address2:
- type: string
- example: Unit 4
- city:
- type: string
- example: London
- postal_code:
- type: string
- example: EC1A 1BB
- phone:
- type: string
- example: "+44 20 7946 0000"
- country_code:
- type: string
- example: GB
- state_code:
- type: string
- example: NY
- state_name:
- type: string
- example: New York
- label:
- type: string
- example: Head office
- delete:
- summary: Delete a seller
+ description: Payment source ID
+ "/api/v3/admin/orders/{order_id}/payments/{id}":
+ get:
+ summary: Show a payment
tags:
- - Sellers
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes the seller. Their products are kept and left without a
- seller rather than deleted — what happens to a departed seller's
- catalog is the operator's decision.
-
+ Returns details of a specific payment.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `read_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23259,12 +14996,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Soft-deletes the seller. Their products stay in the catalog without a
- // seller rather than being deleted with them.
- await client.sellers.delete('sel_UkLWZg9DAJ')
+ const payment = await client.orders.payments.get('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /sellers/{id}
+ source: spree api get /orders/{order_id}/payments/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -23274,37 +15009,84 @@ 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: 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:
- '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
+ '200':
+ description: payment found
+ content:
+ application/json:
+ example:
+ id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: BGS-4a236d40ef07
+ number: R1001-P1
+ status: completed
+ amount: '110.0'
+ display_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.0'
+ order_id: or_UkLWZg9DAJ
+ "/api/v3/admin/orders/{order_id}/payments/{id}/capture":
+ patch:
+ summary: Capture a payment
tags:
- - Sellers
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Sends an invitation to the seller's own team and moves the seller to
- `invited`. The person becomes a member when they accept, and can then
- sign in to the seller panel.
-
- `role_id` must name a role this seller owns; omit it for the seller's
- own admin role. Re-inviting is allowed — an invitation expires, or the
- first one goes to the wrong address.
-
+ Captures a pending payment.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `write_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23316,14 +15098,11 @@ paths:
secretKey: 'sk_xxx',
})
- // They join the seller's team when they accept, and can then sign in to the
- // seller panel. Omit `role_id` for the seller's own admin role.
- const seller = await client.sellers.invite('sel_UkLWZg9DAJ', {
- email: '[email protected]',
- })
+ const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api post /sellers/{id}/invite -d '{"email":"[email protected]"}'
+ source: spree api patch /orders/{order_id}/payments/{id}/capture -d '{ ...
+ }'
parameters:
- name: x-spree-api-key
in: header
@@ -23333,52 +15112,80 @@ 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: Payment ID
schema:
type: string
responses:
- '201':
- description: invitation sent
+ '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.0'
+ display_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.0'
+ 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/Seller"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- required:
- - email
- properties:
- email:
- type: string
- role_id:
- type: string
- example: role_UkLWZg9DAJ
- nullable: true
- "/api/v3/admin/sellers/{id}/approve":
- parameters:
- - name: id
- in: path
- required: true
- description: Seller prefixed ID
- schema:
- type: string
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/orders/{order_id}/payments/{id}/void":
patch:
- summary: Approve a seller
+ summary: Void a payment
tags:
- - Sellers
+ - Payments
security:
- api_key: []
bearer_auth: []
description: |-
- Lets the seller sell. This is also the way back for one that was
- suspended or turned down, and it clears any holiday along with the
- suspension.
-
+ Voids a payment.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `write_payments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23390,12 +15197,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Also the way back for a seller that was suspended or turned down — and it
- // clears any holiday along with the suspension.
- const seller = await client.sellers.approve('sel_UkLWZg9DAJ')
+ const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api patch /sellers/{id}/approve -d '{ ... }'
+ source: spree api patch /orders/{order_id}/payments/{id}/void -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -23405,44 +15210,70 @@ 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: Payment ID
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
+ description: payment voided
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
+ example:
+ id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: void-BGS-11f2e975ba0c
+ number: R1001-P1
+ status: void
+ amount: '110.0'
+ display_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.0'
+ order_id: or_UkLWZg9DAJ
+ "/api/v3/admin/price_lists":
+ get:
+ summary: List price lists
tags:
- - Sellers
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Stops a trading seller from selling. Their catalog and history stay,
- and approving reinstates them. Use this rather than `reject` for a
- seller already on the marketplace — it says something different, and
- it can be undone.
-
+ Returns the price lists configured for the current store.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `read_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23454,14 +15285,10 @@ paths:
secretKey: 'sk_xxx',
})
- // Stops a trading seller from selling. Their catalog and history stay, and
- // approving reinstates them.
- const seller = await client.sellers.suspend('sel_UkLWZg9DAJ', {
- reason: 'Counterfeit goods',
- })
+ const { data: priceLists } = await client.priceLists.list()
- lang: bash
label: Spree CLI
- source: spree api patch /sellers/{id}/suspend -d '{"reason":"Counterfeit goods"}'
+ source: spree api get /price_lists
parameters:
- name: x-spree-api-key
in: header
@@ -23473,43 +15300,111 @@ paths:
required: true
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ schema:
+ type: string
+ - name: q[status_eq]
+ in: query
+ required: false
+ schema:
+ type: string
+ - 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
responses:
'200':
- description: seller suspended
+ description: price lists found
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
+ - 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
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Seller"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- reason:
- type: string
- example: Counterfeit goods
- "/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
+ 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:
- - Sellers
+ - Pricing
security:
- api_key: []
bearer_auth: []
description: |-
- Turns down an applicant who never traded. A seller already selling is
- suspended instead; rejecting one is refused.
-
+ Creates a new draft price list.
- **Required scope:** `write_sellers` (for API-key authentication).
+ **Required scope:** `write_products` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -23521,14 +15416,45 @@ paths:
secretKey: 'sk_xxx',
})
- // For an applicant who never traded. A seller already selling is suspended
- // instead.
- const seller = await client.sellers.reject('sel_UkLWZg9DAJ', {
- reason: 'Incomplete paperwork',
+ // 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',
+ },
+ ],
})
- lang: bash
label: Spree CLI
- source: spree api patch /sellers/{id}/reject -d '{"reason":"Incomplete paperwork"}'
+ 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
@@ -23541,1485 +15467,17964 @@ paths:
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
- example: Incomplete paperwork
- "/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
- the installation has no admin user. Unauthenticated; the dashboard
- login page uses it to offer the setup screen.
- responses:
- '200':
- description: setup status
- content:
- application/json:
- example:
- setup_required: true
- post:
- summary: Complete first-run setup
- tags:
- - Authentication
- description: |
- Creates the first admin account and adopts the seeded store, authorized
- by the one-time setup token printed at install time (rotate it with
- `bin/rails spree:setup:token`). Issues a JWT access token and a
- refresh-token cookie exactly like login. Returns 404 once any admin
- user exists — the flow is closed permanently after setup.
- parameters: []
- responses:
- '200':
- description: setup completed
- content:
- application/json: {}
- '404':
- description: setup not available
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Setup is not available
- 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
- example: Secret123!
- password_confirmation:
- type: string
- example: Secret123!
- first_name:
- type: string
- example: Olivia
- last_name:
- type: string
- example: Owner
- store_name:
- type: string
- example: My Store
- 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.
- example: US
- locale:
- type: string
- description: Storefront locale. Defaults to the country's own language.
- example: en
- currency:
- type: string
- description: ISO 4217 currency. Defaults to the country's own currency
- — pass one only when the store prices in something else.
- example: USD
- "/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
- official languages derived from it. Unauthenticated, because the setup
- screen runs before any credential exists. Returns 404 once any admin
- user exists.
- responses:
- '200':
- description: countries
+ '201':
+ description: price list created (server-to-server — rules + prices)
content:
application/json:
example:
- countries:
- - code: AD
- name: Andorra
- currency: EUR
- locales:
- - ca
- - code: AE
- name: United Arab Emirates
- currency: AED
- locales:
- - ar
- - code: AF
- name: Afghanistan
- currency: AFN
- locales:
- - ps
- - uz
- - tk
- - code: AG
- name: Antigua and Barbuda
- currency: XCD
- locales:
- - en
- - code: AI
- name: Anguilla
- currency: XCD
- locales:
- - en
- - code: AL
- name: Albania
- currency: ALL
- locales:
- - sq
- - code: AM
- name: Armenia
- currency: AMD
- locales:
- - hy
- - code: AO
- name: Angola
- currency: AOA
- locales:
- - pt
- - code: AR
- name: Argentina
- currency: ARS
- locales:
- - es
- - gn
- - code: AS
- name: American Samoa
- currency: USD
- locales:
- - en
- - sm
- - code: AT
- name: Austria
- currency: EUR
- locales:
- - de
- - code: AU
- name: Australia
- currency: AUD
- locales:
- - en
- - code: AW
- name: Aruba
- currency: AWG
- locales:
- - nl
- - code: AZ
- name: Azerbaijan
- currency: AZN
- locales:
- - az
- - hy
- - code: BA
- name: Bosnia and Herzegovina
- currency: BAM
- locales:
- - bs
- - hr
- - sr
- - code: BB
- name: Barbados
- currency: BBD
- locales:
- - en
- - code: BD
- name: Bangladesh
- currency: BDT
- locales:
- - bn
- - code: BE
- name: Belgium
- currency: EUR
- locales:
- - nl
- - fr
- - de
- - code: BF
- name: Burkina Faso
- currency: XOF
- locales:
- - fr
- - ff
- - code: BG
- name: Bulgaria
- currency: EUR
- locales:
- - bg
- - code: BH
- name: Bahrain
- currency: BHD
- locales:
- - ar
- - code: BI
- name: Burundi
- currency: BIF
- locales:
- - fr
- - rn
- - code: BJ
- name: Benin
- currency: XOF
- locales:
- - fr
- - code: BL
- name: Saint Barthélemy
- currency: EUR
- locales:
- - fr
- - code: BM
- name: Bermuda
- currency: BMD
- locales:
- - en
- - code: BN
- name: Brunei Darussalam
- currency: BND
- locales:
- - ms
- - code: BO
- name: Bolivia
- currency: BOB
- locales:
- - es
- - ay
- - qu
- - code: BQ
- name: Bonaire, Sint Eustatius and Saba
- currency: USD
- locales:
- - nl
- - en
- - code: BR
- name: Brazil
- currency: BRL
- locales:
- - pt
- - code: BS
- name: Bahamas
- currency: BSD
- locales:
- - en
- - code: BT
- name: Bhutan
- currency: BTN
- locales:
- - dz
- - code: BW
- name: Botswana
- currency: BWP
- locales:
- - en
- - tn
- - code: BY
- name: Belarus
- currency: BYN
- locales:
- - be
- - ru
- - code: BZ
- name: Belize
- currency: BZD
- locales:
- - en
- - es
- - code: CA
- name: Canada
- currency: CAD
- locales:
- - en
- - fr
- - code: CC
- name: Cocos (Keeling) Islands
- currency: AUD
- locales:
- - en
- - code: CD
- name: Congo, The Democratic Republic of the
- currency: CDF
- locales:
- - fr
- - ln
- - kg
- - sw
- - lu
- - code: CF
- name: Central African Republic
- currency: XAF
- locales:
- - fr
- - sg
- - code: CG
- name: Congo
- currency: XAF
- locales:
- - fr
- - ln
- - code: CH
- name: Switzerland
- currency: CHF
- locales:
- - de
- - fr
- - it
- - rm
- - code: CI
- name: Côte d'Ivoire
- currency: XOF
- locales:
- - fr
- - code: CK
- name: Cook Islands
- currency: NZD
- locales:
- - en
- - code: CL
- name: Chile
- currency: CLP
- locales:
- - es
- - code: CM
- name: Cameroon
- currency: XAF
- locales:
- - en
- - fr
- - code: CN
- name: China
- currency: CNY
- locales:
- - zh
- - code: CO
- name: Colombia
- currency: COP
- locales:
- - es
- - code: CR
- name: Costa Rica
- currency: CRC
- locales:
- - es
- - code: CU
- name: Cuba
- currency: CUP
- locales:
- - es
- - code: CV
- name: Cabo Verde
- currency: CVE
- locales:
- - pt
- - code: CW
- name: Curaçao
- currency: XCG
- locales:
- - nl
- - code: CX
- name: Christmas Island
- currency: AUD
- locales:
- - en
- - zh
- - ms
- - code: CY
- name: Cyprus
- currency: EUR
- locales:
- - el
- - tr
- - hy
- - code: CZ
- name: Czechia
- currency: CZK
- locales:
- - cs
- - code: DE
- name: Germany
- currency: EUR
- locales:
- - de
- - code: DJ
- name: Djibouti
- currency: DJF
- locales:
- - ar
- - fr
- - code: DK
- name: Denmark
- currency: DKK
- locales:
- - da
- - code: DM
- name: Dominica
- currency: XCD
- locales:
- - en
- - code: DO
- name: Dominican Republic
- currency: DOP
- locales:
- - es
- - code: DZ
- name: Algeria
- currency: DZD
- locales:
- - ar
- - code: EC
- name: Ecuador
- currency: USD
- locales:
- - es
- - code: EE
- name: Estonia
- currency: EUR
- locales:
- - et
- - code: EG
- name: Egypt
- currency: EGP
- locales:
- - ar
- - code: ER
- name: Eritrea
- currency: ERN
- locales:
- - en
- - ar
- - ti
- - code: ES
- name: Spain
- currency: EUR
- locales:
- - es
- - code: ET
- name: Ethiopia
- currency: ETB
- locales:
- - am
- - code: FI
- name: Finland
- currency: EUR
- locales:
- - fi
- - sv
- - code: FJ
- name: Fiji
- currency: FJD
- locales:
- - en
- - fj
- - hi
- - code: FK
- name: Falkland Islands (Malvinas)
- currency: FKP
- locales:
- - en
- - code: FM
- name: Micronesia, Federated States of
- currency: USD
- locales:
- - en
- - code: FO
- name: Faroe Islands
- currency: DKK
- locales:
- - fo
- - code: FR
- name: France
- currency: EUR
- locales:
- - fr
- - code: GA
- name: Gabon
- currency: XAF
- locales:
- - fr
- - code: GB
- name: United Kingdom
- currency: GBP
- locales:
- - en
- - code: GD
- name: Grenada
- currency: XCD
- locales:
- - en
- - code: GE
- name: Georgia
- currency: GEL
- locales:
- - ka
- - code: GF
- name: French Guiana
- currency: EUR
- locales:
- - fr
- - code: GG
- name: Guernsey
- currency: GBP
- locales:
- - en
- - fr
- - code: GH
- name: Ghana
- currency: GHS
- locales:
- - en
- - code: GI
- name: Gibraltar
- currency: GIP
- locales:
- - en
- - code: GL
- name: Greenland
- currency: DKK
- locales:
- - kl
- - code: GM
- name: Gambia
- currency: GMD
- locales:
- - en
- - code: GN
- name: Guinea
- currency: GNF
- locales:
- - fr
- - ff
- - code: GP
- name: Guadeloupe
- currency: EUR
- locales:
- - fr
- - code: GQ
- name: Equatorial Guinea
- currency: XAF
- locales:
- - es
- - fr
- - code: GR
- name: Greece
- currency: EUR
- locales:
- - el
- - code: GT
- name: Guatemala
- currency: GTQ
- locales:
- - es
- - code: GU
- name: Guam
+ id: pl_EfhxLZ9ck8
+ name: EU wholesale
+ description:
+ status: draft
+ 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'
+ price_adjustment_percentage:
+ automatic_pricing: false
+ currently_active: false
+ products_count: 1
+ prices_count: 2
+ 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:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ example: EU wholesale
+ description:
+ type: string
+ nullable: true
+ starts_at:
+ type: string
+ nullable: true
+ example: '2026-06-01T00:00:00Z'
+ ends_at:
+ type: string
+ nullable: true
+ example: '2026-09-01T00:00:00Z'
+ match_policy:
+ 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
+ tags:
+ - Pricing
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**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 priceList = await client.priceLists.get('pl_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /price_lists/{id}
+ 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:
+ example:
+ 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
+ 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
+ tags:
+ - Pricing
+ 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.
+
+
+ **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 priceList = await client.priceLists.update('pl_xxx', {
+ name: 'Wholesale (Q3)',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /price_lists/{id} -d '{"name":"Wholesale (Q3)"}'
+ parameters:
+ - 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:
+ 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:
+ 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
+ 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
+ tags:
+ - Pricing
+ 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'
+
+ 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}
+ 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
+ in the future the list is marked `scheduled` instead, matching the
+ legacy admin behaviour.
+
+
+ **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 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
+ 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'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ 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
+ responses:
+ '200':
+ description: price list deactivated
+ 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
+ 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
+ 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',
+ })
+
+ 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"]}'
+ 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
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: q[price_list_id_eq]
+ in: query
+ required: false
+ schema:
+ type: string
+ - name: q[price_list_id_null]
+ in: query
+ required: false
+ schema:
+ type: boolean
+ - name: q[currency_eq]
+ in: query
+ required: false
+ schema:
+ type: string
+ - name: q[variant_id_eq]
+ in: query
+ required: false
+ schema:
+ type: string
+ - 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
+ responses:
+ '200':
+ description: prices found
+ content:
+ application/json:
+ example:
+ data:
+ - id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
currency: USD
- locales:
- - en
- - ch
- - es
- - code: GW
- name: Guinea-Bissau
- currency: XOF
- locales:
- - pt
- - code: GY
- name: Guyana
- currency: GYD
- locales:
- - en
- - code: HK
- name: Hong Kong
- currency: HKD
- locales:
- - en
- - zh
- - code: HN
- name: Honduras
- currency: HNL
- locales:
- - es
- - code: HR
- name: Croatia
- currency: EUR
- locales:
- - hr
- - code: HT
- name: Haiti
- currency: HTG
- locales:
- - fr
- - ht
- - code: HU
- name: Hungary
- currency: HUF
- locales:
- - hu
- - code: ID
- name: Indonesia
- currency: IDR
- locales:
- - id
- - code: IE
- name: Ireland
- currency: EUR
- locales:
- - en
- - ga
- - code: IL
- name: Israel
- currency: ILS
- locales:
- - he
- - ar
- - code: IM
- name: Isle of Man
- currency: GBP
- locales:
- - en
- - gv
- - code: IN
- name: India
- currency: INR
- locales:
- - hi
- - en
- - code: IQ
- name: Iraq
- currency: IQD
- locales:
- - ar
- - code: IR
- name: Iran
- currency: IRR
- locales:
- - fa
- - code: IS
- name: Iceland
- currency: ISK
- locales:
- - is
- - code: IT
- name: Italy
- currency: EUR
- locales:
- - it
- - code: JE
- name: Jersey
- currency: GBP
- locales:
- - en
- - fr
- - code: JM
- name: Jamaica
- currency: JMD
- locales:
- - en
- - code: JO
- name: Jordan
- currency: JOD
- locales:
- - ar
- - code: JP
- name: Japan
- currency: JPY
- locales:
- - ja
- - code: KE
- name: Kenya
- currency: KES
- locales:
- - en
- - sw
- - code: KG
- name: Kyrgyzstan
- currency: KGS
- locales:
- - ky
- - ru
- - code: KH
- name: Cambodia
- currency: KHR
- locales:
- - km
- - code: KI
- name: Kiribati
- currency: AUD
- locales:
- - en
- - code: KM
- name: Comoros
- currency: KMF
- locales:
- - ar
- - fr
- - code: KN
- name: Saint Kitts and Nevis
- currency: XCD
- locales:
- - en
- - code: KP
- name: North Korea
- currency: KPW
- locales:
- - ko
- - code: KR
- name: South Korea
- currency: KRW
- locales:
- - ko
- - code: KW
- name: Kuwait
- currency: KWD
- locales:
- - ar
- - code: KY
- name: Cayman Islands
- currency: KYD
- locales:
- - en
- - code: KZ
- name: Kazakhstan
- currency: KZT
- locales:
- - kk
- - ru
- - code: LA
- name: Lao People's Democratic Republic
- currency: LAK
- locales:
- - lo
- - code: LB
- name: Lebanon
- currency: LBP
- locales:
- - ar
- - fr
- - code: LC
- name: Saint Lucia
- currency: XCD
- locales:
- - en
- - code: LI
- name: Liechtenstein
- currency: CHF
- locales:
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ variant_id: variant_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: price_gbHJdmfrXB
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ variant_id: variant_gbHJdmfrXB
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: price_EfhxLZ9ck8
+ amount: '5.0'
+ amount_in_cents: 500
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$5.00"
+ display_compare_at_amount:
+ price_list_id: pl_UkLWZg9DAJ
+ 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: Create a price
+ tags:
+ - Pricing
+ 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',
+ })
+
+ 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: price created
+ content:
+ application/json:
+ example:
+ id: price_uw2YK1rnl0
+ amount: '9.99'
+ amount_in_cents: 999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: EUR
+ display_amount: "€9.99"
+ display_compare_at_amount:
+ price_list_id:
+ variant_id: variant_EfhxLZ9ck8
+ 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
+ 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
+ get:
+ summary: Get a price
+ tags:
+ - Pricing
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**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 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: price found
+ content:
+ application/json:
+ example:
+ id: price_EfhxLZ9ck8
+ amount: '5.0'
+ amount_in_cents: 500
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$5.00"
+ display_compare_at_amount:
+ price_list_id: pl_UkLWZg9DAJ
+ 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:
+ - 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'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const price = await client.prices.update('price_xxx', {
+ amount: '12.34',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /prices/{id} -d '{"amount":"12.34"}'
+ parameters:
+ - 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:
+ example:
+ id: price_EfhxLZ9ck8
+ amount: '12.34'
+ amount_in_cents: 1234
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$12.34"
+ display_compare_at_amount:
+ price_list_id: pl_UkLWZg9DAJ
+ 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
+ tags:
+ - Pricing
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Soft-deletes the price (acts_as_paranoid).
+
+ **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',
+ })
+
+ await client.prices.delete('price_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /prices/{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: 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.
+
+ 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:
+ - 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.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 /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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ 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
+ 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 fields found
+ content:
+ application/json:
+ example:
+ data:
+ - id: cf_UkLWZg9DAJ
+ label: Title
+ type: Spree::CustomFields::ShortText
+ 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:
+ 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.
+
+ **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 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 /products/{product_id}/custom_fields -d '{"custom_field_definition_id":"cfdef_AbC123XyZ","value":"wool"}'
+ 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:
+ example:
+ id: cf_gbHJdmfrXB
+ label: Description
+ type: Spree::CustomFields::LongText
+ field_type: long_text
+ key: custom.description
+ value: A longer description
+ 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:
+ - has already been taken
+ 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)."
+ 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 customField = await client.products.customFields.get('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /products/{product_id}/custom_fields/{id}
+ 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:
+ example:
+ id: cf_UkLWZg9DAJ
+ label: Title
+ type: Spree::CustomFields::ShortText
+ 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
+ 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.
+
+ **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 customField = await client.products.customFields.update('prod_UkLWZg9DAJ', 'cf_AbC123XyZ', {
+ value: 'cotton',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /products/{product_id}/custom_fields/{id} -d '{"value":"cotton"}'
+ 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:
+ example:
+ id: cf_UkLWZg9DAJ
+ label: Title
+ type: Spree::CustomFields::ShortText
+ field_type: short_text
+ key: custom.title
+ value: cotton
+ 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
+ tags:
+ - Products
+ 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'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ await client.products.customFields.delete('prod_UkLWZg9DAJ', 'cf_AbC123XyZ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /products/{product_id}/custom_fields/{id}
+ 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.
+
+ **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:
+ 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
- - code: LK
- name: Sri Lanka
- currency: LKR
- locales:
- - si
- - ta
- - code: LR
- name: Liberia
- currency: LRD
- locales:
- - en
- - code: LS
- name: Lesotho
- currency: LSL
- locales:
- en
- - st
- - code: LT
- name: Lithuania
- currency: EUR
- locales:
- - lt
- - code: LU
- name: Luxembourg
- currency: EUR
+ - 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({
+ name_cont: 'shirt',
+ status_eq: 'active',
+ sort: '-created_at',
+ limit: 25,
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /products -d '{"name_cont":"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: 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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[status_eq]
+ in: query
+ required: false
+ description: Filter by status
+ schema:
+ type: string
+ responses:
+ '200':
+ description: products found
+ content:
+ application/json:
+ example:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 1016550
+ slug: product-1016550
+ 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
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ 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'
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id: taxcat_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/Product"
+ 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
+ tags:
+ - Products
+ 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.
+
+
+ **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 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 /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
+ 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:
+ 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
+ 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'
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id:
+ 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:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ 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 product
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns a single product by 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',
+ })
+
+ const product = await client.products.get('prod_86Rf07xd4z', {
+ expand: ['variants', 'option_types'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /products/{id} -d '{"expand":["variants","option_types"]}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: prod_UkLWZg9DAJ
+ name: Product 1052061
+ slug: product-1052061
+ 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
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ 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'
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id: taxcat_UkLWZg9DAJ
+ schema:
+ "$ref": "#/components/schemas/Product"
+ '404':
+ description: product not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Product not found
+ 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.
+
+ **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 product = await client.products.update('prod_86Rf07xd4z', {
+ name: 'Updated Name',
+ status: 'active',
+ tags: ['eco', 'sale'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /products/{id} -d '{"name":"Updated Name","status":"active","tags":["eco","sale"]}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: prod_UkLWZg9DAJ
+ name: Updated Name
+ slug: product-1075339
+ 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
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ 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'
+ 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:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ 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
+ delete:
+ summary: Delete a product
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Soft-deletes a product.
+
+ **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',
+ })
+
+ await client.products.delete('prod_86Rf07xd4z')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /products/{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: 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:
+ - This product is under an active supplier contract.
+ 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
+ for search. Cross-store IDs are silently dropped. Returns counts.
+
+
+ **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.bulkStatusUpdate({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ status: 'archived',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /products/bulk_status_update -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"],"status":"archived"}'
+ parameters:
+ - 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:
+ example:
+ 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: 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: 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`.
+ Categories from sibling stores are silently ignored.
+
+
+ **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.bulkAddToCategories({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ category_ids: ['cat_AbC123XyZ'],
+ })
+ - lang: bash
+ label: Spree CLI
+ 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: products added to categories
+ content:
+ application/json:
+ example:
+ product_count: 1
+ category_count: 1
+ 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`.
+
+ **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.bulkRemoveFromCategories({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ category_ids: ['cat_AbC123XyZ'],
+ })
+ - lang: bash
+ label: Spree CLI
+ 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: products removed from categories
+ 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":
+ 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`.
+ Automatic (rule-based) and sibling-store collections are silently ignored.
+
+
+ **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:
+ example:
+ 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:
+ 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`.
+
+ **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:
+ 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:
+ - Products
+ 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).
+ 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.bulkAddToChannels({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ channel_ids: ['channel_AbC123XyZ'],
+ })
+ - lang: bash
+ label: Spree CLI
+ 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: products published on channels
+ content:
+ application/json:
+ example:
+ product_count: 1
+ channel_count: 1
+ 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`.
+
+ **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.bulkRemoveFromChannels({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ channel_ids: ['channel_AbC123XyZ'],
+ })
+ - lang: bash
+ label: Spree CLI
+ 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ 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":
+ 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.
+
+ **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.bulkAddTags({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ tags: ['summer', 'sale'],
+ })
+ - lang: bash
+ label: Spree CLI
+ 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: tags added
+ content:
+ application/json:
+ example:
+ product_count: 1
+ tag_count: 2
+ 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
+ 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
+ content:
+ application/json:
+ example:
+ product_count: 1
+ tag_count: 1
+ 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.
+
+ **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.bulkDestroy({
+ ids: ['prod_UkLWZg9DAJ', 'prod_9XbR2kQwLm'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /products/bulk_destroy -d '{"ids":["prod_UkLWZg9DAJ","prod_9XbR2kQwLm"]}'
+ parameters:
+ - 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:
+ 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: 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.
+
+ **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:
- - fr
- de
- - lb
- - code: LV
- name: Latvia
- currency: EUR
- locales:
- - lv
- - code: LY
- name: Libya
- currency: LYD
- locales:
- - ar
- - code: MA
- name: Morocco
- currency: MAD
- locales:
- - ar
- - code: MC
- name: Monaco
- currency: EUR
- locales:
- - fr
- - code: MD
- name: Moldova
- currency: MDL
- locales:
- - ro
- - code: ME
- name: Montenegro
- currency: EUR
- locales:
- - sr
- - bs
- - sq
- - hr
- - code: MF
- name: Saint Martin (French part)
- currency: EUR
- locales:
- - en
- - fr
- - nl
- - code: MG
- name: Madagascar
- currency: MGA
- locales:
- - fr
- - mg
- - code: MH
- name: Marshall Islands
- currency: USD
- locales:
- - en
- - mh
- - code: MK
- name: North Macedonia
- currency: MKD
- locales:
- - mk
- - code: ML
- name: Mali
- currency: XOF
- locales:
- - fr
- - code: MM
- name: Myanmar
- currency: MMK
- locales:
- - my
- - code: MN
- name: Mongolia
- currency: MNT
- locales:
- - mn
- - code: MO
- name: Macao
- currency: MOP
- locales:
- - zh
- - pt
- - code: MP
- name: Northern Mariana Islands
- currency: USD
- locales:
- - en
- - ch
- - code: MQ
- name: Martinique
- currency: EUR
- locales:
- - fr
- - code: MR
- name: Mauritania
- currency: MRU
- locales:
- - ar
- - fr
- - code: MS
- name: Montserrat
- currency: XCD
- locales:
- - en
- - code: MT
- name: Malta
- currency: EUR
- locales:
- - mt
- - en
- - code: MU
- name: Mauritius
- currency: MUR
- locales:
- - en
- - code: MV
- name: Maldives
- currency: MVR
- locales:
- - dv
- - code: MW
- name: Malawi
- currency: MWK
- locales:
- - en
- - ny
- - code: MX
- name: Mexico
- currency: MXN
- locales:
- - es
- - code: MY
- name: Malaysia
- currency: MYR
- locales:
- - ms
- - en
- - code: MZ
- name: Mozambique
- currency: MZN
- locales:
- - pt
- - code: NA
- name: Namibia
- currency: NAD
- locales:
- - en
- - af
- - code: NC
- name: New Caledonia
- currency: XPF
- locales:
- - fr
- - code: NE
- name: Niger
- currency: XOF
- locales:
- - fr
- - code: NF
- name: Norfolk Island
- currency: AUD
- locales:
- - en
- - code: NG
- name: Nigeria
- currency: NGN
- locales:
- - en
- - code: NI
- name: Nicaragua
- currency: NIO
- locales:
- - es
- - code: NL
- name: Netherlands
- currency: EUR
- locales:
- - nl
- - code: 'NO'
- name: Norway
- currency: NOK
- locales:
- - nb
- - nn
- - code: NP
- name: Nepal
- currency: NPR
- locales:
- - ne
- - code: NR
- name: Nauru
- currency: AUD
- locales:
- - en
- - na
- - code: NU
- name: Niue
- currency: NZD
- locales:
- - en
- - code: NZ
- name: New Zealand
- currency: NZD
- locales:
- - en
- - code: OM
- name: Oman
- currency: OMR
- locales:
- - ar
- - code: PA
- name: Panama
- currency: PAB
- locales:
- - es
- - code: PE
- name: Peru
- currency: PEN
- locales:
- - es
- - code: PF
- name: French Polynesia
- currency: XPF
- locales:
- - fr
- - code: PG
- name: Papua New Guinea
- currency: PGK
- locales:
- - en
- - code: PH
- name: Philippines
- currency: PHP
- locales:
- - tl
- - en
- - code: PK
- name: Pakistan
- currency: PKR
- locales:
- - en
- - ur
- - code: PL
- name: Poland
- currency: PLN
- locales:
- - pl
- - code: PM
- name: Saint Pierre and Miquelon
- currency: EUR
- locales:
- - fr
- - code: PN
- name: Pitcairn
- currency: NZD
- locales:
- - en
- - code: PR
- name: Puerto Rico
- currency: USD
- locales:
- - es
- - en
- - code: PS
- name: Palestine, State of
- currency: ILS
- locales:
- - ar
- - he
- - en
- - code: PT
- name: Portugal
- currency: EUR
- locales:
- - pt
- - code: PW
- name: Palau
- currency: USD
- locales:
- - en
- - code: PY
- name: Paraguay
- currency: PYG
- locales:
- - es
- - gn
- - code: QA
- name: Qatar
- currency: QAR
- locales:
- - ar
- - code: RE
- name: Réunion
+ 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
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: policies } = await client.policies.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /policies
+ parameters:
+ - name: x-spree-api-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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ 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: policies listed
+ 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'
+ 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: 5
+ pages: 1
+ from: 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 a policy
+ tags:
+ - Policies
+ 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.
+
+
+ **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 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 /policies -d '{"name":"Wholesale Policy","body":"<p>Trade
+ orders ship within five working days.</p>"}'
+ parameters:
+ - name: x-spree-api-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:
+ 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'
+ created_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Policy"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Wholesale Policy
+ slug:
+ type: string
+ example: wholesale-policy
+ body:
+ 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
+ get:
+ summary: Get a policy
+ tags:
+ - Policies
+ 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).
+ 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',
+ })
+
+ // Addressable by slug as well as prefixed id.
+ const policy = await client.policies.get('returns-policy')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /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:
+ '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:
+ - Policies
+ security:
+ - api_key: []
+ bearer_auth: []
+ 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
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ 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 patch /policies/{id} -d '{"body":"<p>Return anything unopened
+ within 60 days.</p>"}'
+ parameters:
+ - name: x-spree-api-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:
+ 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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[active_eq]
+ in: query
+ required: false
+ description: Filter by active flag
+ schema:
+ type: boolean
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ schema:
+ type: string
+ responses:
+ '200':
+ description: claim reasons found
+ content:
+ application/json:
+ example:
+ data:
+ - 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
+ 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 claim reason
+ tags:
+ - Reasons
+ 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',
+ })
+
+ const reason = await client.claimReasons.create({
+ name: 'Arrived damaged',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /claim_reasons -d '{"name":"Arrived damaged"}'
+ parameters:
+ - name: x-spree-api-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:
+ 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:
+ - can't be blank
+ 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
+ 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 claim reason
+ tags:
+ - Reasons
+ 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.
+
+
+ **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 reason = await client.claimReasons.update('clr_UkLWZg9DAJ', {
+ active: false,
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /claim_reasons/{id} -d '{"active":false}'
+ parameters:
+ - name: x-spree-api-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:
+ 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
+ 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.
+
+ 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
+ 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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[active_eq]
+ in: query
+ required: false
+ description: Filter by active flag
+ schema:
+ type: boolean
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ schema:
+ type: string
+ responses:
+ '200':
+ description: order cancellation reasons found
+ content:
+ application/json:
+ example:
+ data:
+ - 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'
+ 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 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.
+
+ **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 reason = await client.orderCancellationReasons.create({
+ name: 'Out of stock',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /order_cancellation_reasons -d '{"name":"Out of stock"}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ 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'
+ can_be_deleted: true
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ 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
+ get:
+ summary: Get a order cancellation reason
+ tags:
+ - Reasons
+ security:
+ - api_key: []
+ bearer_auth: []
+ 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
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const reason = await client.orderCancellationReasons.get('ocr_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /order_cancellation_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: order cancellation reason found
+ content:
+ application/json:
+ example:
+ 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'
+ 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 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
+ 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'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const reason = await client.orderCancellationReasons.update('ocr_UkLWZg9DAJ', {
+ active: false,
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /order_cancellation_reasons/{id} -d '{"active":false}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ 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'
+ can_be_deleted: true
+ 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
+ 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.orderCancellationReasons.delete('ocr_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /order_cancellation_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:
+ '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.
+
+ 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.refundReasons.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /refund_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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[active_eq]
+ in: query
+ required: false
+ description: Filter by active flag
+ schema:
+ type: boolean
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ schema:
+ type: string
+ responses:
+ '200':
+ description: refund reasons found
+ 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
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ 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.
+
+ **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 reason = await client.refundReasons.create({
+ name: 'Goodwill gesture',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /refund_reasons -d '{"name":"Goodwill gesture"}'
+ parameters:
+ - name: x-spree-api-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:
+ 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
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ 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: Get a refund reason
+ tags:
+ - Reasons
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns a single refund 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.refundReasons.get('rr_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /refund_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: 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
+ 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:
+ - Reasons
+ 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'
+
+ 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}'
+ parameters:
+ - name: x-spree-api-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:
+ 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
+ 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
+ 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.refundReasons.delete('rr_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /refund_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:
+ '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.
+
+ 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.returnReasons.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /return_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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[active_eq]
+ in: query
+ required: false
+ description: Filter by active flag
+ schema:
+ type: boolean
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ schema:
+ type: string
+ 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:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ 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.
+
+ **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 reason = await client.returnReasons.create({
+ name: 'Damaged in transit',
+ })
+ - lang: bash
+ label: Spree CLI
+ 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:
+ - can't be blank
+ 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
+ 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:
+ 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
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Return reason not found
+ 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
+ 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'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const reason = await client.returnReasons.update('rar_UkLWZg9DAJ', {
+ active: false,
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /return_reasons/{id} -d '{"active":false}'
+ parameters:
+ - name: x-spree-api-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:
+ 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
+ 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
+ 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.returnReasons.delete('rar_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /return_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:
+ '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
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: coupon codes 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:
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
+ "/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)."
+ 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: actions found
+ content:
+ application/json:
+ example:
+ 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: {}
+ preference_schema: []
+ label: Free shipping
+ 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:
+ - 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`). Fully-qualified Ruby class names are also accepted for backward compatibility.
+
+ **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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: action created
+ content:
+ application/json:
+ example:
+ 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: {}
+ preference_schema: []
+ label: Free shipping
+ 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:
+ type:
+ type: string
+ 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 an action from a promotion
+ tags:
+ - Promotions
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**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',
+ })
+
+ 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
+ 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)."
+ 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: 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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: rules found
+ content:
+ application/json:
+ example:
+ data:
+ - 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
+ preference_schema:
+ - key: currency
+ type: string
+ default:
+ label: Currency
+ 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: 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`). Fully-qualified Ruby class names are also accepted for backward compatibility.
+
+ **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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: rule created with preferences
+ content:
+ application/json:
+ example:
+ 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
- locales:
- - fr
- - code: RO
- name: Romania
- currency: RON
- locales:
- - ro
- - code: RS
- name: Serbia
- currency: RSD
- locales:
- - sr
- - code: RU
- name: Russian Federation
- currency: RUB
- locales:
- - ru
- - code: RW
- name: Rwanda
- currency: RWF
- locales:
- - rw
- - en
- - fr
- - code: SA
- name: Saudi Arabia
- currency: SAR
- locales:
- - ar
- - code: SB
- name: Solomon Islands
- currency: SBD
- locales:
+ preference_schema:
+ - key: currency
+ type: string
+ default:
+ label: Currency
+ product_ids:
+ category_ids:
+ customer_ids:
+ option_value_ids:
+ '422':
+ description: unknown rule type
+ content:
+ application/json:
+ example:
+ error:
+ code: unknown_promotion_rule_type
+ message: Unknown type
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ 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 rule's preferences
+ tags:
+ - Promotions
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**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.update('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq', {
+ preferences: { currency: 'USD' },
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /promotions/{promotion_id}/promotion_rules/{id} -d
+ '{"preferences":{"currency":"USD"}}'
+ parameters:
+ - 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:
+ example:
+ 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: GBP
+ preference_schema:
+ - key: currency
+ type: string
+ default:
+ label: Currency
+ product_ids:
+ category_ids:
+ customer_ids:
+ option_value_ids:
+ 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)."
+ 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.promotions.rules.delete('promo_UkLWZg9DAJ', 'promorule_k5nR8xLq')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /promotions/{promotion_id}/promotion_rules/{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: 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.
+
+ **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: promotions } = await client.promotions.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /promotions
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: promotions 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: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ action_ids: []
+ rule_ids: []
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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;
+ 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.
+
+
+ **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',
+ })
+
+ // 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, 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 /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
+ 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:
+ 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: {}
+ 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
+ '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:
+ - can't be blank
+ code:
+ - can't be blank
+ 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
+ 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:
+ - Promotions
+ security:
+ - api_key: []
+ bearer_auth: []
+ 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 promotion = await client.promotions.get('promo_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /promotions/{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: 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:
+ - Promotions
+ 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.
+
+
+ **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',
+ })
+
+ // 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, 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 patch /promotions/{id} -d '{"description":"Updated description"}'
+ 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:
+ 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: []
+ 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:
+ - Promotions
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**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',
+ })
+
+ await client.promotions.delete('promo_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /promotions/{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: 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: action types found
+ content:
+ application/json:
+ example:
+ data:
+ - type: create_line_items
+ label: Create line items
+ description:
+ preference_schema: []
+ - type: create_item_adjustments
+ label: Create per-line-item adjustment
+ description:
+ preference_schema: []
+ - type: create_adjustment
+ label: Create whole-order adjustment
+ description:
+ preference_schema: []
+ - type: free_shipping
+ label: Free shipping
+ description:
+ preference_schema: []
+ "/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.
+
+ **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: ruleTypes } = await client.promotionRules.types()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /promotion_rules/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: rule types found
+ content:
+ application/json:
+ example:
+ data:
+ - type: category
+ label: Categories
+ description:
+ preference_schema:
+ - key: match_policy
+ type: string
+ default: any
+ - type: channel
+ label: Channel(s)
+ description:
+ preference_schema:
+ - key: channel_ids
+ type: array
+ default: []
+ - type: country
+ label: Country
+ description:
+ preference_schema:
+ - key: country_codes
+ type: array
+ default: []
+ - key: country_id
+ type: integer
+ default:
+ - key: country_code
+ type: string
+ default:
+ - type: currency
+ label: Currency
+ description:
+ preference_schema:
+ - key: currency
+ type: string
+ default:
+ - type: customer_group
+ label: Customer Group(s)
+ description:
+ preference_schema:
+ - key: customer_group_ids
+ type: array
+ default: []
+ - type: customer
+ label: Customers
+ description:
+ preference_schema: []
+ - type: first_order
+ label: First order
+ description:
+ preference_schema: []
+ - type: item_total
+ label: Item total
+ description:
+ preference_schema:
+ - key: amount_min
+ type: decimal
+ default: 100.0
+ - key: operator_min
+ type: string
+ default: ">"
+ - key: amount_max
+ type: decimal
+ default:
+ - key: operator_max
+ type: string
+ default: "<"
+ - type: market
+ label: Market(s)
+ description:
+ preference_schema:
+ - key: market_ids
+ type: array
+ default: []
+ - type: one_use_per_user
+ label: One Use Per User
+ description:
+ preference_schema: []
+ - type: customer_logged_in
+ label: Only logged in customers
+ description:
+ preference_schema: []
+ - type: option_value
+ label: Option Value(s)
+ description:
+ preference_schema:
+ - key: eligible_values
+ type: array
+ default: []
+ - key: match_policy
+ type: string
+ default: any
+ - type: product
+ label: Product(s)
+ description:
+ preference_schema:
+ - key: match_policy
+ type: string
+ default: any
+ "/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
+ 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: 'refrsn_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":"refrsn_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.0'
+ 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'
+ 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: de
+ default: false
+ rtl: false
+ - code: en
+ name: English
+ default: true
+ rtl: false
+ - code: fr
+ name: fr
+ 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
+ preferred_storefront_url:
+ 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]
+ preferred_send_consumer_transactional_emails: true
+ preferred_admin_locale:
+ preferred_timezone: UTC
+ preferred_weight_unit: lb
+ preferred_default_package_weight: 0
+ preferred_default_package_length: 0
+ preferred_default_package_width: 0
+ preferred_default_package_height: 0
+ preferred_unit_system: imperial
+ preferred_storefront_access: public
+ preferred_guest_checkout: true
+ preferred_company_field_enabled: false
+ preferred_address_requires_company: false
+ preferred_address_requires_phone: false
+ preferred_capture_method: checkout
+ preferred_track_inventory_levels: true
+ preferred_stock_reservations_enabled: true
+ preferred_tax_using_ship_address: true
+ preferred_track_price_history: true
+ preferred_show_products_without_price: false
+ preferred_disable_sku_validation: false
+ preferred_order_routing_strategy: Spree::OrderRouting::Strategy::Rules
+ preferred_pricing_provider: internal
+ preferred_inventory_provider: internal
+ preferred_pricing_provider_failure_policy: strict
+ preferred_inventory_provider_failure_policy: fallback
+ preferred_payout_provider:
+ preferred_default_payouts_schedule_interval: monthly
+ preferred_default_minimum_payout_amount: 0
+ preferred_document_number_format: sequential
+ preferred_order_number_prefix: R
+ preferred_order_number_suffix: ''
+ preferred_order_number_sequence_start: 1001
+ preferred_limit_digital_download_count: true
+ preferred_digital_asset_authorized_clicks: 5
+ preferred_limit_digital_download_days: true
+ preferred_digital_asset_authorized_days: 7
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_number_sequence_started: false
+ url: http://www.example.com:3000
+ api_url: http://www.example.com:3000
+ setup_tasks:
+ - 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
+ preferred_storefront_url:
+ 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]
+ preferred_send_consumer_transactional_emails: true
+ preferred_admin_locale:
+ preferred_timezone: UTC
+ preferred_weight_unit: lb
+ preferred_default_package_weight: 0
+ preferred_default_package_length: 0
+ preferred_default_package_width: 0
+ preferred_default_package_height: 0
+ preferred_unit_system: imperial
+ preferred_storefront_access: public
+ preferred_guest_checkout: true
+ preferred_company_field_enabled: false
+ preferred_address_requires_company: false
+ preferred_address_requires_phone: false
+ preferred_capture_method: checkout
+ preferred_track_inventory_levels: true
+ preferred_stock_reservations_enabled: true
+ preferred_tax_using_ship_address: true
+ preferred_track_price_history: true
+ preferred_show_products_without_price: false
+ preferred_disable_sku_validation: false
+ preferred_order_routing_strategy: Spree::OrderRouting::Strategy::Rules
+ preferred_pricing_provider: internal
+ preferred_inventory_provider: internal
+ preferred_pricing_provider_failure_policy: strict
+ preferred_inventory_provider_failure_policy: fallback
+ preferred_payout_provider:
+ preferred_default_payouts_schedule_interval: monthly
+ preferred_default_minimum_payout_amount: 0
+ preferred_document_number_format: sequential
+ preferred_order_number_prefix: R
+ preferred_order_number_suffix: ''
+ preferred_order_number_sequence_start: 1001
+ preferred_limit_digital_download_count: true
+ preferred_digital_asset_authorized_clicks: 5
+ preferred_limit_digital_download_days: true
+ preferred_digital_asset_authorized_days: 7
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ order_number_sequence_started: false
+ url: http://www.example.com:3000
+ api_url: http://www.example.com:3000
+ setup_tasks:
+ - 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:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: My Store
+ preferred_admin_locale:
+ type: string
+ example: en
+ preferred_timezone:
+ type: string
+ example: UTC
+ preferred_weight_unit:
+ type: string
+ example: kg
+ preferred_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: 'Spree::User',
+ q: 'vip',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /tags -d '{"taggable_type":"Spree::User","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: Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)
+ 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 Spree::Product, Spree::Order,
+ Spree::Customer
+ "/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: 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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[included_in_price_true]
+ in: query
+ required: false
+ description: Only rates included in the product price
+ schema:
+ type: boolean
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ schema:
+ type: string
+ 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:
+ amount: '0.19'
+ amount_percentage: 19.0
+ 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 `amount` as a
+ decimal (`0.19`) or `amount_percentage` as a percentage (`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:
+ amount: '0.19'
+ amount_percentage: 19.0
+ 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:
+ - must exist
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ description: Customer-facing rate name, e.g. "VAT"
+ amount:
+ type: string
+ description: Rate as a decimal, e.g. "0.19"
+ amount_percentage:
+ type: number
+ description: Rate as a percentage, 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:
+ amount: '0.19'
+ amount_percentage: 19.0
+ 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:
+ amount: '0.07'
+ amount_percentage: 7.0
+ 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
+ amount:
+ type: string
+ amount_percentage:
+ type: number
+ 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
- - code: SC
- name: Seychelles
- currency: SCR
- locales:
- 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
- - code: SD
- name: Sudan
- currency: SDG
- locales:
- - ar
- - en
- - code: SE
- name: Sweden
- currency: SEK
- locales:
- - sv
- - code: SG
- name: Singapore
- currency: SGD
- locales:
- - en
- - ms
- - ta
- - code: SH
- name: Saint Helena, Ascension and Tristan da Cunha
- currency: SHP
- locales:
- - en
- - code: SI
- name: Slovenia
- currency: EUR
- locales:
- - sl
- - code: SJ
- name: Svalbard and Jan Mayen
- currency: NOK
- locales:
- - 'no'
- - code: SK
- name: Slovakia
- currency: EUR
- locales:
- - sk
- - code: SL
- name: Sierra Leone
- currency: SLE
- locales:
- - en
- - code: SM
- name: San Marino
- currency: EUR
- locales:
- - it
- - code: SN
- name: Senegal
- currency: XOF
- locales:
- fr
- - code: SO
- name: Somalia
- currency: SOS
- locales:
- - so
- - ar
- - code: SR
- name: Suriname
- currency: SRD
- locales:
- - nl
- - code: SS
- name: South Sudan
- currency: SSP
- locales:
- - ar
- - en
- - code: ST
- name: Sao Tome and Principe
- currency: STN
- locales:
- - pt
- - code: SV
- name: El Salvador
+ '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
+ 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.
+
+ **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
+ 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]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=bcFtaxxWh2f6dkZb6EQNpKhJ"
+ 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]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=VVL8HRJRDHaZmJ4pQEhtz6ey"
+ 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/{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]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=FxDpzwwoQd483CL8xLvY7u6R"
+ 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_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
+ resource: fulfillments
+ kind: write
+ group: orders
+ group_label: Orders
+ label: Fulfillments
+ description: Pack, ship and track order fulfillments
+ - key: read_refunds
+ resource: refunds
+ kind: read
+ group: orders
+ group_label: Orders
+ label: Refunds
+ description: Issue and view refunds
+ - key: write_refunds
+ resource: refunds
+ kind: write
+ group: orders
+ group_label: Orders
+ label: Refunds
+ description: Issue and view refunds
+ - key: read_gift_cards
+ resource: gift_cards
+ kind: read
+ group: orders
+ group_label: Orders
+ label: Gift cards
+ description: Gift cards and gift card batches
+ - key: write_gift_cards
+ resource: gift_cards
+ kind: write
+ group: orders
+ group_label: Orders
+ label: Gift cards
+ description: Gift cards and gift card batches
+ - key: read_store_credits
+ resource: store_credits
+ kind: read
+ group: orders
+ group_label: Orders
+ label: Store credits
+ description: Customer store credit balances
+ - key: write_store_credits
+ resource: store_credits
+ kind: write
+ group: orders
+ group_label: Orders
+ label: Store credits
+ description: Customer store credit balances
+ - key: read_products
+ resource: products
+ kind: read
+ group: catalog
+ group_label: Catalog
+ label: Products
+ description: Products, variants, options, prices and media
+ - key: write_products
+ resource: products
+ kind: write
+ group: catalog
+ group_label: Catalog
+ label: Products
+ description: Products, variants, options, prices and media
+ - key: read_product_types
+ resource: product_types
+ kind: read
+ group: catalog
+ group_label: Catalog
+ label: Product types
+ description: ''
+ - key: write_product_types
+ resource: product_types
+ kind: write
+ group: catalog
+ group_label: Catalog
+ label: Product types
+ description: ''
+ - key: read_publishing
+ resource: publishing
+ kind: read
+ group: catalog
+ group_label: Catalog
+ label: Publishing
+ description: ''
+ - key: write_publishing
+ resource: publishing
+ kind: write
+ group: catalog
+ group_label: Catalog
+ label: Publishing
+ description: ''
+ - key: read_media
+ resource: media
+ kind: read
+ group: catalog
+ group_label: Catalog
+ label: Media
+ description: ''
+ - key: write_media
+ resource: media
+ kind: write
+ group: catalog
+ group_label: Catalog
+ label: Media
+ description: ''
+ - key: read_categories
+ resource: categories
+ kind: read
+ group: catalog
+ group_label: Catalog
+ label: Categories
+ description: Category tree and taxonomies
+ - key: write_categories
+ resource: categories
+ kind: write
+ group: catalog
+ group_label: Catalog
+ label: Categories
+ description: Category tree and taxonomies
+ - key: read_collections
+ resource: collections
+ kind: read
+ group: catalog
+ group_label: Catalog
+ label: Collections
+ description: Manual and rule-based product collections
+ - key: write_collections
+ resource: collections
+ kind: write
+ group: catalog
+ group_label: Catalog
+ label: Collections
+ description: Manual and rule-based product collections
+ - key: read_stock
+ resource: stock
+ kind: read
+ group: catalog
+ group_label: Catalog
+ label: Inventory
+ description: Stock levels, locations, movements and transfers
+ - key: write_stock
+ resource: stock
+ kind: write
+ group: catalog
+ group_label: Catalog
+ label: Inventory
+ description: Stock levels, locations, movements and transfers
+ - key: read_promotions
+ resource: promotions
+ kind: read
+ group: marketing
+ group_label: Marketing
+ label: Promotions
+ description: Promotions, rules and coupon codes
+ - key: write_promotions
+ resource: promotions
+ kind: write
+ group: marketing
+ group_label: Marketing
+ label: Promotions
+ description: Promotions, rules and coupon codes
+ - key: read_customers
+ resource: customers
+ kind: read
+ group: customers
+ group_label: Customers
+ label: Customers
+ description: Customer accounts, addresses, cards and groups
+ - key: write_customers
+ resource: customers
+ kind: write
+ group: customers
+ group_label: Customers
+ label: Customers
+ description: Customer accounts, addresses, cards and groups
+ - key: read_settings
+ resource: settings
+ kind: read
+ group: settings
+ group_label: Settings
+ label: Store settings
+ description: Store, payment, delivery, tax and channel configuration
+ - key: write_settings
+ resource: settings
+ kind: write
+ group: settings
+ group_label: Settings
+ label: Store settings
+ description: Store, payment, delivery, tax and channel configuration
+ - key: read_delivery_methods
+ resource: delivery_methods
+ kind: read
+ group: settings
+ group_label: Settings
+ label: Delivery methods
+ description: ''
+ - key: write_delivery_methods
+ resource: delivery_methods
+ kind: write
+ group: settings
+ group_label: Settings
+ label: Delivery methods
+ description: ''
+ - key: read_webhooks
+ resource: webhooks
+ kind: read
+ group: settings
+ group_label: Settings
+ label: Webhooks
+ description: Webhook endpoints and deliveries
+ - key: write_webhooks
+ resource: webhooks
+ kind: write
+ group: settings
+ group_label: Settings
+ label: Webhooks
+ description: Webhook endpoints and deliveries
+ - key: read_integrations
+ resource: integrations
+ kind: read
+ group: settings
+ group_label: Settings
+ label: Integrations
+ description: ''
+ - key: write_integrations
+ resource: integrations
+ kind: write
+ group: settings
+ group_label: Settings
+ label: Integrations
+ description: ''
+ - key: read_api_keys
+ resource: api_keys
+ kind: read
+ group: access
+ group_label: Access
+ label: API keys
+ description: Create and revoke API credentials
+ - key: write_api_keys
+ resource: api_keys
+ kind: write
+ group: access
+ group_label: Access
+ label: API keys
+ description: Create and revoke API credentials
+ - key: read_staff
+ resource: staff
+ kind: read
+ group: access
+ group_label: Access
+ label: Staff & roles
+ description: Team members, invitations, roles and their permissions
+ - key: write_staff
+ resource: staff
+ kind: write
+ group: access
+ group_label: Access
+ label: Staff & roles
+ description: Team members, invitations, roles and their permissions
+ - key: read_sellers
+ resource: sellers
+ kind: read
+ group: access
+ group_label: Access
+ label: Sellers
+ description: ''
+ - key: write_sellers
+ resource: sellers
+ kind: write
+ group: access
+ group_label: Access
+ label: Sellers
+ description: ''
+ - key: read_commissions
+ resource: commissions
+ kind: read
+ group: access
+ group_label: Access
+ label: Commissions
+ description: ''
+ - key: write_commissions
+ resource: commissions
+ kind: write
+ group: access
+ group_label: Access
+ label: Commissions
+ description: ''
+ - key: read_payouts
+ resource: payouts
+ kind: read
+ group: access
+ group_label: Access
+ label: Payouts
+ description: ''
+ - key: write_payouts
+ resource: payouts
+ kind: write
+ group: access
+ group_label: Access
+ label: Payouts
+ description: ''
+ - key: read_seller_profile
+ resource: seller_profile
+ kind: read
+ group: access
+ group_label: Access
+ label: Seller profile
+ description: ''
+ - key: write_seller_profile
+ resource: seller_profile
+ kind: write
+ group: access
+ group_label: Access
+ label: Seller profile
+ description: ''
+ - key: read_dashboard
+ resource: dashboard
+ kind: read
+ group: analytics
+ group_label: Analytics
+ label: Analytics dashboard
+ description: Sales and performance analytics
+ meta:
+ count: 51
+ "/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.
+
+ **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: roles } = await client.roles.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /roles
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: roles found
+ content:
+ application/json:
+ example:
+ data:
+ - id: role_UkLWZg9DAJ
+ name: admin
+ description:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ permissions:
+ - read_orders
+ - write_orders
+ - read_payments
+ - write_payments
+ - read_fulfillments
+ - write_fulfillments
+ - read_refunds
+ - write_refunds
+ - read_gift_cards
+ - write_gift_cards
+ - read_store_credits
+ - write_store_credits
+ - read_products
+ - write_products
+ - read_product_types
+ - write_product_types
+ - read_publishing
+ - write_publishing
+ - read_media
+ - write_media
+ - read_categories
+ - write_categories
+ - read_collections
+ - write_collections
+ - read_stock
+ - write_stock
+ - read_promotions
+ - write_promotions
+ - read_customers
+ - write_customers
+ - read_settings
+ - write_settings
+ - read_delivery_methods
+ - write_delivery_methods
+ - read_webhooks
+ - write_webhooks
+ - read_integrations
+ - write_integrations
+ - read_api_keys
+ - write_api_keys
+ - read_staff
+ - write_staff
+ - read_sellers
+ - write_sellers
+ - read_commissions
+ - write_commissions
+ - read_payouts
+ - write_payouts
+ - read_seller_profile
+ - write_seller_profile
+ - read_dashboard
+ mutable: false
+ users_count: 1
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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 role = await client.roles.create({
+ name: 'order_manager',
+ description: 'Handles daily orders',
+ permissions: ['write_orders', 'read_customers'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /roles -d '{"name":"order_manager","description":"Handles
+ daily orders","permissions":["write_orders","read_customers"]}'
+ 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:
+ example:
+ id: role_gbHJdmfrXB
+ name: order_manager
+ description: Handles daily orders
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ permissions:
+ - write_orders
+ - read_customers
+ mutable: true
+ users_count: 0
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: 'Permissions contains unknown permissions: write_bogus'
+ details:
+ permissions:
+ - 'contains unknown permissions: write_bogus'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: order_manager
+ description:
+ type: string
+ nullable: true
+ example: Handles daily orders
+ permissions:
+ type: array
+ items:
+ type: string
+ example:
+ - write_orders
+ - read_customers
+ 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.
+
+ **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 role = await client.roles.update('role_abc123', {
+ permissions: ['write_orders', 'write_payments', 'read_customers'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /roles/{id} -d '{"permissions":["write_orders","write_payments","read_customers"]}'
+ parameters:
+ - 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:
+ example:
+ id: role_gbHJdmfrXB
+ name: support
+ description:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ permissions:
+ - read_orders
+ - read_customers
+ mutable: true
+ users_count: 0
+ 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.
+
+ **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.roles.delete('role_abc123')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /roles/{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: role deleted
+ '422':
+ description: role cannot be deleted
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Roles cannot be deleted
+ "/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
+ (shared across stores). Filter with Ransack predicates such as
+ `q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or
+ `q[name_cont]`.
+
+ Pickup-related attributes (`kind`, `pickup_enabled`,
+ `pickup_stock_policy`, `pickup_ready_in_minutes`,
+ `pickup_instructions`) drive merchant pickup support at checkout —
+ customers can collect orders from any active location with
+ `pickup_enabled: true`.
+
+
+ **Required scope:** `read_stock` (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: stockLocations } = await client.stockLocations.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /stock_locations
+ parameters:
+ - name: x-spree-api-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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[active_eq]
+ in: query
+ required: false
+ description: Filter by active status
+ schema:
+ type: boolean
+ - name: q[kind_eq]
+ in: query
+ required: false
+ description: 'Filter by kind (built-in: ''warehouse'', ''store'', ''fulfillment_center'')'
+ schema:
+ type: string
+ - name: q[pickup_enabled_eq]
+ in: query
+ required: false
+ description: Filter by pickup-enabled flag
+ schema:
+ type: boolean
+ - 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
+ responses:
+ '200':
+ description: stock locations found
+ content:
+ application/json:
+ example:
+ data:
+ - id: sloc_UkLWZg9DAJ
+ name: Brooklyn warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ external_references: {}
+ admin_name:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ backorderable_default: true
+ propagate_all_variants: false
+ kind: warehouse
+ pickup_enabled: false
+ pickup_stock_policy: local
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ seller_id:
+ seller_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/StockLocation"
+ 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 stock location
+ tags:
+ - Stock Locations
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Creates a new stock location.
+
+ Setting `default: true` automatically demotes the previous default
+ location.
+
+
+ **Required scope:** `write_stock` (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 stockLocation = await client.stockLocations.create({
+ name: 'Brooklyn warehouse',
+ kind: 'warehouse',
+ country_code: 'US',
+ state_code: 'NY',
+ city: 'Brooklyn',
+ zipcode: '11201',
+ pickup_enabled: true,
+ pickup_stock_policy: 'local',
+ pickup_ready_in_minutes: 60,
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /stock_locations -d '{"name":"Brooklyn warehouse","kind":"warehouse","country_code":"US","state_code":"NY","city":"Brooklyn","zipcode":"11201","pickup_enabled":true,"pickup_stock_policy":"local","pickup_ready_in_minutes":60}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: sloc_gbHJdmfrXB
+ name: Manhattan store
+ address1:
+ city:
+ zipcode:
+ country_code:
+ country_name:
+ state_code:
+ state_text:
+ pickup_ready_in_minutes: 30
+ pickup_instructions:
+ external_references: {}
+ admin_name:
+ address2:
+ state_name:
+ phone:
+ company:
+ active: true
+ default: false
+ backorderable_default: false
+ propagate_all_variants: false
+ kind: store
+ pickup_enabled: true
+ pickup_stock_policy: local
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ seller_id:
+ seller_name:
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Brooklyn warehouse
+ admin_name:
+ type: string
+ nullable: true
+ description: Internal name shown only in the admin
+ active:
+ type: boolean
+ example: true
+ default:
+ type: boolean
+ description: Setting to true demotes the previous default.
+ kind:
+ type: string
+ enum:
+ - warehouse
+ - store
+ - fulfillment_center
+ description: Categorizes the location.
+ example: warehouse
+ 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.
+
+ **Required scope:** `read_stock` (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 stockLocation = await client.stockLocations.get('sloc_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /stock_locations/{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: 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:
+ example:
+ id: sloc_UkLWZg9DAJ
+ name: Brooklyn warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ external_references: {}
+ admin_name:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ backorderable_default: true
+ propagate_all_variants: false
+ kind: warehouse
+ pickup_enabled: false
+ pickup_stock_policy: local
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ seller_id:
+ seller_name:
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
+ '404':
+ description: stock location not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Stock location not found
+ 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
+ the create endpoint.
+
+ Setting `default: true` automatically demotes the previous default.
+
+
+ **Required scope:** `write_stock` (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 stockLocation = await client.stockLocations.update('sloc_UkLWZg9DAJ', {
+ pickup_enabled: true,
+ pickup_ready_in_minutes: 45,
+ pickup_instructions: 'Enter through the back door, ring the bell.',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /stock_locations/{id} -d '{"pickup_enabled":true,"pickup_ready_in_minutes":45,"pickup_instructions":"Enter
+ through the back door, ring the bell."}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: sloc_UkLWZg9DAJ
+ name: Renamed warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes: 45
+ pickup_instructions:
+ external_references: {}
+ admin_name:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ backorderable_default: true
+ propagate_all_variants: false
+ kind: warehouse
+ pickup_enabled: true
+ pickup_stock_policy: local
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ seller_id:
+ seller_name:
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Pickup stock policy is not included in the list
+ details:
+ pickup_stock_policy:
+ - is not included in the list
+ 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
+ fulfillments that referenced it keep the historical record via
+ `Spree::StockLocation.with_deleted`.
+
+
+ **Required scope:** `write_stock` (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.stockLocations.delete('sloc_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /stock_locations/{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: stock location deleted
+ "/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.
+
+ **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: variants } = await client.products.variants.list('prod_86Rf07xd4z', {
+ expand: ['prices', 'stock_levels'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /products/{product_id}/variants -d '{"expand":["prices","stock_levels"]}'
+ parameters:
+ - name: x-spree-api-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: 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
+ responses:
+ '200':
+ description: variants found
+ content:
+ application/json:
+ example:
+ data:
+ - id: variant_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-164
+ 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:
+ minimum_order_quantity:
+ order_multiple:
+ purchase_unit:
+ units_per_carton:
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ option_values: []
+ external_references: {}
+ metadata: {}
+ position: 1
+ cost_price: '17.0'
+ cost_currency: USD
+ barcode:
+ weight_unit: lb
+ dimensions_unit:
+ backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preorderable: false
+ tax_category_id: taxcat_UkLWZg9DAJ
+ available_stock: 0
+ reserved_quantity: 0
+ total_on_hand: 0
+ product_name: Product 1326804
+ delivery_profile_id: fp_UkLWZg9DAJ
+ - id: variant_gbHJdmfrXB
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-165
+ 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: 198.7
+ height: 97.29
+ width: 126.5
+ depth: 56.58
+ minimum_order_quantity:
+ order_multiple:
+ purchase_unit:
+ units_per_carton:
+ price:
+ id: price_gbHJdmfrXB
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-31
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-40
+ 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_price: '17.0'
+ cost_currency: USD
+ barcode:
+ weight_unit: lb
+ dimensions_unit:
+ backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preorderable: false
+ tax_category_id: taxcat_UkLWZg9DAJ
+ available_stock: 0
+ reserved_quantity: 0
+ total_on_hand: 0
+ product_name: Product 1326804
+ delivery_profile_id: fp_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
+ 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.
+
+ 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
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const variant = await client.products.variants.create('prod_86Rf07xd4z', {
+ sku: 'TSHIRT-L-NAVY',
+ options: [
+ { name: 'size', value: 'Large' },
+ { name: 'color', value: 'navy' },
+ ],
+ prices: [
+ { currency: 'USD', amount: '29.99', compare_at_amount: '34.99' },
+ { currency: 'EUR', amount: '27.99' },
+ ],
+ stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 25 }],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /products/{product_id}/variants -d '{"sku":"TSHIRT-L-NAVY","options":[{"name":"size","value":"Large"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99","compare_at_amount":"34.99"},{"currency":"EUR","amount":"27.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":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: product_id
+ in: path
+ required: true
+ description: Product ID
+ schema:
+ type: string
+ responses:
+ '201':
+ description: variant created
+ content:
+ application/json:
+ example:
+ id: variant_EfhxLZ9ck8
+ product_id: prod_UkLWZg9DAJ
+ sku: NEW-SKU-001
+ options_text: 'Size: XL'
+ track_inventory: true
+ media_count: 0
+ preorder_ships_at:
+ thumbnail_url:
+ purchasable: false
+ in_stock: false
+ backorderable: false
+ preorder: false
+ weight: 0.0
+ height:
+ width:
+ depth:
+ minimum_order_quantity:
+ order_multiple:
+ purchase_unit:
+ units_per_carton:
+ price:
+ id: price_EfhxLZ9ck8
+ amount: '24.99'
+ amount_in_cents: 2499
+ compare_at_amount:
+ compare_at_amount_in_cents:
currency: USD
- locales:
- - es
- - code: SX
- name: Sint Maarten (Dutch part)
- currency: XCG
- locales:
- - nl
- - en
- - code: SY
- name: Syrian Arab Republic
- currency: SYP
- locales:
- - ar
- - code: SZ
- name: Eswatini
- currency: SZL
- locales:
- - en
- - ss
- - code: TC
- name: Turks and Caicos Islands
+ display_amount: "$24.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ option_values:
+ - id: optval_gbHJdmfrXB
+ option_type_id: opt_gbHJdmfrXB
+ name: xl
+ label: XL
+ position: 1
+ color_code:
+ option_type_name: size
+ 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: 3
+ cost_price:
+ cost_currency: USD
+ barcode:
+ weight_unit: lb
+ dimensions_unit:
+ backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preorderable: false
+ tax_category_id: taxcat_UkLWZg9DAJ
+ available_stock: 0
+ reserved_quantity: 0
+ total_on_hand: 0
+ product_name: Product 1331771
+ delivery_profile_id: fp_UkLWZg9DAJ
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: SKU has already been taken
+ details:
+ sku:
+ - has already been taken
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ sku:
+ type: string
+ example: SKU-001
+ cost_price:
+ type: string
+ example: '10.00'
+ cost_currency:
+ type: string
+ example: USD
+ 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
+ example: size
+ value:
+ type: string
+ example: Small
+ 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
+ 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
+ "/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.
+
+ **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 variant = await client.products.variants.get('prod_86Rf07xd4z', 'variant_k5nR8xLq', {
+ expand: ['prices', 'stock_levels'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /products/{product_id}/variants/{id} -d '{"expand":["prices","stock_levels"]}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: variant_gbHJdmfrXB
+ product_id: prod_UkLWZg9DAJ
+ sku: SKU-171
+ 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: 19.33
+ height: 158.93
+ width: 166.27
+ depth: 20.71
+ minimum_order_quantity:
+ order_multiple:
+ purchase_unit:
+ units_per_carton:
+ price:
+ id: price_gbHJdmfrXB
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
currency: USD
- locales:
- - en
- - code: TD
- name: Chad
- currency: XAF
- locales:
- - ar
- - fr
- - code: TG
- name: Togo
- currency: XOF
- locales:
- - fr
- - code: TH
- name: Thailand
- currency: THB
- locales:
- - th
- - code: TJ
- name: Tajikistan
- currency: TJS
- locales:
- - tg
- - ru
- - code: TK
- name: Tokelau
- currency: NZD
- locales:
- - en
- - code: TL
- name: Timor-Leste
- currency: IDR
- locales:
- - pt
- - code: TM
- name: Turkmenistan
- currency: TMT
- locales:
- - tk
- - code: TN
- name: Tunisia
- currency: TND
- locales:
- - ar
- - fr
- - code: TO
- name: Tonga
- currency: TOP
- locales:
- - en
- - to
- - code: TR
- name: Türkiye
- currency: TRY
- locales:
- - tr
- - code: TT
- name: Trinidad and Tobago
- currency: TTD
- locales:
- - en
- - code: TV
- name: Tuvalu
- currency: AUD
- locales:
- - en
- - code: TW
- name: Taiwan
- currency: TWD
- locales:
- - zh
- - code: TZ
- name: Tanzania
- currency: TZS
- locales:
- - sw
- - en
- - code: UA
- name: Ukraine
- currency: UAH
- locales:
- - uk
- - code: UG
- name: Uganda
- currency: UGX
- locales:
- - en
- - sw
- - code: US
- name: United States
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-34
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-43
+ 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_price: '17.0'
+ cost_currency: USD
+ barcode:
+ weight_unit: lb
+ dimensions_unit:
+ backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preorderable: false
+ tax_category_id: taxcat_UkLWZg9DAJ
+ available_stock: 0
+ reserved_quantity: 0
+ total_on_hand: 0
+ product_name: Product 1354025
+ delivery_profile_id: fp_UkLWZg9DAJ
+ '404':
+ description: variant not found
+ content:
+ application/json:
+ example:
+ error:
+ code: variant_not_found
+ message: Variant not found
+ 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.
+
+ **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 variant = await client.products.variants.update('prod_86Rf07xd4z', 'variant_k5nR8xLq', {
+ sku: 'UPDATED-SKU',
+ stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 75 }],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /products/{product_id}/variants/{id} -d '{"sku":"UPDATED-SKU","stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":75}]}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: variant_gbHJdmfrXB
+ product_id: prod_UkLWZg9DAJ
+ sku: UPDATED-SKU
+ 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: 85.5
+ height: 120.69
+ width: 57.61
+ depth: 3.72
+ minimum_order_quantity:
+ order_multiple:
+ purchase_unit:
+ units_per_carton:
+ price:
+ id: price_gbHJdmfrXB
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ option_values:
+ - id: optval_UkLWZg9DAJ
+ option_type_id: opt_UkLWZg9DAJ
+ name: size-36
+ label: S
+ position: 1
+ color_code:
+ option_type_name: foo-size-45
+ 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_price: '17.0'
+ cost_currency: USD
+ barcode:
+ weight_unit: lb
+ dimensions_unit:
+ backorder_limit:
+ hs_code:
+ country_of_origin:
+ customs_description:
+ deleted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ preorderable: false
+ tax_category_id: taxcat_UkLWZg9DAJ
+ available_stock: 0
+ reserved_quantity: 0
+ total_on_hand: 0
+ product_name: Product 1375672
+ delivery_profile_id: fp_UkLWZg9DAJ
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ sku:
+ type: string
+ example: SKU-001
+ cost_price:
+ type: string
+ example: '10.00'
+ cost_currency:
+ type: string
+ example: USD
+ 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
+ example: size
+ value:
+ type: string
+ example: Small
+ 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
+ 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 variant
+ tags:
+ - Variants
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Soft-deletes a variant.
+
+ **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',
+ })
+
+ await client.products.variants.delete('prod_86Rf07xd4z', 'variant_k5nR8xLq')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /products/{product_id}/variants/{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: 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.
+ Each row carries the original request payload, the response code
+ (when the receiver replied), the execution time, and any transport
+ error — everything needed to audit failures and decide whether to
+ redeliver.
+
+
+ **Required scope:** `read_webhooks` (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 deliveries = await client.webhookEndpoints.deliveries.list('whe_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /webhook_endpoints/{webhook_endpoint_id}/deliveries
+ parameters:
+ - name: x-spree-api-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[event_name_eq]
+ in: query
+ required: false
+ description: Filter by event name (exact)
+ schema:
+ type: string
+ - name: q[success_eq]
+ in: query
+ required: false
+ description: Filter by success flag
+ schema:
+ type: boolean
+ - 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
+ responses:
+ '200':
+ description: deliveries found
+ content:
+ application/json:
+ example:
+ data:
+ - id: whd_UkLWZg9DAJ
+ event_name: order.created
+ event_id:
+ response_code: 200
+ execution_time: 150
+ error_type:
+ request_errors:
+ response_body:
+ success: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ payload:
+ event: order.created
+ data:
+ id: 1
+ webhook_endpoint_id: whe_UkLWZg9DAJ
+ webhook_endpoint_url: https://shop.example.com/webhooks
+ - id: whd_gbHJdmfrXB
+ event_name: order.created
+ event_id:
+ response_code: 500
+ execution_time: 200
+ error_type:
+ request_errors:
+ response_body:
+ success: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ payload:
+ event: order.created
+ data:
+ id: 1
+ webhook_endpoint_id: whe_UkLWZg9DAJ
+ webhook_endpoint_url: https://shop.example.com/webhooks
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
+ '404':
+ description: parent webhook endpoint not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Webhook endpoint not found
+ 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
+ the response body the receiver returned. Use this for ad-hoc debug
+ of failed deliveries.
+
+
+ **Required scope:** `read_webhooks` (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 delivery = await client.webhookEndpoints.deliveries.get('whe_xxx', 'whd_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /webhook_endpoints/{webhook_endpoint_id}/deliveries/{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: 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:
+ example:
+ id: whd_gbHJdmfrXB
+ event_name: order.created
+ event_id:
+ response_code: 500
+ execution_time: 200
+ error_type:
+ request_errors:
+ response_body:
+ success: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ payload:
+ event: order.created
+ data:
+ id: 1
+ webhook_endpoint_id: whe_UkLWZg9DAJ
+ webhook_endpoint_url: https://shop.example.com/webhooks
+ '404':
+ description: delivery not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Webhook delivery not found
+ 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
+ queues it. The original row is preserved for audit history.
+
+
+ **Required scope:** `write_webhooks` (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',
+ })
+
+ // Creates a new delivery row with the same payload + event_name and queues
+ // it. The original row is preserved for audit history.
+ const delivery = await client.webhookEndpoints.deliveries.redeliver('whe_xxx', 'whd_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver
+ -d '{ ... }'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: whd_EfhxLZ9ck8
+ event_name: order.created
+ event_id:
+ response_code:
+ execution_time:
+ error_type:
+ request_errors:
+ response_body:
+ success:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivered_at:
+ payload:
+ event: order.created
+ data:
+ id: 1
+ webhook_endpoint_id: whe_UkLWZg9DAJ
+ webhook_endpoint_url: https://shop.example.com/webhooks
+ "/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
+ endpoint receives a signed POST when any subscribed event fires.
+ `secret_key` is `null` on list reads — the plaintext is delivered
+ exactly once on create.
+
+
+ **Required scope:** `read_webhooks` (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 endpoints = await client.webhookEndpoints.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /webhook_endpoints
+ parameters:
+ - name: x-spree-api-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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[url_cont]
+ in: query
+ required: false
+ description: Filter by URL (contains)
+ schema:
+ type: string
+ - 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
+ responses:
+ '200':
+ description: webhook endpoints found
+ content:
+ application/json:
+ example:
+ data:
+ - id: whe_UkLWZg9DAJ
+ name: Order pipeline
+ url: https://shop.example.com/webhooks/orders
+ active: true
+ subscriptions:
+ - order.created
+ - order.completed
+ - product.created
+ disabled_reason:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ disabled_at:
+ secret_key:
+ last_delivery_at:
+ recent_delivery_count: 0
+ recent_failure_count: 0
+ total_delivery_count: 0
+ successful_delivery_count: 0
+ failed_delivery_count: 0
+ 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 webhook endpoint
+ tags:
+ - Webhooks
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Creates a new outbound webhook subscription. The plaintext
+ `secret_key` is returned **once** in this response — persist it
+ immediately to verify incoming webhook signatures. Subsequent reads
+ return `null` for the secret. Pass an empty `subscriptions` array or
+ omit it to receive every event.
+
+
+ **Required scope:** `write_webhooks` (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 endpoint = await client.webhookEndpoints.create({
+ name: 'Order pipeline',
+ url: 'https://example.com/webhooks/orders',
+ active: true,
+ subscriptions: ['order.placed', 'order.canceled'],
+ })
+
+ // The plaintext `secret_key` is returned exactly once on create — persist it
+ // immediately so you can verify incoming webhook signatures. Subsequent reads
+ // will return `null`.
+ const signingSecret = endpoint.secret_key
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /webhook_endpoints -d '{"name":"Order pipeline","url":"https://example.com/webhooks/orders","active":true,"subscriptions":["order.placed","order.canceled"]}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: whe_gbHJdmfrXB
+ name: CI integration
+ url: https://ci.example.com/webhooks
+ active: true
+ subscriptions:
+ - order.placed
+ disabled_reason:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ disabled_at:
+ secret_key: f44b508d518f47b9d42ae8a67ba913f7f7c4ee25be2e4dda1fbc06370fe29854
+ last_delivery_at:
+ recent_delivery_count: 0
+ recent_failure_count: 0
+ total_delivery_count: 0
+ successful_delivery_count: 0
+ failed_delivery_count: 0
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: |-
+ Url Translation missing. Options considered were:
+ - en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url
+ - en.activerecord.errors.models.spree/webhook_endpoint.invalid_url
+ - en.activerecord.errors.messages.invalid_url
+ - en.errors.attributes.url.invalid_url
+ - en.errors.messages.invalid_url
+ details:
+ url:
+ - |-
+ Translation missing. Options considered were:
+ - en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url
+ - en.activerecord.errors.models.spree/webhook_endpoint.invalid_url
+ - en.activerecord.errors.messages.invalid_url
+ - en.errors.attributes.url.invalid_url
+ - en.errors.messages.invalid_url
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - url
+ properties:
+ name:
+ type: string
+ example: Order pipeline
+ url:
+ type: string
+ example: https://example.com/webhooks/orders
+ active:
+ type: boolean
+ example: true
+ subscriptions:
+ type: array
+ items:
+ type: string
+ example:
+ - order.placed
+ - order.canceled
+ "/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.
+
+ **Required scope:** `read_webhooks` (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 endpoint = await client.webhookEndpoints.get('whe_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /webhook_endpoints/{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: 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:
+ example:
+ id: whe_UkLWZg9DAJ
+ name: Order pipeline
+ url: https://shop.example.com/webhooks/orders
+ active: true
+ subscriptions:
+ - order.created
+ - order.completed
+ - product.created
+ disabled_reason:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ disabled_at:
+ secret_key:
+ last_delivery_at:
+ recent_delivery_count: 0
+ recent_failure_count: 0
+ total_delivery_count: 0
+ successful_delivery_count: 0
+ failed_delivery_count: 0
+ '404':
+ description: webhook endpoint not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Webhook endpoint not found
+ 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.
+ Toggling `active` here is equivalent to calling `disable`/`enable`
+ without an audit reason.
+
+
+ **Required scope:** `write_webhooks` (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 endpoint = await client.webhookEndpoints.update('whe_xxx', {
+ name: 'Order pipeline (v2)',
+ subscriptions: ['order.placed', 'order.canceled', 'order.paid'],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /webhook_endpoints/{id} -d '{"name":"Order pipeline
+ (v2)","subscriptions":["order.placed","order.canceled","order.paid"]}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: whe_UkLWZg9DAJ
+ name: Order pipeline (renamed)
+ url: https://shop.example.com/webhooks/orders
+ active: true
+ subscriptions:
+ - order.created
+ - order.completed
+ - product.created
+ disabled_reason:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ disabled_at:
+ secret_key:
+ last_delivery_at:
+ recent_delivery_count: 0
+ recent_failure_count: 0
+ total_delivery_count: 0
+ successful_delivery_count: 0
+ failed_delivery_count: 0
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: |-
+ Url Translation missing. Options considered were:
+ - en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url
+ - en.activerecord.errors.models.spree/webhook_endpoint.invalid_url
+ - en.activerecord.errors.messages.invalid_url
+ - en.errors.attributes.url.invalid_url
+ - en.errors.messages.invalid_url
+ details:
+ url:
+ - |-
+ Translation missing. Options considered were:
+ - en.activerecord.errors.models.spree/webhook_endpoint.attributes.url.invalid_url
+ - en.activerecord.errors.models.spree/webhook_endpoint.invalid_url
+ - en.activerecord.errors.messages.invalid_url
+ - en.errors.attributes.url.invalid_url
+ - en.errors.messages.invalid_url
+ 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.
+
+ **Required scope:** `write_webhooks` (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.webhookEndpoints.delete('whe_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /webhook_endpoints/{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: 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
+ verify the endpoint is reachable and your signature verification
+ accepts Spree's payloads.
+
+
+ **Required scope:** `write_webhooks` (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',
+ })
+
+ // Fires a synthetic `webhook.test` delivery so you can verify the endpoint is
+ // reachable and your signature-verification code accepts Spree's payloads.
+ const delivery = await client.webhookEndpoints.sendTest('whe_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /webhook_endpoints/{id}/send_test -d '{ ... }'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: whd_UkLWZg9DAJ
+ event_name: webhook.test
+ event_id:
+ response_code:
+ execution_time:
+ error_type:
+ request_errors:
+ response_body:
+ success:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivered_at:
+ payload:
+ id: 98bd6b06-c704-47e3-a821-f23f15825658
+ name: webhook.test
+ created_at: '2026-01-15T12:00:00Z'
+ data:
+ message: This is a test webhook from Spree.
+ metadata:
+ spree_version: 6.0.0.alpha
+ webhook_endpoint_id: whe_UkLWZg9DAJ
+ webhook_endpoint_url: https://shop.example.com/webhooks/orders
+ "/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.
+
+ **Required scope:** `write_webhooks` (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',
+ })
+
+ // Re-enable an endpoint that was auto-disabled after repeated delivery failures.
+ const endpoint = await client.webhookEndpoints.enable('whe_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /webhook_endpoints/{id}/enable -d '{ ... }'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: whe_UkLWZg9DAJ
+ name: Order pipeline
+ url: https://shop.example.com/webhooks/orders
+ active: true
+ subscriptions:
+ - order.created
+ - order.completed
+ - product.created
+ disabled_reason:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ disabled_at:
+ secret_key:
+ last_delivery_at:
+ recent_delivery_count: 0
+ recent_failure_count: 0
+ total_delivery_count: 0
+ successful_delivery_count: 0
+ failed_delivery_count: 0
+ "/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
+ repeated delivery failures), no notification email is sent.
+
+
+ **Required scope:** `write_webhooks` (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',
+ })
+
+ // Pause an endpoint without deleting it. The optional `reason` is shown next
+ // to the disabled indicator in the admin.
+ const endpoint = await client.webhookEndpoints.disable('whe_xxx', {
+ reason: 'Investigating elevated 5xx rate',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /webhook_endpoints/{id}/disable -d '{"reason":"Investigating
+ elevated 5xx rate"}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: whe_UkLWZg9DAJ
+ name: Order pipeline
+ url: https://shop.example.com/webhooks/orders
+ active: false
+ subscriptions:
+ - order.created
+ - order.completed
+ - product.created
+ disabled_reason: Investigating
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ disabled_at: '2026-01-15T12:00:00.000Z'
+ secret_key:
+ last_delivery_at:
+ recent_delivery_count: 0
+ recent_failure_count: 0
+ total_delivery_count: 0
+ successful_delivery_count: 0
+ failed_delivery_count: 0
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ reason:
+ type: string
+ example: Investigating elevated 5xx rate
+ "/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
+ 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:
+ - can't be blank
+ 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: expand
+ in: query
+ required: false
+ description: Comma-separated. `catalog_price` adds the resolved price to every
+ row.
+ example: catalog_price
+ schema:
+ type: string
+ responses:
+ '200':
+ description: products found, with what the agreement charges
+ content:
+ application/json:
+ example:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 12159
+ slug: product-12159
+ 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: Veritatis quos vel inventore enim quod. Accusamus ipsum
+ itaque debitis magnam nisi deserunt error. Ad aperiam tempora
+ totam veniam adipisci nihil deleniti. Corporis expedita soluta
+ sunt harum reiciendis. Animi alias sed odio modi expedita corrupti
+ facere. Inventore quos corrupti dolor vitae. Dolorem amet unde
+ blanditiis iste adipisci quo fuga. Autem corporis accusamus ullam
+ repellendus architecto aliquid ipsum reprehenderit. Magni aliquid
+ id asperiores consectetur sunt numquam. Praesentium animi corrupti
+ tenetur recusandae sunt magnam aliquid. Expedita cumque qui sint
+ amet. Voluptatum architecto tempora nulla repudiandae adipisci.
+ Est quos quis minus quia at.
+ description_html: |-
+ Veritatis quos vel inventore enim quod. Accusamus ipsum itaque debitis magnam nisi deserunt error. Ad aperiam tempora totam veniam adipisci nihil deleniti.
+ Corporis expedita soluta sunt harum reiciendis. Animi alias sed odio modi expedita corrupti facere. Inventore quos corrupti dolor vitae. Dolorem amet unde blanditiis iste adipisci quo fuga.
+ Autem corporis accusamus ullam repellendus architecto aliquid ipsum reprehenderit. Magni aliquid id asperiores consectetur sunt numquam. Praesentium animi corrupti tenetur recusandae sunt magnam aliquid.
+ Expedita cumque qui sint amet. Voluptatum architecto tempora nulla repudiandae adipisci. Est quos quis minus quia at.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '100.0'
+ amount_in_cents: 10000
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$100.00"
+ display_compare_at_amount:
+ price_list_id:
+ 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'
+ delivery_profile_id: fp_UkLWZg9DAJ
+ seller_name:
+ product_type_id:
+ tax_category_id: taxcat_UkLWZg9DAJ
+ catalog_price:
+ currency: USD
+ source: automatic
+ amount: '80.0'
+ display_amount: "$80.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/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}/quantity_rules":
+ get:
+ summary: List catalog quantity rules
+ tags:
+ - Catalogs
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ The catalog's per-variant quantity terms. The catalog-wide default is a pair of fields on the catalog itself, so these are strictly the overrides.
+
+ **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
+ responses:
+ '200':
+ description: quantity rules found
+ content:
+ application/json:
+ example:
+ data:
+ - id: cqr_UkLWZg9DAJ
+ minimum_order_quantity: 48
+ order_multiple: 24
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ variant_id: variant_gbHJdmfrXB
+ variant_sku: SKU-5
+ product_name: Product 45457
+ options_text: 'Size: S'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ post:
+ summary: Create a catalog quantity rule
+ tags:
+ - Catalogs
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ States how much of one variant a buyer on this agreement must order. Both fields are optional individually, but a rule must state at least one — a field left out falls through to the catalog default, and then to the variant.
+
+ **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: quantity rule created
+ content:
+ application/json:
+ example:
+ id: cqr_UkLWZg9DAJ
+ minimum_order_quantity: 48
+ order_multiple: 24
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ variant_id: variant_gbHJdmfrXB
+ variant_sku: SKU-7
+ product_name: Product 51599
+ options_text: 'Size: S'
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Set a minimum order quantity, an order multiple, or both
+ details:
+ base:
+ - Set a minimum order quantity, an order multiple, or both
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ variant_id:
+ type: string
+ example: variant_86Rf07xd4z
+ minimum_order_quantity:
+ type: integer
+ nullable: true
+ example: 48
+ description: The least a buyer may order.
+ order_multiple:
+ type: integer
+ nullable: true
+ example: 24
+ description: Orders must land on a multiple of this, counted from
+ the minimum.
+ required:
+ - variant_id
+ "/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
+ responses:
+ '200':
+ description: order minimums found
+ content:
+ application/json:
+ example:
+ data:
+ - id: com_UkLWZg9DAJ
currency: USD
- locales:
- - en
- - code: UY
- name: Uruguay
- currency: UYU
- locales:
- - es
- - code: UZ
- name: Uzbekistan
- currency: UZS
- locales:
- - uz
- - code: VA
- name: Holy See (Vatican City State)
- currency: EUR
- locales:
- - it
- - la
- - code: VC
- name: Saint Vincent and the Grenadines
- currency: XCD
- locales:
- - en
- - code: VE
- name: Venezuela
- currency: VES
- locales:
- - es
- - code: VG
- name: Virgin Islands, British
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '500.0'
+ display_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.0'
+ display_amount: "$500.00"
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Amount must be greater than 0
+ details:
+ amount:
+ - must be greater than 0
+ 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}/quantity_rules/{id}":
+ patch:
+ summary: Update a catalog quantity rule
+ tags:
+ - Catalogs
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Restates one variant term. A field sent as null hands that field back to the catalog default; a rule must still state at least one of the two.
+
+ **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: quantity rule updated
+ content:
+ application/json:
+ example:
+ id: cqr_UkLWZg9DAJ
+ minimum_order_quantity: 96
+ order_multiple: 24
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ variant_id: variant_gbHJdmfrXB
+ variant_sku: SKU-11
+ product_name: Product 71912
+ options_text: 'Size: S'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ minimum_order_quantity:
+ type: integer
+ nullable: true
+ example: 96
+ order_multiple:
+ type: integer
+ nullable: true
+ example: 48
+ delete:
+ summary: Delete a catalog quantity rule
+ tags:
+ - Catalogs
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Drops one variant's exception, so it falls back to the catalog's own default.
+
+ **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: quantity rule deleted
+ "/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.0'
+ display_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: |-
+ Lifts the threshold for one currency, so orders in it may come to any total.
+
+ **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}/product_terms":
+ get:
+ summary: List catalog terms by product
+ tags:
+ - Catalogs
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ The catalog's quantity terms at the grain a merchant states them: one entry per product, over rows the database keeps per variant. `mixed` marks a product whose variants carry different terms.
+
+ **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
+ responses:
+ '200':
+ description: product terms found
+ content:
+ application/json:
+ example:
+ data:
+ - id: prod_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ product_name: Product 93986
+ minimum_order_quantity: 48
+ order_multiple: 24
+ mixed: true
+ put:
+ summary: Set catalog terms by product
+ tags:
+ - Catalogs
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Writes the given products' terms in one request, keyed by prefixed product id. 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 — this is the one catalog-term surface that is not a whole-set replacement, because an agreement may name terms for thousands of SKUs.
+
+ **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: product terms set
+ content:
+ application/json:
+ example:
+ data:
+ - id: prod_UkLWZg9DAJ
+ product_id: prod_UkLWZg9DAJ
+ product_name: Product 107053
+ minimum_order_quantity: 48
+ order_multiple: 24
+ mixed: false
+ 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
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ 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')
+ - lang: bash
+ label: Spree CLI
+ 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
+ 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: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (e.g., rules, custom_fields,
+ translations).
+ schema:
+ type: string
+ responses:
+ '200':
+ 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:
+ - can't be blank
+ 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: Spree::CollectionRules::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:
+ error:
+ code: record_not_found
+ message: Collection not found
+ 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.
+
+ **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:
+ example:
+ 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: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/Collection"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ 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:
+ 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.
+
+ **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.
+
+ **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
+ responses:
+ '200':
+ description: products found
+ content:
+ application/json:
+ example:
+ data: []
+ meta:
+ page: 1
+ limit: 25
+ count: 0
+ pages: 1
+ from: 0
+ to: 0
+ in: 0
+ 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
+ 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.
+
+ **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:
+ 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 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.
+
+ **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:
+ 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":
+ 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.
+
+ **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`.
+
+ **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:
+ example:
+ data:
+ - type: sale
+ label: On sale
+ description: Products currently discounted below their compare-at
+ price
+ preference_schema: []
+ - type: available_on
+ label: Recently published
+ description: Products published within the last N days
+ preference_schema: []
+ - type: tag
+ label: Tag
+ description: Products carrying a matching tag
+ preference_schema: []
+ "/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
+ 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:** `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',
+ })
+
+ // `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 get /commission_lines -d '{"page":1,"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: 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[seller_id_eq]
+ in: query
+ required: false
+ description: Filter to one seller
+ schema:
+ type: string
+ - name: q[order_id_eq]
+ in: query
+ required: false
+ description: Filter to one order
+ schema:
+ type: string
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ schema:
+ type: string
+ responses:
+ '200':
+ description: commission lines found
+ content:
+ application/json:
+ example:
+ data:
+ - id: cline_UkLWZg9DAJ
+ kind: percentage
currency: USD
- locales:
- - en
- - code: VI
- name: Virgin Islands, U.S.
+ taxability_reason:
+ country_code:
+ state_code:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ rate: '10.0'
+ tax_rate: '0.0'
+ amount: '10.0'
+ tax_amount: '2.1'
+ total: '12.1'
+ display_amount: "$10.00"
+ display_tax_amount: "$2.10"
+ display_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:
+ 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
+ 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:
+ 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.0'
+ tax_rate: '0.0'
+ amount: '10.0'
+ tax_amount: '2.1'
+ total: '12.1'
+ display_amount: "$10.00"
+ display_tax_amount: "$2.10"
+ display_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
+ 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 commission rates
+ tags:
+ - Commission Rates
+ 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.
+
+
+ **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
+ 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[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: q[enabled_eq]
+ in: query
+ required: false
+ description: Filter by whether the rate is in use
+ schema:
+ type: boolean
+ - name: sort
+ in: query
+ required: false
+ description: Sort by field. Prefix with `-` for descending (e.g., `-position`).
+ schema:
+ type: string
+ responses:
+ '200':
+ description: commission rates 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.0'
+ commission_tax_rate:
+ amounts: {}
+ bounds: {}
+ global: true
+ rules: []
+ 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/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
+ tags:
+ - Commission Rates
+ 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.
+
+
+ **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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: commission rate created
+ content:
+ application/json:
+ example:
+ 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/CommissionRate"
+ '422':
+ description: validation failed
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: needs a flat fee amount in at least one currency
+ details:
+ base:
+ - needs a flat fee amount in at least one currency
+ 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.
+ 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:
+ type: string
+ example: '0.21'
+ 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
+ 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 preference_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
+ the configuration it takes — so a client builds its editor from what
+ this marketplace has rather than a list hardcoded to match core's.
+
+ `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
+ 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
+ preference_schema:
+ - key: seller_ids
+ type: array
+ default: []
+ association_fields: []
+ - type: category_rule
+ name: Category
+ description: Charges this rate only for products in the selected
+ categories, and anything filed beneath them
+ preference_schema:
+ - key: category_ids
+ type: array
+ default: []
+ association_fields: []
+ - type: product_rule
+ name: Product
+ description: Charges this rate only for the selected products
+ preference_schema: []
+ association_fields:
+ - product_ids
+ - type: item_total_rule
+ name: Sale value
+ description: Charges this rate only on sales within a value range
+ preference_schema:
+ - key: min_amount
+ type: decimal
+ default:
+ - key: max_amount
+ type: decimal
+ default:
+ 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
+ preference_schema:
+ type: array
+ items:
+ type: object
+ 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
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ 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.0'
+ commission_tax_rate:
+ amounts: {}
+ bounds: {}
+ global: true
+ rules: []
+ schema:
+ "$ref": "#/components/schemas/CommissionRate"
+ '404':
+ description: commission rate not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Commission rate not found
+ 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"}}]}'
+ parameters:
+ - 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:
+ 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.0'
+ commission_tax_rate:
+ amounts: {}
+ bounds: {}
+ global: true
+ rules: []
+ 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
+ tags:
+ - Commission Rates
+ 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',
+ })
+
+ // 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
+ 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.
+
+ **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
+ 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
+ responses:
+ '200':
+ description: certificates 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:
+ 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: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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
+ 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`.
+
+
+ **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: certificate 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:
+ 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:
+ - can't be blank
+ 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:
+ 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:
+ - 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
+ 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).
+ 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: certificate verified
+ 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'
+ 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
+ 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.
+
+ **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:
+ '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).
+ 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
+ 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
+ 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_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: registrations } = await client.companies.taxIdentifiers.list('comp_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /companies/{company_id}/tax_identifiers
+ responses:
+ '200':
+ description: registrations found
+ content:
+ application/json:
+ example:
+ data:
+ - 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'
+ validatable: false
+ customer_id:
+ cart_id:
+ order_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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: validation_error
+ message: Registration type has already been taken
+ details:
+ kind:
+ - has already been taken
+ 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
+ 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
+ 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:
+ '422':
+ description: no validator installed for this kind
+ 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":
+ get:
+ summary: List companies
+ tags:
+ - Companies
+ 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',
+ })
+
+ const { data: companies } = await client.companies.list({ name_cont: 'Acme' })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /companies -d '{"name_cont":"Acme"}'
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: companies 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: {}
+ 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
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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',
+ })
+
+ const company = await client.companies.create({
+ name: 'Globex Corporation',
+ external_references: { erp: 'GLBX-42' },
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /companies -d '{"name":"Globex Corporation","external_references":{"erp":"GLBX-42"}}'
+ 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:
+ example:
+ id: comp_gbHJdmfrXB
+ name: Globex Corporation
+ kind: company
+ po_number_required: false
+ parent_id:
+ ancestors: []
+ external_references:
+ erp: GLBX-42
+ metadata: {}
+ 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:
+ - can't be blank
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ 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:
+ type: string
+ nullable: true
+ description: The parent node. Omit for a root.
+ example: comp_86Rf07xd4z
+ 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
+ example: erp
+ external_id:
+ type: string
+ example: GLBX-42
+ 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
+ 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. The two differ where a class has been renamed — categories are
+ stored under `Spree::Taxon` and shown as "Categories" — so send the
+ value back verbatim rather than deriving it from the name.
+
+
+ **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
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: resource types found
+ content:
+ application/json:
+ example:
+ data:
+ - resource_type: Spree::Address
+ name: Addresses
+ - resource_type: Spree::Taxon
+ name: Categories
+ - resource_type: Spree::Claim
+ name: Claims
+ - resource_type: Spree::Collection
+ name: Collections
+ - resource_type: Spree::CreditCard
+ name: Credit Cards
+ - resource_type: Spree::Customer
+ name: Customers
+ - resource_type: Spree::DeliveryMethod
+ name: Delivery Methods
+ - resource_type: Spree::Exchange
+ name: Exchanges
+ - resource_type: Spree::Fulfillment
+ name: Fulfillments
+ - resource_type: Spree::GiftCard
+ name: Gift Cards
+ - resource_type: Spree::LineItem
+ name: Line Items
+ - resource_type: Spree::Media
+ name: Media
+ - resource_type: Spree::NewsletterSubscriber
+ name: Newsletter Subscribers
+ - resource_type: Spree::OptionType
+ name: Option Types
+ - resource_type: Spree::OptionValue
+ name: Option Values
+ - resource_type: Spree::Order
+ name: Orders
+ - resource_type: Spree::PaymentMethod
+ name: Payment Methods
+ - resource_type: Spree::PaymentSource
+ name: Payment Sources
+ - resource_type: Spree::Payment
+ name: Payments
+ - resource_type: Spree::ProductType
+ name: Product Types
+ - resource_type: Spree::Product
+ name: Products
+ - resource_type: Spree::Promotion
+ name: Promotions
+ - resource_type: Spree::Refund
+ name: Refunds
+ - resource_type: Spree::Return
+ name: Returns
+ - resource_type: Spree::Seller
+ name: Sellers
+ - resource_type: Spree::StockLevel
+ name: Stock Levels
+ - resource_type: Spree::StockTransfer
+ name: Stock Transfers
+ - resource_type: Spree::StoreCredit
+ name: Store Credits
+ - resource_type: Spree::Store
+ name: Stores
+ - resource_type: Spree::TaxRate
+ name: Tax Rates
+ - resource_type: Spree::Variant
+ name: Variants
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ resource_type:
+ type: string
+ example: Spree::Seller
+ name:
+ type: string
+ example: Sellers
+ "/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.
+
+ **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 profiles = await client.deliveryProfiles.list()
+ - lang: bash
+ label: Spree CLI
+ 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
+ responses:
+ '200':
+ description: delivery profiles found
+ content:
+ application/json:
+ example:
+ data:
+ - 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
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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 profile = await client.deliveryProfiles.create({
+ name: 'Oversized',
+ stock_location_ids: ['sloc_86Rf07xd4z'],
+ })
+ - lang: bash
+ label: Spree CLI
+ 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: delivery profile created
+ content:
+ application/json:
+ example:
+ 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:
+ - can't be blank
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ 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:
+ - 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.
+
+ **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 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 /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: origin group created
+ 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
+ tags:
+ - Delivery
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**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 profile = await client.deliveryProfiles.update('fp_86Rf07xd4z', {
+ name: 'Oversized freight',
+ stock_location_ids: [],
+ })
+ - lang: bash
+ label: Spree CLI
+ 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: delivery profile updated
+ 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":
+ get:
+ summary: List delivery methods
+ tags:
+ - Delivery
+ 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'
+
+ 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
+ parameters:
+ - 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 methods found
+ content:
+ application/json:
+ example:
+ data:
+ - id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ admin_name:
+ fulfillment_provider: Spree::FulfillmentProvider::Manual
+ pickup_point_provider:
+ rate_provider:
+ storefront_visible: true
+ tracking_url:
+ markup_flat: '0.0'
+ markup_percent: '0.0'
+ available_to_sellers: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ 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: []
+ calculator_type: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ amount: '10.0'
+ currency: USD
+ amounts: {}
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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 deliveryMethod = await client.deliveryMethods.create({
+ name: 'Express',
+ storefront_visible: true,
+ calculator_type: 'Spree::Calculator::Shipping::FlatRate',
+ calculator_preferences: { amount: 12.5 },
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /delivery_methods -d '{"name":"Express","storefront_visible":true,"calculator_type":"Spree::Calculator::Shipping::FlatRate","calculator_preferences":{"amount":12.5}}'
+ 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:
+ 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:
+ fulfillment_provider: Spree::FulfillmentProvider::Manual
+ pickup_point_provider:
+ rate_provider:
+ storefront_visible: true
+ tracking_url:
+ markup_flat: '0.0'
+ markup_percent: '0.0'
+ available_to_sellers: false
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ 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: []
+ calculator_type: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ amount: '12.5'
currency: USD
- locales:
- - en
- - code: VN
- name: Vietnam
- currency: VND
- locales:
- - vi
- - code: VU
- name: Vanuatu
- currency: VUV
- locales:
- - bi
- - en
- - fr
- - code: WF
- name: Wallis and Futuna
- currency: XPF
- locales:
- - fr
- - code: WS
- name: Samoa
- currency: WST
- locales:
- - sm
- - en
- - code: YE
- name: Yemen
- currency: YER
- locales:
- - ar
- - code: YT
- name: Mayotte
- currency: EUR
- locales:
- - fr
- - code: ZA
- name: South Africa
- currency: ZAR
- locales:
- - af
- - en
- - nr
- - st
- - ss
- - tn
- - ts
- - ve
- - xh
- - zu
- - code: ZM
- name: Zambia
- currency: ZMW
- locales:
- - en
- - code: ZW
- name: Zimbabwe
+ amounts: {}
+ 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: Spree::FulfillmentProvider::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:
+ type: string
+ example: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ type: object
+ example:
+ amount: 12.5
+ 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.
+
+ **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: Spree::Calculator::Shipping::FlatPercentItemTotal
+ name: Flat Percent
+ preference_schema:
+ - key: flat_percent
+ type: decimal
+ default: 0
+ - type: Spree::Calculator::Shipping::FlatRate
+ name: Flat rate
+ preference_schema:
+ - key: amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - key: amounts
+ type: hash
+ default: {}
+ - type: Spree::Calculator::Shipping::FlexiRate
+ name: Flexible Rate per package item
+ preference_schema:
+ - key: currency
+ type: string
+ default: USD
+ - key: first_item
+ type: decimal
+ default: 0.0
+ - key: additional_item
+ type: decimal
+ default: 0.0
+ - key: max_items
+ type: integer
+ default: 0
+ - type: Spree::Calculator::Shipping::PerItem
+ name: Flat rate per package item
+ preference_schema:
+ - key: amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - key: amounts
+ type: hash
+ default: {}
+ - type: Spree::Calculator::Shipping::PriceSack
+ name: Price sack
+ preference_schema:
+ - key: minimal_amount
+ type: decimal
+ default: 0
+ - key: normal_amount
+ type: decimal
+ default: 0
+ - key: discount_amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - type: Spree::Calculator::Shipping::DigitalDelivery
+ name: Digital Delivery
+ preference_schema:
+ - key: amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - key: amounts
+ type: hash
+ default: {}
+ "/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).
+
+ **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 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"}]}'
+ 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:
+ 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":
+ 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.
+
+ **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: integrations } = await client.integrations.list()
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /integrations
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: integrations found
+ content:
+ application/json:
+ example:
+ data:
+ - id: int_UkLWZg9DAJ
+ name: Carrier
+ active: false
+ 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'
+ preference_schema:
+ - key: api_key
+ type: password
+ default:
+ - key: account_number
+ type: string
+ default:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **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 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"}}'
+ 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:
+ example:
+ id: int_UkLWZg9DAJ
+ name: Carrier
+ active: false
+ 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:
+ preference_schema:
+ - key: api_key
+ type: password
+ default:
+ - key: account_number
+ type: string
+ default:
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ type:
+ 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'
+ 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:
+ preference_schema:
+ - key: api_key
+ type: password
+ default:
+ - key: account_number
+ type: string
+ default:
+ "/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":
+ 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
+ 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.
+
+
+ **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: 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
+ responses:
+ '200':
+ description: media found
+ content:
+ application/json:
+ example:
+ data:
+ - 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==--ee384b06b9035e678160c88fe35ccc8036485072/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1fdfc054106765923edf66a82ed28f05b6086cf2/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f6be6c2e5f6c387856595952a80253b1e253880/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--0c546bb74ed0de4de296554ede0b9749582ccad7/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d5064f97e1a23955372d4a16ed655b4c03527c78/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--de8d2c7d094a845fe439eef0968764b84ebe1349/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--17903bb2c581bd6827c784417ad5e4c7de9d63e0/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==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2fcb9d411b07c09ec93ae6dfc42c4da4a9500292/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072
+ viewable_id: prod_UkLWZg9DAJ
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/thinking-cat.jpg?disposition=attachment
+ metadata: {}
+ viewable_type: product
+ 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/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
+ 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==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/library-upload.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1fdfc054106765923edf66a82ed28f05b6086cf2/library-upload.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f6be6c2e5f6c387856595952a80253b1e253880/library-upload.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--0c546bb74ed0de4de296554ede0b9749582ccad7/library-upload.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d5064f97e1a23955372d4a16ed655b4c03527c78/library-upload.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--de8d2c7d094a845fe439eef0968764b84ebe1349/library-upload.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--17903bb2c581bd6827c784417ad5e4c7de9d63e0/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==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2fcb9d411b07c09ec93ae6dfc42c4da4a9500292/library-upload.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37
+ viewable_id:
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--cab07391bf4e6e8c8aad1c4176b476248ed0ec37/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 253397
+ owner_type: Spree::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==--ee384b06b9035e678160c88fe35ccc8036485072/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--1fdfc054106765923edf66a82ed28f05b6086cf2/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8f6be6c2e5f6c387856595952a80253b1e253880/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--0c546bb74ed0de4de296554ede0b9749582ccad7/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--d5064f97e1a23955372d4a16ed655b4c03527c78/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--de8d2c7d094a845fe439eef0968764b84ebe1349/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--17903bb2c581bd6827c784417ad5e4c7de9d63e0/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==--ee384b06b9035e678160c88fe35ccc8036485072/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2fcb9d411b07c09ec93ae6dfc42c4da4a9500292/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072
+ viewable_id: prod_gbHJdmfrXB
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072/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
+ tags:
+ - Deliveries
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ The consignments of a parcel — one per tracking number, each with the carrier status last reported.
+
+ **Required scope:** `read_fulfillments` (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: deliveries } = await client.orders.fulfillments.deliveries.list(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ )
+
+ // Each carries its own carrier status: pending, in_transit, delivered, ...
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries
+ parameters:
+ - name: x-spree-api-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:
+ '200':
+ description: deliveries found
+ content:
+ application/json:
+ example:
+ data:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ 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:
+ 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.
+
+ **Required scope:** `write_fulfillments` (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 second box, or a freight consignment: the carrier is free text, so a
+ // forwarder's PRO number is as valid as a parcel number.
+ const delivery = await client.orders.fulfillments.deliveries.create(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ { tracking_number: 'PRO-4471923', carrier: 'Estes Freight' },
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries
+ -d '{"tracking_number":"PRO-4471923","carrier":"Estes Freight"}'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: dlv_gbHJdmfrXB
+ tracking_number: 1Z879E930346834440
+ carrier: ups
+ carrier_name: UPS
+ service:
+ status: pending
+ tracking_url: https://www.ups.com/track?tracknum=1Z879E930346834440
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ '422':
+ description: tracking number already recorded on this parcel
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Tracking number has already been taken
+ details:
+ tracking_number:
+ - has already been taken
+ 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.
+
+ **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:
+ example:
+ id: dlv_UkLWZg9DAJ
+ tracking_number: CORRECTED-1
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ 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.
+
+ **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.
+
+ **Required scope:** `write_fulfillments` (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',
+ })
+
+ // Staff confirming one consignment arrived. The fulfillment follows once
+ // every one of its consignments has.
+ const delivery = await client.orders.fulfillments.deliveries.markDelivered(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'dlv_UkLWZg9DAJ',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered
+ -d '{ ... }'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: delivered
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at: '2026-01-15T12:00:00.000Z'
+ details:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ 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.
+
+ **Required scope:** `read_fulfillments` (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: labels } = await client.orders.fulfillments.labels.list(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ )
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /orders/{order_id}/fulfillments/{fulfillment_id}/labels
+ parameters:
+ - name: x-spree-api-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:
+ '200':
+ description: labels found
+ content:
+ application/json:
+ example:
+ data:
+ - id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: purchased
+ carrier: ups
+ carrier_name: UPS
+ service: Ground
+ tracking_number: 1Z879E930346830001
currency: USD
- locales:
- - en
- - sn
- - nd
- "/api/v3/admin/stock_levels/bulk_upsert":
+ format: pdf
+ external_id: shp_1
+ 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'
+ display_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:
post:
- summary: Bulk-upsert stock levels
+ 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.
+
+ **Required scope:** `write_fulfillments` (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',
+ })
+
+ // With no body, the parcel's carrier account buys the label.
+ const label = await client.orders.fulfillments.labels.create('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')
+
+ // The tracking number is now on the parcel's first delivery, and the label is
+ // ready to print. What the merchant paid the carrier is label.display_cost.
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /orders/{order_id}/fulfillments/{fulfillment_id}/labels
+ -d '{ ... }'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: purchased
+ carrier: ups
+ carrier_name: UPS
+ service: Ground
+ tracking_number: 1Z879E930346834440
+ currency: USD
+ format: pdf
+ external_id: shp_1
+ metadata:
+ tracker_id: trk_1
+ file_url: https://carrier.example/label.pdf
+ 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'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: true
+ download_url: "/api/v3/admin/orders/or_UkLWZg9DAJ/fulfillments/ful_UkLWZg9DAJ/labels/lbl_UkLWZg9DAJ/download"
+ '422':
+ description: provider does not produce labels
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: This delivery method's provider does not produce labels
+ 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.
+
+ **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:
+ example:
+ id: lbl_UkLWZg9DAJ
+ source: uploaded
+ status: purchased
+ carrier: ups
+ carrier_name: UPS
+ service: Ground
+ tracking_number: 1Z879E930346830002
+ currency: USD
+ format: pdf
+ external_id:
+ 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'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: false
+ download_url:
+ 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.
+
+ **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.
+
+ **Required scope:** `write_fulfillments` (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 label = await client.orders.fulfillments.labels.refund(
+ 'or_UkLWZg9DAJ',
+ 'ful_UkLWZg9DAJ',
+ 'lbl_UkLWZg9DAJ',
+ )
+
+ // 'refunded' when the carrier settled at once, 'refund_requested' when it
+ // will answer later.
+ const outcome = label.status
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund
+ -d '{ ... }'
+ parameters:
+ - name: x-spree-api-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:
+ example:
+ id: lbl_UkLWZg9DAJ
+ source: purchased
+ status: refunded
+ carrier: ups
+ carrier_name: UPS
+ service: Ground
+ tracking_number: 1Z879E930346830004
+ currency: USD
+ format: pdf
+ external_id: shp_2
+ metadata: {}
+ refunded_at: '2026-01-15T12:00:00.000Z'
+ 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'
+ display_cost: "$7.25"
+ integration_id:
+ file_pending: false
+ download_url:
+ '422':
+ description: uploaded labels cannot be refunded
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: An uploaded label was not bought through Spree and cannot
+ be refunded — delete it instead
+ "/api/v3/admin/price_lists/{price_list_id}/products":
+ get:
+ summary: List price list products
tags:
- - Stock
+ - Price Lists
security:
- api_key: []
bearer_auth: []
description: |-
- Sets stock levels for many (variant, location) pairs at once — what a
- warehouse or ERP feed posts on a schedule.
-
- Each row names its variant and stock location by Spree id
- (`variant_id`, `stock_location_id`).
-
- A row carries either `count_on_hand` — the absolute level the external
- system reports — or `adjustment`, a relative change for feeds that
- report movements instead. Every change is written as a stock movement,
- so a merchant can still see why a figure moved.
-
- The response carries `stock_level_count`: how many rows moved a shelf.
-
+ The products the list prices, listed by name — membership is derived from the price rows.
- **Required scope:** `write_stock` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ **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
+ responses:
+ '200':
+ description: products found
+ content:
+ application/json:
+ example:
+ data: []
+ meta:
+ page: 1
+ limit: 25
+ count: 0
+ pages: 1
+ from: 0
+ to: 0
+ in: 0
+ 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 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.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ **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:
+ 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 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.
- const { stock_level_count } = await client.stockLevels.bulkUpsert({
- stock_levels: [
- {
- variant_id: 'variant_xxx',
- stock_location_id: 'sloc_xxx',
- count_on_hand: 42,
- },
- ],
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /stock_levels/bulk_upsert -d '{"stock_levels":[{"variant_id":"variant_xxx","stock_location_id":"sloc_xxx","count_on_hand":42}]}'
+ **Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25031,81 +33436,49 @@ paths:
required: true
schema:
type: string
+ - name: price_list_id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: stock levels updated
- '422':
- description: row is missing a level
+ description: products removed
+ content:
+ application/json:
+ example:
+ removed_count: 1
requestBody:
content:
application/json:
schema:
type: object
- required:
- - stock_levels
properties:
- stock_levels:
+ product_ids:
type: array
items:
- type: object
- required:
- - variant_id
- - stock_location_id
- properties:
- variant_id:
- type: string
- example: variant_xY9
- stock_location_id:
- type: string
- example: sloc_aBc
- count_on_hand:
- type: integer
- nullable: true
- example: 42
- adjustment:
- type: integer
- nullable: true
- example: -3
- backorderable:
- type: boolean
- nullable: true
- "/api/v3/admin/stock_locations":
+ type: string
+ example:
+ - prod_abc123
+ required:
+ - product_ids
+ "/api/v3/admin/product_types":
get:
- summary: List stock locations
+ summary: List product types
tags:
- - Stock Locations
+ - Product Types
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the configured stock locations. Stock locations are global
- (shared across stores). Filter with Ransack predicates such as
- `q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or
- `q[name_cont]`.
-
- Pickup-related attributes (`kind`, `pickup_enabled`,
- `pickup_stock_policy`, `pickup_ready_in_minutes`,
- `pickup_instructions`) drive merchant pickup support at checkout —
- customers can collect orders from any active location with
- `pickup_enabled: true`.
-
+ Returns a paginated list of product types.
- **Required scope:** `read_stock` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ A product type is a back-office template: it seeds option types and
+ categories onto products created with it, and defines which custom
+ fields those products' forms show. It is not exposed on the Store API.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const { data: stockLocations } = await client.stockLocations.list()
- - lang: bash
- label: Spree CLI
- source: spree api get /stock_locations
+ **Required scope:** `read_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25130,54 +33503,39 @@ paths:
description: Number of records per page
schema:
type: integer
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: q[active_eq]
- in: query
- required: false
- description: Filter by active status
- schema:
- type: boolean
- - name: q[kind_eq]
- in: query
- required: false
- description: 'Filter by kind (built-in: ''warehouse'', ''store'', ''fulfillment_center'')'
- schema:
- type: string
- - name: q[pickup_enabled_eq]
- in: query
- required: false
- description: Filter by pickup-enabled flag
- schema:
- type: boolean
- - 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
responses:
'200':
- description: stock locations found
+ description: product types found
content:
application/json:
+ example:
+ data:
+ - id: pt_UkLWZg9DAJ
+ name: T-Shirt
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivery_profile_id:
+ option_type_ids: []
+ category_ids: []
+ custom_field_definitions: []
+ 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/StockLocation"
+ "$ref": "#/components/schemas/ProductType"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
@@ -25187,48 +33545,29 @@ paths:
description: unauthorized
content:
application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a stock location
+ summary: Create a product type
tags:
- - Stock Locations
+ - Product Types
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new stock location.
-
- Setting `default: true` automatically demotes the previous default
- location.
-
+ Creates a product type.
- **Required scope:** `write_stock` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ `option_type_ids` and `category_ids` seed products created with this
+ type. `custom_field_definitions` is a replace-set of the definitions the
+ product form renders, in `sort_order`. `required` is advisory — the
+ dashboard marks the field, but a blank value is never rejected.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const stockLocation = await client.stockLocations.create({
- name: 'Brooklyn warehouse',
- kind: 'warehouse',
- country_code: 'US',
- state_code: 'NY',
- city: 'Brooklyn',
- zipcode: '11201',
- pickup_enabled: true,
- pickup_stock_policy: 'local',
- pickup_ready_in_minutes: 60,
- })
- - lang: bash
- label: Spree CLI
- source: spree api post /stock_locations -d '{"name":"Brooklyn warehouse","kind":"warehouse","country_code":"US","state_code":"NY","city":"Brooklyn","zipcode":"11201","pickup_enabled":true,"pickup_stock_policy":"local","pickup_ready_in_minutes":60}'
+ **Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25243,15 +33582,32 @@ paths:
type: string
responses:
'201':
- description: stock location created
+ description: product type created
content:
application/json:
+ example:
+ id: pt_gbHJdmfrXB
+ name: Hoodie
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivery_profile_id:
+ option_type_ids: []
+ category_ids: []
+ custom_field_definitions: []
schema:
- "$ref": "#/components/schemas/StockLocation"
+ "$ref": "#/components/schemas/ProductType"
'422':
- description: validation error
+ description: unprocessable entity
content:
application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -25262,112 +33618,57 @@ paths:
properties:
name:
type: string
- example: Brooklyn warehouse
- admin_name:
- type: string
- nullable: true
- description: Internal name shown only in the admin
- active:
- type: boolean
- example: true
- default:
- type: boolean
- description: Setting to true demotes the previous default.
- kind:
- type: string
- enum:
- - warehouse
- - store
- - fulfillment_center
- description: Categorizes the location.
- example: warehouse
- 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:
+ example: Hoodie
+ delivery_profile_id:
type: string
nullable: true
+ example: fp_86Rf07xd4z
+ 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/stock_locations/{id}":
+ "/api/v3/admin/product_types/{id}":
parameters:
- name: id
in: path
+ description: Product type ID
required: true
- description: Stock location ID
schema:
type: string
get:
- summary: Get a stock location
+ summary: Retrieve a product type
tags:
- - Stock Locations
+ - Product Types
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single stock location by prefixed ID.
-
- **Required scope:** `read_stock` (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 a single product type with its option types, categories and custom fields.
- const stockLocation = await client.stockLocations.get('sloc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api get /stock_locations/{id}
+ **Required scope:** `read_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25380,60 +33681,48 @@ paths:
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
+ description: product type found
content:
application/json:
+ example:
+ id: pt_UkLWZg9DAJ
+ name: T-Shirt
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivery_profile_id:
+ option_type_ids: []
+ category_ids: []
+ custom_field_definitions: []
schema:
- "$ref": "#/components/schemas/StockLocation"
+ "$ref": "#/components/schemas/ProductType"
'404':
- description: stock location not found
+ description: product type not found
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Product type not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a stock location
+ summary: Update a product type
tags:
- - Stock Locations
+ - Product Types
security:
- api_key: []
bearer_auth: []
description: |-
- Updates an existing stock location. Same address-field conventions as
- the create endpoint.
-
- Setting `default: true` automatically demotes the previous default.
-
+ Updates a product type.
- **Required scope:** `write_stock` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
+ Changes never modify products that already carry the type — use
+ `apply_to_products` to backfill those.
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
- const stockLocation = await client.stockLocations.update('sloc_UkLWZg9DAJ', {
- pickup_enabled: true,
- pickup_ready_in_minutes: 45,
- pickup_instructions: 'Enter through the back door, ring the bell.',
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /stock_locations/{id} -d '{"pickup_enabled":true,"pickup_ready_in_minutes":45,"pickup_instructions":"Enter
- through the back door, ring the bell."}'
+ **Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25448,17 +33737,21 @@ paths:
type: string
responses:
'200':
- description: stock location updated
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/StockLocation"
- '422':
- description: validation error
+ description: product type updated
content:
application/json:
+ example:
+ id: pt_UkLWZg9DAJ
+ name: Premium T-Shirt
+ products_count: 0
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ delivery_profile_id:
+ option_type_ids: []
+ category_ids: []
+ custom_field_definitions: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/ProductType"
requestBody:
content:
application/json:
@@ -25467,93 +33760,40 @@ paths:
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:
+ example: Premium T-Shirt
+ 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 stock location
+ summary: Delete a product type
tags:
- - Stock Locations
+ - Product Types
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes the stock location (sets `deleted_at`). Existing
- fulfillments that referenced it keep the historical record via
- `Spree::StockLocation.with_deleted`.
-
-
- **Required scope:** `write_stock` (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 product type. Types still used by products cannot be deleted.
- await client.stockLocations.delete('sloc_UkLWZg9DAJ')
- - lang: bash
- label: Spree CLI
- source: spree api delete /stock_locations/{id}
+ **Required scope:** `write_products` (for API-key authentication).
parameters:
- name: x-spree-api-key
in: header
@@ -25568,38 +33808,75 @@ paths:
type: string
responses:
'204':
- description: stock location deleted
- "/api/v3/admin/stock_movements":
- get:
- summary: List stock movements
+ 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:
- - Stock Movements
+ - Product Types
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the stock ledger, newest first. Every row says what happened to
- stock (`kind`) and carries a direct reference to what caused it, so a
- merchant can answer "why is this number what it is?" from the data.
+ Backfills the type's option types and categories onto the products that
+ already carry it. Additive and idempotent — nothing is removed, and
+ re-running is safe.
- Kinds are `received` (goods arrived), `allocated` (stock promised to a
- placed order), `shipped` (promised stock left), `released` (a promise
- withdrawn) and `adjusted` (a manual correction, which always carries a
- `reason`).
+ Runs in the background; the response reports how many products the type
+ currently has.
- Movements are immutable — reversing one means writing its counterpart
- through the resource that caused it, which is why there is no create,
- update or delete here.
- Filter with Ransack predicates such as `q[kind_eq]`,
- `q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or
- `q[created_at_gteq]`.
+ **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:
+ example:
+ products_count: 0
+ schema:
+ type: object
+ properties:
+ products_count:
+ type: integer
+ "/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,
+ in the order sellers work through it.
- `kind` is null on rows written before Spree 6.0 until
- `spree:migrate_stock_movements_to_typed_rows` has run.
+ Each row is one configured requirement. `required` says whether it
+ stands between the seller and approval — the others are shown as
+ recommended and counted in their progress, but never block. `active`
+ switches one off without losing how it was worded.
- **Required scope:** `read_stock` (for API-key authentication).
+ **Required scope:** `read_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25611,12 +33888,12 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: stockMovements } = await client.stockMovements.list({
- q: { kind_eq: 'allocated' },
- })
+ // The checklist in the order sellers work through it. `required` items block
+ // approval; the rest are shown as recommended.
+ const { data: sellerRequirements } = await client.sellerRequirements.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
- source: spree api get /stock_movements -d '{"q":{"kind_eq":"allocated"}}'
+ source: spree api get /seller_requirements -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -25626,82 +33903,84 @@ 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[kind_eq]
- in: query
- required: false
- description: Filter by kind ('received', 'allocated', 'shipped', 'released',
- 'adjusted')
- schema:
- type: string
- - name: q[stock_level_id_eq]
- in: query
- required: false
- description: Filter by stock level, e.g. sl_1234567890
- 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 movements found
+ description: seller requirements found
content:
application/json:
+ example:
+ data:
+ - id: selreq_UkLWZg9DAJ
+ position: 1
+ active: true
+ required: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ kind: accept_terms
+ name: Accept terms
+ description: Read and accept the marketplace terms
+ preferences:
+ terms_effective_from:
+ terms_url:
+ custom_field_definition_ids: []
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: 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/StockMovement"
+ "$ref": "#/components/schemas/SellerRequirement"
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
+ post:
+ summary: Add a seller requirement
tags:
- - Stock Movements
+ - Seller Requirements
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single stock movement by prefixed ID.
+ Adds something the marketplace asks of its sellers.
- **Required scope:** `read_stock` (for API-key authentication).
+ `type` comes from `GET /seller_requirements/types`, which also
+ describes the configuration each kind takes. Most kinds answer one
+ question and can be added once; the open-ended ones — a seller
+ confirmation, a manual check, a document — carry the question in your
+ own `name` and `description`, so a store may add as many as it needs.
+
+ A kind that reads the seller's own data (their addresses, their
+ products, whether they accepted the terms) needs nothing from the
+ seller beyond doing it. The others wait for the seller to submit
+ something, and the ones you review wait for you.
+
+
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25713,10 +33992,20 @@ paths:
secretKey: 'sk_xxx',
})
- const stockMovement = await client.stockMovements.get('sm_k5nR8xLq')
+ // Asks every seller for a business registration before they can be approved.
+ // The wording is yours — `document` is one of the open-ended kinds, so a store
+ // can add as many as it needs, each with its own instructions.
+ const sellerRequirement = await client.sellerRequirements.create({
+ type: 'document',
+ name: 'Business registration',
+ description: 'A copy of your certificate of incorporation.',
+ required: true,
+ preferences: { accepted_content_types: ['application/pdf'] },
+ })
- lang: bash
label: Spree CLI
- source: spree api get /stock_movements/{id}
+ source: spree api post /seller_requirements -d '{"type":"document","name":"Business
+ registration","description":"A copy of your certificate of incorporation.","required":true,"preferences":{"accepted_content_types":["application/pdf"]}}'
parameters:
- name: x-spree-api-key
in: header
@@ -25726,40 +34015,101 @@ paths:
- 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
+ '201':
+ description: seller requirement created
content:
application/json:
+ example:
+ id: selreq_UkLWZg9DAJ
+ position: 1
+ active: true
+ required: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ kind: document
+ name: Business registration
+ description: Upload this document for the marketplace to review
+ preferences: {}
+ custom_field_definition_ids: []
+ allow_multiple: true
+ accepts_submissions: true
+ reviewed_by_operator: true
schema:
- "$ref": "#/components/schemas/StockMovement"
- '404':
- description: stock movement not found
+ "$ref": "#/components/schemas/SellerRequirement"
+ '422':
+ description: kind is not registered
content:
application/json:
+ example:
+ error:
+ code: unknown_seller_requirement_type
+ message: Unknown type
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/store":
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - type
+ properties:
+ type:
+ type: string
+ example: document
+ description: The kind, from `GET /seller_requirements/types`.
+ name:
+ type: string
+ example: Business registration
+ 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
+ example: A copy of your certificate of incorporation.
+ description: Instructions shown to the seller.
+ required:
+ type: boolean
+ example: true
+ description: Whether this blocks approval. Off means recommended.
+ active:
+ type: boolean
+ example: true
+ position:
+ type: integer
+ example: 1
+ description: Place in the checklist.
+ preferences:
+ type: object
+ example:
+ accepted_content_types:
+ - application/pdf
+ description: Configuration for this kind, per its `preference_schema`.
+ "/api/v3/admin/seller_requirements/types":
get:
- summary: Get the current store
+ summary: List seller requirement kinds
tags:
- - Settings
+ - Seller Requirements
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.
+ The kinds you can add, and the shape of each one's configuration form.
- **Required scope:** `read_settings` (for API-key authentication).
+ `configured` says the store already has this kind — meaningful only
+ where `allow_multiple` is false. `accepts_submissions` says the seller
+ records having done it rather than it being read from their data, and
+ `reviewed_by_operator` says what they send waits for you.
+
+ A marketplace that registers its own kind server-side sees it here
+ without this endpoint changing.
+
+
+ **Required scope:** `read_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25771,10 +34121,12 @@ paths:
secretKey: 'sk_xxx',
})
- const store = await client.store.get()
+ // What you can ask for, and the configuration each kind takes. A kind your own
+ // code registers server-side shows up here too.
+ const { data: requirementTypes } = await client.sellerRequirements.types()
- lang: bash
label: Spree CLI
- source: spree api get /store
+ source: spree api get /seller_requirements/types
parameters:
- name: x-spree-api-key
in: header
@@ -25784,33 +34136,239 @@ paths:
- 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
+ description: kinds found
content:
application/json:
+ example:
+ data:
+ - type: accept_terms
+ name: Accept terms
+ description: Read and accept the marketplace terms
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema:
+ - key: terms_effective_from
+ type: string
+ default:
+ - key: terms_url
+ type: string
+ default:
+ - type: complete_profile
+ name: Complete profile
+ description: Fill in the public profile shoppers see
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema:
+ - key: require_cover_photo
+ type: boolean
+ default: false
+ - key: require_contact_email
+ type: boolean
+ default: true
+ - key: require_about
+ type: boolean
+ default: true
+ - key: require_logo
+ type: boolean
+ default: true
+ - type: billing_address
+ name: Billing address
+ description: The address your payouts are billed from
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema: []
+ - type: returns_address
+ name: Returns address
+ description: The address customer returns are sent to
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema: []
+ - type: delivery_method
+ name: Delivery method
+ description: Offer at least one way to ship your orders
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema: []
+ - type: minimum_products
+ name: Minimum products
+ description: List at least this many products
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema:
+ - key: minimum_count
+ type: integer
+ default: 1
+ - type: payout_account
+ name: Payout Account
+ description: ''
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema: []
+ - type: required_custom_fields
+ name: Required custom fields
+ description: Fill in the details the marketplace asks for
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields:
+ - custom_field_definition_ids
+ preference_schema: []
+ - type: policy
+ name: Seller policy
+ description: Publish a policy with this name
+ allow_multiple: true
+ accepts_submissions: false
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema: []
+ - type: attestation
+ name: Seller confirmation
+ description: Confirm this yourself before you are approved
+ allow_multiple: true
+ accepts_submissions: true
+ reviewed_by_operator: false
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema: []
+ - type: operator_review
+ name: Manual check
+ description: The marketplace checks this by hand before approving
+ you
+ allow_multiple: true
+ accepts_submissions: true
+ reviewed_by_operator: true
+ configured: false
+ addable: true
+ accepted_content_types: []
+ association_fields: []
+ preference_schema: []
+ - type: document
+ name: Document
+ description: Upload this document for the marketplace to review
+ allow_multiple: true
+ accepts_submissions: true
+ reviewed_by_operator: true
+ configured: false
+ addable: true
+ accepted_content_types:
+ - application/pdf
+ - image/jpeg
+ - image/png
+ - image/heic
+ - image/webp
+ - application/msword
+ - application/vnd.openxmlformats-officedocument.wordprocessingml.document
+ association_fields: []
+ preference_schema: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ type:
+ type: string
+ example: document
+ name:
+ type: string
+ example: Document
+ description:
+ type: string
+ example: A file the seller uploads and you review
+ allow_multiple:
+ type: boolean
+ example: true
+ accepts_submissions:
+ type: boolean
+ example: true
+ reviewed_by_operator:
+ type: boolean
+ example: true
+ configured:
+ type: boolean
+ example: false
+ addable:
+ type: boolean
+ example: true
+ description: Whether the operator may add one now. The uniqueness
+ rule is the server's, so clients filter on this rather
+ than deriving it.
+ preference_schema:
+ type: array
+ items:
+ type: object
+ "/api/v3/admin/seller_requirements/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
patch:
- summary: Update the current store
+ summary: Update a seller requirement
tags:
- - Settings
+ - Seller Requirements
security:
- api_key: []
bearer_auth: []
description: |-
- Updates the current store configuration.
+ Changes how a requirement is worded, what it asks for, where it sits in
+ the checklist, and whether it blocks approval.
- **Required scope:** `write_settings` (for API-key authentication).
+ `type` is not accepted: a saved row's kind never changes, because
+ anything a seller already submitted answered the old one.
+
+
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25822,12 +34380,14 @@ paths:
secretKey: 'sk_xxx',
})
- const store = await client.store.update({
- name: 'My Store',
+ // Asks for three products instead of one. Sellers who already met the old
+ // number see this return to their checklist.
+ const sellerRequirement = await client.sellerRequirements.update('selreq_a1b2c3', {
+ preferences: { minimum_count: 3 },
})
- lang: bash
label: Spree CLI
- source: spree api patch /store -d '{"name":"My Store"}'
+ source: spree api patch /seller_requirements/{id} -d '{"preferences":{"minimum_count":3}}'
parameters:
- name: x-spree-api-key
in: header
@@ -25837,22 +34397,32 @@ paths:
- 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
+ description: seller requirement updated
content:
application/json:
+ example:
+ id: selreq_UkLWZg9DAJ
+ position: 1
+ active: true
+ required: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ kind: minimum_products
+ name: Minimum products
+ description: List at least this many products
+ preferences:
+ minimum_count: 3
+ custom_field_definition_ids: []
+ allow_multiple: false
+ accepts_submissions: false
+ reviewed_by_operator: false
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/SellerRequirement"
requestBody:
content:
application/json:
@@ -25861,29 +34431,37 @@ paths:
properties:
name:
type: string
- example: My Store
- preferred_admin_locale:
- type: string
- example: en
- preferred_timezone:
- type: string
- example: UTC
- preferred_weight_unit:
- type: string
- example: kg
- preferred_unit_system:
+ example: Proof of business registration
+ description:
type: string
- example: metric
- "/api/v3/admin/tags":
- get:
- summary: List tags
+ example: A copy of your certificate of incorporation.
+ required:
+ type: boolean
+ example: false
+ active:
+ type: boolean
+ example: true
+ position:
+ type: integer
+ example: 2
+ preferences:
+ type: object
+ example:
+ minimum_count: 3
+ delete:
+ summary: Delete a seller requirement
tags:
- - Settings
+ - Seller Requirements
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: |-
+ Stops asking for this. Anything sellers already submitted against it
+ goes too — to keep the record while pausing the ask, set `active` to
+ false instead.
+
+
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -25895,13 +34473,12 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: tags } = await client.tags.list({
- taggable_type: 'Spree::User',
- q: 'vip',
- })
+ // Stops asking for this, and deletes what sellers submitted against it. To
+ // keep the record while pausing the ask, update it with `active: false`.
+ await client.sellerRequirements.delete('selreq_a1b2c3')
- lang: bash
label: Spree CLI
- source: spree api get /tags -d '{"taggable_type":"Spree::User","q":"vip"}'
+ source: spree api delete /seller_requirements/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -25913,43 +34490,42 @@ paths:
required: true
schema:
type: string
- - name: taggable_type
- in: query
- required: true
- description: Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)
- schema:
- type: string
- - name: q
- in: query
- required: false
- description: Optional case-insensitive substring filter
- schema:
- type: string
responses:
- '200':
- description: tags found
- '422':
- description: invalid taggable type
- "/api/v3/admin/tax_rates":
+ '204':
+ description: seller requirement deleted
+ "/api/v3/admin/sellers":
get:
- summary: List tax rates
+ summary: List sellers
tags:
- - Settings
+ - Sellers
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).
+ Returns the sellers on this marketplace. `status` says where each one
+ is in its life on the marketplace, and `sellable` answers the question
+ the status alone cannot: an approved seller who is away cannot be
+ bought from either.
- Markets using an external tax provider ignore these rows — that
- provider carries its own jurisdiction data.
+ **Required scope:** `read_sellers` (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',
+ })
- **Required scope:** `read_settings` (for API-key authentication).
+ // `sellable` is the one to read for "can this seller be bought from" — an
+ // approved seller who is away answers false.
+ const { data: sellers } = await client.sellers.list({ page: 1, limit: 25 })
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /sellers -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -25980,12 +34556,12 @@ paths:
description: Filter by name (contains)
schema:
type: string
- - name: q[included_in_price_true]
+ - name: q[status_eq]
in: query
required: false
- description: Only rates included in the product price
+ description: Filter by status
schema:
- type: boolean
+ type: string
- name: sort
in: query
required: false
@@ -25994,16 +34570,58 @@ paths:
type: string
responses:
'200':
- description: tax rates found
+ description: sellers found
content:
application/json:
+ example:
+ data:
+ - id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: pending
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata: {}
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: false
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
+ 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"
+ "$ref": "#/components/schemas/Seller"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
@@ -26013,380 +34631,178 @@ paths:
description: unauthorized
content:
application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
post:
- summary: Create a tax rate
+ summary: Create a seller
tags:
- - Settings
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a tax rate for the current store. Give either `amount` as a
- decimal (`0.19`) or `amount_percentage` as a percentage (`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.
-
+ Opens a seller record. The seller starts as `pending` and has no team
+ yet — invite someone to run it with the `invite` action below.
- **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"
- amount:
- type: string
- description: Rate as a decimal, e.g. "0.19"
- amount_percentage:
- type: number
- description: Rate as a percentage, 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
- amount:
- type: string
- amount_percentage:
- type: number
- 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.
+ `status` is deliberately not writable here or on update: every move
+ through the lifecycle is its own action, because each one does more
+ than set a column.
- **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
- "/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_sellers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
- **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
- '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/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.
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
- **Required scope:** `read_products` (for API-key authentication).
+ // The seller starts as `pending` and has no team yet — invite someone to run
+ // it next.
+ const seller = await client.sellers.create({
+ name: 'Northwind Books',
+ contact_email: '[email protected]',
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /sellers -d '{"name":"Northwind Books","contact_email":"[email protected]"}'
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`).
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
- '200':
- description: coverage found
+ '201':
+ description: seller created
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
- "/api/v3/admin/products/{product_id}/variants":
+ id: sel_gbHJdmfrXB
+ name: Northwind Books
+ slug: northwind-books
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: pending
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata: {}
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: false
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
+ schema:
+ "$ref": "#/components/schemas/Seller"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank and Slug can't be blank
+ details:
+ name:
+ - can't be blank
+ slug:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ properties:
+ name:
+ type: string
+ example: Northwind Books
+ slug:
+ type: string
+ example: northwind-books
+ description: Derived from the name when omitted.
+ contact_email:
+ type: string
+ nullable: true
+ billing_email:
+ type: string
+ nullable: true
+ about:
+ type: string
+ example: "<p>Independent bookshop.</p>"
+ nullable: true
+ tax_remittance:
+ type: string
+ enum:
+ - seller
+ - platform
+ example: seller
+ payouts_schedule_interval:
+ type: string
+ enum:
+ - daily
+ - weekly
+ - biweekly
+ - monthly
+ - manual
+ nullable: true
+ minimum_payout_amount:
+ type: string
+ example: '25.0'
+ nullable: true
+ "/api/v3/admin/sellers/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: Seller prefixed ID
+ schema:
+ type: string
get:
- summary: List product variants
+ summary: Get a seller
tags:
- - Variants
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a paginated list of variants for a product, including the default variant.
+ Returns a single seller, including its settlement and tax configuration.
- **Required scope:** `read_products` (for API-key authentication).
+ **Required scope:** `read_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26398,12 +34814,10 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: variants } = await client.products.variants.list('prod_86Rf07xd4z', {
- expand: ['prices', 'stock_levels'],
- })
+ const seller = await client.sellers.get('sel_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /products/{product_id}/variants -d '{"expand":["prices","stock_levels"]}'
+ source: spree api get /sellers/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -26413,60 +34827,70 @@ paths:
- 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: 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
responses:
'200':
- description: variants found
- post:
- summary: Create a variant
+ description: seller found
+ content:
+ application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: pending
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata: {}
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: false
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
+ schema:
+ "$ref": "#/components/schemas/Seller"
+ '404':
+ description: seller not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Seller not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a seller
tags:
- - Variants
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new variant for a product. Supports nested prices and stock items.
-
- Option types and values are auto-created if they don't exist.
- Prices are upserted by currency. Stock items are upserted by stock location.
+ Updates the seller's profile and the settlement configuration the
+ operator owns. A `status` sent here is ignored — use the lifecycle
+ actions.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26478,21 +34902,16 @@ paths:
secretKey: 'sk_xxx',
})
- const variant = await client.products.variants.create('prod_86Rf07xd4z', {
- sku: 'TSHIRT-L-NAVY',
- options: [
- { name: 'size', value: 'Large' },
- { name: 'color', value: 'navy' },
- ],
- prices: [
- { currency: 'USD', amount: '29.99', compare_at_amount: '34.99' },
- { currency: 'EUR', amount: '27.99' },
- ],
- stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 25 }],
+ // `status` is not writable here: each move through the lifecycle is its own
+ // action, because each one does more than set a column.
+ const seller = await client.sellers.update('sel_UkLWZg9DAJ', {
+ billing_email: '[email protected]',
+ payouts_schedule_interval: 'weekly',
+ minimum_payout_amount: '25.0',
})
- lang: bash
label: Spree CLI
- source: spree api post /products/{product_id}/variants -d '{"sku":"TSHIRT-L-NAVY","options":[{"name":"size","value":"Large"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99","compare_at_amount":"34.99"},{"currency":"EUR","amount":"27.99"}],"stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":25}]}'
+ source: spree api patch /sellers/{id} -d '{"billing_email":"[email protected]","payouts_schedule_interval":"weekly","minimum_payout_amount":"25.0"}'
parameters:
- name: x-spree-api-key
in: header
@@ -26502,22 +34921,87 @@ paths:
- 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
+ '200':
+ description: seller address written inline
+ content:
+ application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: pending
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata: {}
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: false
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name:
+ last_name:
+ full_name: ''
+ address1: 1 Seller Way
+ address2:
+ postal_code: EC1A 1BB
+ city: London
+ phone: '555'
+ company: Sparks Trading Ltd
+ country_name: United Kingdom
+ country_code: GB
+ state_text:
+ state_code:
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr:
+ country_iso: GB
+ state_name:
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ latitude:
+ longitude:
+ customer_id:
+ owner_id: sel_UkLWZg9DAJ
+ owner_type: Spree::Seller
+ schema:
+ "$ref": "#/components/schemas/Seller"
'422':
description: validation error
content:
application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -26526,100 +35010,140 @@ paths:
schema:
type: object
properties:
- sku:
+ name:
type: string
- example: SKU-001
- cost_price:
+ example: Sparks Audio Ltd
+ billing_email:
type: string
- example: '10.00'
- cost_currency:
+ nullable: true
+ payouts_schedule_interval:
type: string
- example: USD
- weight:
- type: number
- height:
- type: number
- width:
- type: number
- depth:
- type: number
- weight_unit:
+ enum:
+ - daily
+ - weekly
+ - biweekly
+ - monthly
+ - manual
+ nullable: true
+ minimum_payout_amount:
type: string
- dimensions_unit:
+ example: '25.0'
+ nullable: true
+ holiday_mode_until:
type: string
- track_inventory:
- type: boolean
- tax_category_id:
+ format: date-time
+ nullable: true
+ logo:
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
- example: size
- value:
- type: string
- example: Small
- position:
- type: integer
- barcode:
+ 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
- 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
- "/api/v3/admin/products/{product_id}/variants/{id}":
- get:
- summary: Get a variant
+ 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
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ company:
+ type: string
+ example: Sparks Audio Ltd
+ address1:
+ type: string
+ example: 1 Seller Way
+ address2:
+ type: string
+ example: Unit 4
+ city:
+ type: string
+ example: London
+ postal_code:
+ type: string
+ example: EC1A 1BB
+ phone:
+ type: string
+ example: "+44 20 7946 0000"
+ country_code:
+ type: string
+ example: GB
+ state_code:
+ type: string
+ example: NY
+ state_name:
+ type: string
+ example: New York
+ label:
+ type: string
+ example: Head office
+ 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
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ company:
+ type: string
+ example: Sparks Audio Ltd
+ address1:
+ type: string
+ example: 1 Seller Way
+ address2:
+ type: string
+ example: Unit 4
+ city:
+ type: string
+ example: London
+ postal_code:
+ type: string
+ example: EC1A 1BB
+ phone:
+ type: string
+ example: "+44 20 7946 0000"
+ country_code:
+ type: string
+ example: GB
+ state_code:
+ type: string
+ example: NY
+ state_name:
+ type: string
+ example: New York
+ label:
+ type: string
+ example: Head office
+ delete:
+ summary: Delete a seller
tags:
- - Variants
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single variant by ID.
+ Soft-deletes the seller. Their products are kept and left without a
+ seller rather than deleted — what happens to a departed seller's
+ catalog is the operator's decision.
- **Required scope:** `read_products` (for API-key authentication).
+
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26631,12 +35155,12 @@ paths:
secretKey: 'sk_xxx',
})
- const variant = await client.products.variants.get('prod_86Rf07xd4z', 'variant_k5nR8xLq', {
- expand: ['prices', 'stock_levels'],
- })
+ // Soft-deletes the seller. Their products stay in the catalog without a
+ // seller rather than being deleted with them.
+ await client.sellers.delete('sel_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api get /products/{product_id}/variants/{id} -d '{"expand":["prices","stock_levels"]}'
+ source: spree api delete /sellers/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -26646,56 +35170,37 @@ paths:
- 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
- '404':
- description: variant not found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a variant
+ 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:
- - Variants
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Updates a variant. Only provided fields are updated.
+ Sends an invitation to the seller's own team and moves the seller to
+ `invited`. The person becomes a member when they accept, and can then
+ sign in to the seller panel.
- **Required scope:** `write_products` (for API-key authentication).
+ `role_id` must name a role this seller owns; omit it for the seller's
+ own admin role. Re-inviting is allowed — an invitation expires, or the
+ first one goes to the wrong address.
+
+
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26707,13 +35212,14 @@ paths:
secretKey: 'sk_xxx',
})
- const variant = await client.products.variants.update('prod_86Rf07xd4z', 'variant_k5nR8xLq', {
- sku: 'UPDATED-SKU',
- stock_levels: [{ stock_location_id: 'sloc_UkLWZg9DAJ', count_on_hand: 75 }],
+ // They join the seller's team when they accept, and can then sign in to the
+ // seller panel. Omit `role_id` for the seller's own admin role.
+ const seller = await client.sellers.invite('sel_UkLWZg9DAJ', {
+ email: '[email protected]',
})
- lang: bash
label: Spree CLI
- source: spree api patch /products/{product_id}/variants/{id} -d '{"sku":"UPDATED-SKU","stock_levels":[{"stock_location_id":"sloc_UkLWZg9DAJ","count_on_hand":75}]}'
+ source: spree api post /sellers/{id}/invite -d '{"email":"[email protected]"}'
parameters:
- name: x-spree-api-key
in: header
@@ -26723,123 +35229,83 @@ paths:
- 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
+ '201':
+ description: invitation sent
+ content:
+ application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: invited
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata: {}
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: false
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
+ schema:
+ "$ref": "#/components/schemas/Seller"
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - email
properties:
- sku:
- type: string
- example: SKU-001
- cost_price:
- type: string
- example: '10.00'
- cost_currency:
- type: string
- example: USD
- 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:
+ email:
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
- position:
- type: integer
- barcode:
+ role_id:
type: string
- 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 variant
+ example: role_UkLWZg9DAJ
+ 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:
- - Variants
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Soft-deletes a variant.
+ Lets the seller sell. This is also the way back for one that was
+ suspended or turned down, and it clears any holiday along with the
+ suspension.
- **Required scope:** `write_products` (for API-key authentication).
+
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26851,10 +35317,12 @@ paths:
secretKey: 'sk_xxx',
})
- await client.products.variants.delete('prod_86Rf07xd4z', 'variant_k5nR8xLq')
+ // Also the way back for a seller that was suspended or turned down — and it
+ // clears any holiday along with the suspension.
+ const seller = await client.sellers.approve('sel_UkLWZg9DAJ')
- lang: bash
label: Spree CLI
- source: spree api delete /products/{product_id}/variants/{id}
+ source: spree api patch /sellers/{id}/approve -d '{ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -26864,48 +35332,79 @@ paths:
- 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":
+ '200':
+ description: seller approved
+ content:
+ application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: approved
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata: {}
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: true
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
+ schema:
+ "$ref": "#/components/schemas/Seller"
+ '422':
+ description: seller cannot be approved from its current status
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: already_approved
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/sellers/{id}/suspend":
parameters:
- - name: webhook_endpoint_id
+ - name: id
in: path
required: true
- description: Parent webhook endpoint ID
+ description: Seller prefixed ID
schema:
type: string
- get:
- summary: List webhook deliveries
+ patch:
+ summary: Suspend a seller
tags:
- - Webhooks
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns delivery attempts for the given endpoint, most recent first.
- Each row carries the original request payload, the response code
- (when the receiver replied), the execution time, and any transport
- error — everything needed to audit failures and decide whether to
- redeliver.
+ Stops a trading seller from selling. Their catalog and history stay,
+ and approving reinstates them. Use this rather than `reject` for a
+ seller already on the marketplace — it says something different, and
+ it can be undone.
- **Required scope:** `read_webhooks` (for API-key authentication).
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26917,10 +35416,14 @@ paths:
secretKey: 'sk_xxx',
})
- const deliveries = await client.webhookEndpoints.deliveries.list('whe_xxx')
+ // Stops a trading seller from selling. Their catalog and history stay, and
+ // approving reinstates them.
+ const seller = await client.sellers.suspend('sel_UkLWZg9DAJ', {
+ reason: 'Counterfeit goods',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /webhook_endpoints/{webhook_endpoint_id}/deliveries
+ source: spree api patch /sellers/{id}/suspend -d '{"reason":"Counterfeit goods"}'
parameters:
- name: x-spree-api-key
in: header
@@ -26930,82 +35433,77 @@ 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[event_name_eq]
- in: query
- required: false
- description: Filter by event name (exact)
- schema:
- type: string
- - name: q[success_eq]
- in: query
- required: false
- description: Filter by success flag
- schema:
- type: boolean
- - 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
responses:
'200':
- description: deliveries found
- '404':
- description: parent webhook endpoint not found
+ description: seller suspended
content:
application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: suspended
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata:
+ suspension_reason: Counterfeit goods
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: false
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":
+ "$ref": "#/components/schemas/Seller"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ reason:
+ type: string
+ example: Counterfeit goods
+ "/api/v3/admin/sellers/{id}/reject":
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
+ description: Seller prefixed ID
schema:
type: string
- get:
- summary: Get a webhook delivery
+ patch:
+ summary: Reject a seller
tags:
- - Webhooks
+ - Sellers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single delivery attempt with the full request payload and
- the response body the receiver returned. Use this for ad-hoc debug
- of failed deliveries.
+ Turns down an applicant who never traded. A seller already selling is
+ suspended instead; rejecting one is refused.
- **Required scope:** `read_webhooks` (for API-key authentication).
+ **Required scope:** `write_sellers` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27017,10 +35515,14 @@ paths:
secretKey: 'sk_xxx',
})
- const delivery = await client.webhookEndpoints.deliveries.get('whe_xxx', 'whd_xxx')
+ // For an applicant who never traded. A seller already selling is suspended
+ // instead.
+ const seller = await client.sellers.reject('sel_UkLWZg9DAJ', {
+ reason: 'Incomplete paperwork',
+ })
- lang: bash
label: Spree CLI
- source: spree api get /webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}
+ source: spree api patch /sellers/{id}/reject -d '{"reason":"Incomplete paperwork"}'
parameters:
- name: x-spree-api-key
in: header
@@ -27030,55 +35532,80 @@ paths:
- 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
- '404':
- description: delivery not found
+ description: seller rejected
content:
application/json:
example:
- error:
- code: record_not_found
- message: Webhook delivery not found
+ id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: rejected
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ metadata:
+ rejection_reason: Incomplete paperwork
+ holiday_mode_until:
+ terms_accepted_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ deleted_at:
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: false
+ products_count: 0
+ users_count: 0
+ onboarding_progress:
+ done: 0
+ total: 0
+ onboarding_complete: true
+ legal_name:
+ registration_number:
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
+ "$ref": "#/components/schemas/Seller"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ reason:
+ type: string
+ example: Incomplete paperwork
+ "/api/v3/admin/stock_levels/bulk_upsert":
post:
- summary: Redeliver a webhook delivery
+ summary: Bulk-upsert stock levels
tags:
- - Webhooks
+ - Stock
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new delivery row with the same payload + event_name and
- queues it. The original row is preserved for audit history.
+ Sets stock levels for many (variant, location) pairs at once — what a
+ warehouse or ERP feed posts on a schedule.
+ Each row names its variant and stock location by Spree id
+ (`variant_id`, `stock_location_id`).
- **Required scope:** `write_webhooks` (for API-key authentication).
+ A row carries either `count_on_hand` — the absolute level the external
+ system reports — or `adjustment`, a relative change for feeds that
+ report movements instead. Every change is written as a stock movement,
+ so a merchant can still see why a figure moved.
+
+ The response carries `stock_level_count`: how many rows moved a shelf.
+
+
+ **Required scope:** `write_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27090,13 +35617,18 @@ paths:
secretKey: 'sk_xxx',
})
- // Creates a new delivery row with the same payload + event_name and queues
- // it. The original row is preserved for audit history.
- const delivery = await client.webhookEndpoints.deliveries.redeliver('whe_xxx', 'whd_xxx')
+ const { stock_level_count } = await client.stockLevels.bulkUpsert({
+ stock_levels: [
+ {
+ variant_id: 'variant_xxx',
+ stock_location_id: 'sloc_xxx',
+ count_on_hand: 42,
+ },
+ ],
+ })
- lang: bash
label: Spree CLI
- source: spree api post /webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver
- -d '{ ... }'
+ source: spree api post /stock_levels/bulk_upsert -d '{"stock_levels":[{"variant_id":"variant_xxx","stock_location_id":"sloc_xxx","count_on_hand":42}]}'
parameters:
- name: x-spree-api-key
in: header
@@ -27106,28 +35638,93 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
- '201':
- description: redelivery queued
- "/api/v3/admin/webhook_endpoints":
+ '200':
+ description: stock levels updated
+ content:
+ application/json:
+ example:
+ stock_level_count: 1
+ '422':
+ description: row is missing a level
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_stock_levels
+ message: Each row must name a variant and stock location in this
+ store, and either a count_on_hand or an adjustment.
+ details:
+ rows:
+ - index: 0
+ missing:
+ - count_on_hand
+ 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
+ example: variant_xY9
+ stock_location_id:
+ type: string
+ example: sloc_aBc
+ count_on_hand:
+ type: integer
+ nullable: true
+ example: 42
+ adjustment:
+ type: integer
+ nullable: true
+ example: -3
+ backorderable:
+ type: boolean
+ nullable: true
+ "/api/v3/admin/stock_movements":
get:
- summary: List webhook endpoints
+ summary: List stock movements
tags:
- - Webhooks
+ - Stock Movements
security:
- api_key: []
bearer_auth: []
description: |-
- Returns outbound webhook subscriptions for the current store. Each
- endpoint receives a signed POST when any subscribed event fires.
- `secret_key` is `null` on list reads — the plaintext is delivered
- exactly once on create.
+ Returns the stock ledger, newest first. Every row says what happened to
+ stock (`kind`) and carries a direct reference to what caused it, so a
+ merchant can answer "why is this number what it is?" from the data.
+ Kinds are `received` (goods arrived), `allocated` (stock promised to a
+ placed order), `shipped` (promised stock left), `released` (a promise
+ withdrawn) and `adjusted` (a manual correction, which always carries a
+ `reason`).
- **Required scope:** `read_webhooks` (for API-key authentication).
+ Movements are immutable — reversing one means writing its counterpart
+ through the resource that caused it, which is why there is no create,
+ update or delete here.
+
+ Filter with Ransack predicates such as `q[kind_eq]`,
+ `q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or
+ `q[created_at_gteq]`.
+
+ `kind` is null on rows written before Spree 6.0 until
+ `spree:migrate_stock_movements_to_typed_rows` has run.
+
+
+ **Required scope:** `read_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27139,10 +35736,12 @@ paths:
secretKey: 'sk_xxx',
})
- const endpoints = await client.webhookEndpoints.list()
+ const { data: stockMovements } = await client.stockMovements.list({
+ q: { kind_eq: 'allocated' },
+ })
- lang: bash
label: Spree CLI
- source: spree api get /webhook_endpoints
+ source: spree api get /stock_movements -d '{"q":{"kind_eq":"allocated"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -27167,22 +35766,17 @@ paths:
description: Number of records per page
schema:
type: integer
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: q[url_cont]
+ - name: q[kind_eq]
in: query
required: false
- description: Filter by URL (contains)
+ description: Filter by kind ('received', 'allocated', 'shipped', 'released',
+ 'adjusted')
schema:
type: string
- - name: sort
+ - name: q[stock_level_id_eq]
in: query
required: false
- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
+ description: Filter by stock level, e.g. sl_1234567890
schema:
type: string
- name: fields
@@ -27193,30 +35787,23 @@ paths:
type: string
responses:
'200':
- description: webhook endpoints found
+ description: stock movements found
content:
application/json:
example:
data:
- - id: whe_UkLWZg9DAJ
- name: Order pipeline
- url: https://shop.example.com/webhooks/orders
- active: true
- subscriptions:
- - order.created
- - order.completed
- - product.created
- disabled_reason:
+ - id: sm_UkLWZg9DAJ
+ quantity: 5
+ kind: adjusted
+ reason: Cycle count
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- disabled_at:
- secret_key:
- last_delivery_at:
- recent_delivery_count: 0
- recent_failure_count: 0
- total_delivery_count: 0
- successful_delivery_count: 0
- failed_delivery_count: 0
+ stock_level_id: sl_gbHJdmfrXB
+ order_id:
+ fulfillment_id:
+ return_id:
+ exchange_id:
+ stock_transfer_id:
meta:
page: 1
limit: 25
@@ -27227,117 +35814,47 @@ paths:
in: 1
previous:
next:
+ 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:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
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
- `secret_key` is returned **once** in this response — persist it
- immediately to verify incoming webhook signatures. Subsequent reads
- return `null` for the secret. Pass an empty `subscriptions` array or
- omit it to receive every event.
-
-
- **Required scope:** `write_webhooks` (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 endpoint = await client.webhookEndpoints.create({
- name: 'Order pipeline',
- url: 'https://example.com/webhooks/orders',
- active: true,
- subscriptions: ['order.placed', 'order.canceled'],
- })
-
- // The plaintext `secret_key` is returned exactly once on create — persist it
- // immediately so you can verify incoming webhook signatures. Subsequent reads
- // will return `null`.
- const signingSecret = endpoint.secret_key
- - lang: bash
- label: Spree CLI
- source: spree api post /webhook_endpoints -d '{"name":"Order pipeline","url":"https://example.com/webhooks/orders","active":true,"subscriptions":["order.placed","order.canceled"]}'
- parameters:
- - name: x-spree-api-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
- '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
- example: Order pipeline
- url:
- type: string
- example: https://example.com/webhooks/orders
- active:
- type: boolean
- example: true
- subscriptions:
- type: array
- items:
- type: string
- example:
- - order.placed
- - order.canceled
- "/api/v3/admin/webhook_endpoints/{id}":
+ "/api/v3/admin/stock_movements/{id}":
parameters:
- name: id
in: path
required: true
- description: Webhook endpoint ID
+ description: Stock movement ID
schema:
type: string
get:
- summary: Get a webhook endpoint
+ summary: Get a stock movement
tags:
- - Webhooks
+ - Stock Movements
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single webhook endpoint by prefixed ID.
+ Returns a single stock movement by prefixed ID.
- **Required scope:** `read_webhooks` (for API-key authentication).
+ **Required scope:** `read_stock` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -27349,10 +35866,10 @@ paths:
secretKey: 'sk_xxx',
})
- const endpoint = await client.webhookEndpoints.get('whe_xxx')
+ const stockMovement = await client.stockMovements.get('sm_k5nR8xLq')
- lang: bash
label: Spree CLI
- source: spree api get /webhook_endpoints/{id}
+ source: spree api get /stock_movements/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -27373,363 +35890,34 @@ paths:
type: string
responses:
'200':
- description: webhook endpoint found
+ description: stock movement found
content:
application/json:
example:
- id: whe_UkLWZg9DAJ
- name: Order pipeline
- url: https://shop.example.com/webhooks/orders
- active: true
- subscriptions:
- - order.created
- - order.completed
- - product.created
- disabled_reason:
+ id: sm_UkLWZg9DAJ
+ quantity: 5
+ kind: adjusted
+ reason: Cycle count
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- disabled_at:
- secret_key:
- last_delivery_at:
- recent_delivery_count: 0
- recent_failure_count: 0
- total_delivery_count: 0
- successful_delivery_count: 0
- failed_delivery_count: 0
+ stock_level_id: sl_gbHJdmfrXB
+ order_id:
+ fulfillment_id:
+ return_id:
+ exchange_id:
+ stock_transfer_id:
+ schema:
+ "$ref": "#/components/schemas/StockMovement"
'404':
- description: webhook endpoint not found
+ description: stock movement not found
content:
application/json:
example:
error:
code: record_not_found
- message: Webhook endpoint not found
- 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.
- Toggling `active` here is equivalent to calling `disable`/`enable`
- without an audit reason.
-
-
- **Required scope:** `write_webhooks` (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 endpoint = await client.webhookEndpoints.update('whe_xxx', {
- name: 'Order pipeline (v2)',
- subscriptions: ['order.placed', 'order.canceled', 'order.paid'],
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /webhook_endpoints/{id} -d '{"name":"Order pipeline
- (v2)","subscriptions":["order.placed","order.canceled","order.paid"]}'
- parameters:
- - name: x-spree-api-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
- '422':
- description: validation error
- content:
- application/json:
+ message: Stock movement not found
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.
-
- **Required scope:** `write_webhooks` (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.webhookEndpoints.delete('whe_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api delete /webhook_endpoints/{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: 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
- verify the endpoint is reachable and your signature verification
- accepts Spree's payloads.
-
-
- **Required scope:** `write_webhooks` (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',
- })
-
- // Fires a synthetic `webhook.test` delivery so you can verify the endpoint is
- // reachable and your signature-verification code accepts Spree's payloads.
- const delivery = await client.webhookEndpoints.sendTest('whe_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api post /webhook_endpoints/{id}/send_test -d '{ ... }'
- parameters:
- - name: x-spree-api-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
- "/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.
-
- **Required scope:** `write_webhooks` (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',
- })
-
- // Re-enable an endpoint that was auto-disabled after repeated delivery failures.
- const endpoint = await client.webhookEndpoints.enable('whe_xxx')
- - lang: bash
- label: Spree CLI
- source: spree api patch /webhook_endpoints/{id}/enable -d '{ ... }'
- parameters:
- - name: x-spree-api-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:
- example:
- id: whe_UkLWZg9DAJ
- name: Order pipeline
- url: https://shop.example.com/webhooks/orders
- active: true
- subscriptions:
- - order.created
- - order.completed
- - product.created
- disabled_reason:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- disabled_at:
- secret_key:
- last_delivery_at:
- recent_delivery_count: 0
- recent_failure_count: 0
- total_delivery_count: 0
- successful_delivery_count: 0
- failed_delivery_count: 0
- "/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
- repeated delivery failures), no notification email is sent.
-
-
- **Required scope:** `write_webhooks` (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',
- })
-
- // Pause an endpoint without deleting it. The optional `reason` is shown next
- // to the disabled indicator in the admin.
- const endpoint = await client.webhookEndpoints.disable('whe_xxx', {
- reason: 'Investigating elevated 5xx rate',
- })
- - lang: bash
- label: Spree CLI
- source: spree api patch /webhook_endpoints/{id}/disable -d '{"reason":"Investigating
- elevated 5xx rate"}'
- parameters:
- - name: x-spree-api-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:
- example:
- id: whe_UkLWZg9DAJ
- name: Order pipeline
- url: https://shop.example.com/webhooks/orders
- active: false
- subscriptions:
- - order.created
- - order.completed
- - product.created
- disabled_reason: Investigating
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- disabled_at: '2026-01-15T12:00:00.000Z'
- secret_key:
- last_delivery_at:
- recent_delivery_count: 0
- recent_failure_count: 0
- total_delivery_count: 0
- successful_delivery_count: 0
- failed_delivery_count: 0
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- reason:
- type: string
- example: Investigating elevated 5xx rate
servers:
- url: http://{defaultHost}
variables:
@@ -33946,6 +42134,9 @@ components:
carrier:
type: string
nullable: true
+ carrier_name:
+ type: string
+ nullable: true
service:
type: string
nullable: true
@@ -33974,9 +42165,6 @@ components:
type: string
owner_type:
type: string
- carrier_name:
- type: string
- nullable: true
cost:
type: string
display_cost:
@@ -33994,6 +42182,7 @@ components:
- source
- status
- carrier
+ - carrier_name
- service
- tracking_number
- currency
@@ -34005,7 +42194,6 @@ components:
- updated_at
- owner_id
- owner_type
- - carrier_name
- cost
- display_cost
- integration_id
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yaml
index 08fabb316e..accce17d1d 100644
--- a/docs/api-reference/seller.yaml
+++ b/docs/api-reference/seller.yaml
@@ -81,12 +81,30 @@ paths:
description: login successful
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjE5NWY4OTE2LWI3NGQtNDg2MS1hMTQ3LTJmMDhiMzhiMWIzNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.e2XwsDONtD0x4j9jfjnHhDhAJpzhXBQ2LuIjWS1kY1k
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Jan
+ last_name: Cummerata
+ full_name: Jan Cummerata
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 1
+ status: approved
schema:
"$ref": "#/components/schemas/AuthResponse"
'401':
description: invalid credentials
content:
application/json:
+ example:
+ error:
+ code: authentication_failed
+ message: Invalid email or password
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -129,12 +147,30 @@ paths:
description: refresh successful
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjdjODEzNjdjLTBlYWEtNGUzOC1hNmRjLTJjMTYzOTIxY2Q1MiIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.N2ttey6pvsPoOdx0F9pdUNbdT1j25ejAzpghXTbB8zo
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Magdalen
+ last_name: Hayes
+ full_name: Magdalen Hayes
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 3
+ status: approved
schema:
"$ref": "#/components/schemas/AuthResponse"
'401':
description: missing or invalid refresh-token cookie
content:
application/json:
+ example:
+ error:
+ code: invalid_refresh_token
+ message: Refresh token cookie missing
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/seller/auth/logout":
@@ -160,131 +196,242 @@ paths:
description: providers listed
content:
application/json:
+ example:
+ providers:
+ - key: email
+ kind: password
schema:
"$ref": "#/components/schemas/AuthProvidersResponse"
- "/api/v3/seller/countries":
+ "/api/v3/seller/auth/invitations/{id}/lookup":
+ parameters:
+ - name: id
+ in: path
+ description: Invitation ID from the emailed link
+ required: true
+ schema:
+ type: string
get:
- summary: List countries
+ summary: Look up an invitation
tags:
- - Countries
- security:
- - bearer_auth: []
+ - Authentication
description: |
- Countries and their states, for the panel's address forms.
+ Reads an invitation from the emailed link, before anyone signs in.
- Public reference data — the same list the storefront serves — so it is
- not narrowed to the markets this marketplace sells into: a seller filling
- in a billing address needs every country.
+ The acceptance page needs the invited address to decide whether it is
+ asking someone to set a new password or to confirm one they already have.
- Unpaginated. An address dropdown needs all ~250 at once.
+ Unauthenticated — the ID and token in the emailed link are the
+ credential. A wrong token is indistinguishable from an unknown
+ invitation: both answer `404`, so the endpoint cannot be used to
+ enumerate. An invitation onto the store's own staff rather than a seller
+ answers `404` here too.
parameters:
- - name: X-Spree-Seller-Id
- in: header
+ - name: token
+ in: query
required: true
+ description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: countries listed
+ description: invitation found
content:
application/json:
+ example:
+ id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=RgGhNP1euUCS75Nc3V1Y7YQF"
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/SellerCountry"
- meta:
- type: object
- properties:
- count:
- type: integer
- example: 250
- required:
- - count
- required:
- - data
- - meta
- "/api/v3/seller/delivery_methods":
- get:
- summary: List delivery methods
+ "$ref": "#/components/schemas/Invitation"
+ '404':
+ description: wrong token, or an invitation that can no longer be accepted
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Invitation not found, expired, or already accepted.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/auth/invitations/{id}/accept":
+ parameters:
+ - name: id
+ in: path
+ description: Invitation ID from the emailed link
+ required: true
+ schema:
+ type: string
+ post:
+ summary: Accept an invitation
tags:
- - Delivery Methods
- security:
- - bearer_auth: []
+ - Authentication
description: |
- How this seller's goods can ship: the methods they created themselves,
- plus any the marketplace shares with its sellers.
+ Accepts the invitation and returns a signed-in seller session, so the new
+ member lands in the panel rather than on a login form.
- A shared marketplace method comes back with `editable: false` — it is
- listed so the seller can see what already ships their goods, and every
- write against it is a 404.
+ The email is never taken from the request — it always comes from the
+ invitation, which is what stops the link being redirected to another
+ address.
+
+ `password` is required when no account exists for the invited address, in
+ which case it sets one. When an account already exists, the same field is
+ how the person proves the account is theirs.
parameters:
- - name: X-Spree-Seller-Id
- in: header
+ - name: token
+ in: query
required: true
+ description: The token from the emailed link
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
responses:
'200':
- description: delivery methods listed
+ description: invitation accepted, session issued
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs
+ user:
+ id: adm_gbHJdmfrXB
+ first_name: Robin
+ last_name: Ellis
+ full_name: Robin Ellis
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 31
+ status: approved
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/DeliveryMethod"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
+ "$ref": "#/components/schemas/AuthResponse"
+ '404':
+ description: wrong token, or an invitation that can no longer be accepted
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Invitation not found, expired, or already accepted.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ password:
+ type: string
+ example: password123
+ password_confirmation:
+ type: string
+ example: password123
+ first_name:
+ type: string
+ example: Robin
+ last_name:
+ type: string
+ example: Ellis
+ "/api/v3/seller/auth/password_resets":
post:
- summary: Create a delivery method
+ summary: Request password reset
tags:
- - Delivery Methods
- security:
- - bearer_auth: []
+ - Authentication
description: |
- Adds a way for this seller to ship. The method is always the seller's
- own, whatever the payload says.
+ Requests a password reset email for a seller.
- Neither the rate provider nor the fulfillment provider is settable: a
- seller prices their own rates and enters tracking numbers by hand,
- because carrier accounts belong to the marketplace.
+ Unauthenticated. Always answers `202`, whether or not the address
+ belongs to a seller, so this cannot be used to discover which accounts
+ exist. A store staff member who runs no seller is treated as no match:
+ they have no seller panel to be sent to.
+
+ `redirect_url` is where the emailed link should point, with the reset
+ token appended as a `token` query param. It is honoured only when it
+ matches one of the store's allowed origins; otherwise it is silently
+ ignored and the server resolves the seller panel origin itself. The
+ email is delivered by Spree via the
+ `seller_user.password_reset_requested` event, which is never forwarded
+ to webhook endpoints.
+ parameters: []
+ responses:
+ '202':
+ description: reset requested
+ content:
+ application/json:
+ example:
+ message: If an account exists for that email, password reset instructions
+ have been sent.
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ redirect_url:
+ type: string
+ example: https://sellers.your-store.com/reset-password
+ description: Must match an allowed origin of the store; ignored
+ otherwise.
+ required:
+ - email
+ "/api/v3/seller/auth/password_resets/{id}":
+ patch:
+ summary: Reset password
+ tags:
+ - Authentication
+ description: |
+ Spends a password reset token (the `token` query param from the emailed
+ link), sets the new password and signs the seller in: the response
+ carries a seller JWT and the rotatable refresh token is set in an
+ HttpOnly cookie, so they land in the panel rather than on a login form.
+
+ The token is single-use, and resetting revokes every other session the
+ account holds. A token whose seller membership has since been revoked is
+ refused exactly as an expired one.
parameters:
- - name: X-Spree-Seller-Id
- in: header
+ - name: id
+ in: path
+ description: The reset token from the emailed link
required: true
schema:
type: string
responses:
- '201':
- description: delivery method created
+ '200':
+ description: password reset
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImJjMDM3NTNhLTEzN2MtNGM1Zi1hMzM2LWUzMjBlZTNiMjQ5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.EASrzbGpJVyAl10SJyzs8na68Wmvedkm7G66wTBq_0k
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Ariana
+ last_name: Wiza
+ full_name: Ariana Wiza
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 52
+ status: approved
schema:
- "$ref": "#/components/schemas/DeliveryMethod"
+ "$ref": "#/components/schemas/AuthResponse"
'422':
- description: invalid request
+ description: invalid or expired token
content:
application/json:
+ example:
+ error:
+ code: password_reset_token_invalid
+ message: Password reset token is invalid or has expired.
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -293,21 +440,12047 @@ paths:
schema:
type: object
properties:
- name:
- type: string
- admin_name:
- type: string
- nullable: true
- code:
- type: string
- nullable: true
- delivery_profile_id:
+ password:
type: string
- description: One of the marketplace's delivery profiles
- delivery_zone_id:
+ example: new-password-123
+ password_confirmation:
type: string
- nullable: true
- description: Narrows where the method ships
+ example: new-password-123
+ required:
+ - password
+ - password_confirmation
+ "/api/v3/seller/me":
+ get:
+ summary: Current user
+ tags:
+ - Account
+ security:
+ - bearer_auth: []
+ description: |
+ The signed-in user, the sellers they may act for, and what they may do on
+ the selected one.
+
+ This is the one authenticated endpoint that answers without
+ `X-Spree-Seller-Id` — it is what tells the panel which seller to name.
+ Sending the header narrows `permission_keys` and `permissions` to that
+ seller; without it both are empty, because capability is per seller and
+ there is no answer spanning all of them.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: false
+ description: The seller to report capability for. Omit to list sellers without
+ narrowing permissions.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: current user returned
+ content:
+ application/json:
+ example:
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Nadia
+ last_name: Effertz
+ full_name: Nadia Effertz
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 40
+ slug: seller-40
+ status: approved
+ permissions:
+ - allow: true
+ actions:
+ - read
+ subjects:
+ - Spree::Country
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ subjects:
+ - Spree::State
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ subjects:
+ - Spree::Store
+ has_conditions: true
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Product
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Variant
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::OptionType
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::OptionValue
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Price
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::PriceList
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::PriceRule
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Catalog
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::CatalogProduct
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::CatalogAssignment
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::CustomField
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::DigitalAsset
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Import
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::ImportRow
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Product
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Variant
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::OptionType
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::OptionValue
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Price
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::PriceList
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::PriceRule
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Catalog
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::CatalogProduct
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::CatalogAssignment
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::CustomField
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::DigitalAsset
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Import
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::ImportRow
+ has_conditions: false
+ permission_keys:
+ - read_products
+ - write_products
+ schema:
+ "$ref": "#/components/schemas/SellerMeResponse"
+ '401':
+ description: missing or invalid token
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/countries":
+ get:
+ summary: List countries
+ tags:
+ - Countries
+ security:
+ - bearer_auth: []
+ description: |
+ Countries and their states, for the panel's address forms.
+
+ Public reference data — the same list the storefront serves — so it is
+ not narrowed to the markets this marketplace sells into: a seller filling
+ in a billing address needs every country.
+
+ Unpaginated. An address dropdown needs all ~250 at once.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: countries listed
+ content:
+ application/json:
+ example:
+ data:
+ - iso: AF
+ iso3: AFG
+ name: Afghanistan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BDS
+ name: Badakhshan
+ - abbr: BDG
+ name: Badghis
+ - abbr: BGL
+ name: Baghlan
+ - abbr: BAL
+ name: Balkh
+ - abbr: BAM
+ name: Bamian
+ - abbr: DAY
+ name: Daykondi
+ - abbr: FRA
+ name: Farah
+ - abbr: FYB
+ name: Faryab
+ - abbr: GHA
+ name: Ghazni
+ - abbr: GHO
+ name: Ghowr
+ - abbr: HEL
+ name: Helmand
+ - abbr: HER
+ name: Herat
+ - abbr: JOW
+ name: Jowzjan
+ - abbr: KAB
+ name: Kabul [Kabol]
+ - abbr: KAN
+ name: Kandahar
+ - abbr: KAP
+ name: Kapisa
+ - abbr: KHO
+ name: Khowst
+ - abbr: KNR
+ name: Konar [Kunar]
+ - abbr: KDZ
+ name: Kondoz [Kunduz]
+ - abbr: LAG
+ name: Laghman
+ - abbr: NAN
+ name: Nangrahar [Nangarhar]
+ - abbr: NIM
+ name: Nimruz
+ - abbr: NUR
+ name: Nurestan
+ - abbr: PIA
+ name: Paktia
+ - abbr: PKA
+ name: Paktika
+ - abbr: PAN
+ name: Panjshir
+ - abbr: PAR
+ name: Parwan
+ - abbr: SAM
+ name: Samangan
+ - abbr: SAR
+ name: Sar-e Pol
+ - abbr: TAK
+ name: Takhar
+ - abbr: WAR
+ name: Wardak [Wardag]
+ - abbr: ZAB
+ name: Zabol [Zabul]
+ - abbr: URU
+ name: روزګان ولايت
+ - abbr: LOG
+ name: لوګر ولايت
+ - iso: AL
+ iso3: ALB
+ name: Albania
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Berat
+ - abbr: '09'
+ name: Dibër
+ - abbr: '02'
+ name: Durrës
+ - abbr: '03'
+ name: Elbasan
+ - abbr: '04'
+ name: Fier
+ - abbr: '05'
+ name: Gjirokastër
+ - abbr: '06'
+ name: Korçë
+ - abbr: '07'
+ name: Kukës
+ - abbr: '08'
+ name: Lezhë
+ - abbr: '10'
+ name: Shkodër
+ - abbr: '11'
+ name: Tiranë
+ - abbr: '12'
+ name: Vlorë
+ - iso: DZ
+ iso3: DZA
+ name: Algeria
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Adrar
+ - abbr: '16'
+ name: Alger
+ - abbr: '23'
+ name: Annaba
+ - abbr: '44'
+ name: Aïn Defla
+ - abbr: '46'
+ name: Aïn Témouchent
+ - abbr: '05'
+ name: Batna
+ - abbr: '07'
+ name: Biskra
+ - abbr: '09'
+ name: Blida
+ - abbr: '34'
+ name: Bordj Bou Arréridj
+ - abbr: '10'
+ name: Bouira
+ - abbr: '35'
+ name: Boumerdès
+ - abbr: '08'
+ name: Béchar
+ - abbr: '06'
+ name: Béjaïa
+ - abbr: '02'
+ name: Chlef
+ - abbr: '25'
+ name: Constantine
+ - abbr: '17'
+ name: Djelfa
+ - abbr: '32'
+ name: El Bayadh
+ - abbr: '39'
+ name: El Oued
+ - abbr: '36'
+ name: El Tarf
+ - abbr: '47'
+ name: Ghardaïa
+ - abbr: '24'
+ name: Guelma
+ - abbr: '33'
+ name: Illizi
+ - abbr: '18'
+ name: Jijel
+ - abbr: '40'
+ name: Khenchela
+ - abbr: '03'
+ name: Laghouat
+ - abbr: '29'
+ name: Mascara
+ - abbr: '43'
+ name: Mila
+ - abbr: '27'
+ name: Mostaganem
+ - abbr: '28'
+ name: Msila
+ - abbr: '26'
+ name: Médéa
+ - abbr: '45'
+ name: Naama
+ - abbr: '31'
+ name: Oran
+ - abbr: '30'
+ name: Ouargla
+ - abbr: '04'
+ name: Oum el Bouaghi
+ - abbr: '48'
+ name: Relizane
+ - abbr: '20'
+ name: Saïda
+ - abbr: '22'
+ name: Sidi Bel Abbès
+ - abbr: '21'
+ name: Skikda
+ - abbr: '41'
+ name: Souk Ahras
+ - abbr: '19'
+ name: Sétif
+ - abbr: '11'
+ name: Tamanghasset
+ - abbr: '14'
+ name: Tiaret
+ - abbr: '37'
+ name: Tindouf
+ - abbr: '42'
+ name: Tipaza
+ - abbr: '38'
+ name: Tissemsilt
+ - abbr: '15'
+ name: Tizi Ouzou
+ - abbr: '13'
+ name: Tlemcen
+ - abbr: '12'
+ name: Tébessa
+ - iso: AS
+ iso3: ASM
+ name: American Samoa
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: AD
+ iso3: AND
+ name: Andorra
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '07'
+ name: Andorra la Vella
+ - abbr: '02'
+ name: Canillo
+ - abbr: '03'
+ name: Encamp
+ - abbr: '08'
+ name: Escaldes-Engordany
+ - abbr: '04'
+ name: La Massana
+ - abbr: '05'
+ name: Ordino
+ - abbr: '06'
+ name: Sant Julià de Lòria
+ - iso: AO
+ iso3: AGO
+ name: Angola
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BGO
+ name: Bengo
+ - abbr: BGU
+ name: Benguela
+ - abbr: BIE
+ name: Bié
+ - abbr: CAB
+ name: Cabinda
+ - abbr: CCU
+ name: Cuando-Cubango
+ - abbr: CNO
+ name: Cuanza Norte
+ - abbr: CUS
+ name: Cuanza Sul
+ - abbr: CNN
+ name: Cunene
+ - abbr: HUA
+ name: Huambo
+ - abbr: HUI
+ name: Huíla
+ - abbr: LUA
+ name: Luanda
+ - abbr: LNO
+ name: Lunda Norte
+ - abbr: LSU
+ name: Lunda Sul
+ - abbr: MAL
+ name: Malange
+ - abbr: MOX
+ name: Moxico
+ - abbr: NAM
+ name: Namibe
+ - abbr: UIG
+ name: Uíge
+ - abbr: ZAI
+ name: Zaire
+ - iso: AI
+ iso3: AIA
+ name: Anguilla
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: AG
+ iso3: ATG
+ name: Antigua and Barbuda
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '10'
+ name: Barbuda
+ - abbr: '11'
+ name: Redonda
+ - abbr: '03'
+ name: Saint George
+ - abbr: '04'
+ name: Saint John’s
+ - abbr: '05'
+ name: Saint Mary
+ - abbr: '06'
+ name: Saint Paul
+ - abbr: '07'
+ name: Saint Peter
+ - abbr: '08'
+ name: Saint Philip
+ - iso: AR
+ iso3: ARG
+ name: Argentina
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: B
+ name: Buenos Aires
+ - abbr: C
+ name: Capital federal
+ - abbr: K
+ name: Catamarca
+ - abbr: H
+ name: Chaco
+ - abbr: U
+ name: Chubut
+ - abbr: W
+ name: Corrientes
+ - abbr: X
+ name: Córdoba
+ - abbr: E
+ name: Entre Ríos
+ - abbr: P
+ name: Formosa
+ - abbr: "Y"
+ name: Jujuy
+ - abbr: L
+ name: La Pampa
+ - abbr: F
+ name: La Rioja
+ - abbr: M
+ name: Mendoza
+ - abbr: "N"
+ name: Misiones
+ - abbr: Q
+ name: Neuquén
+ - abbr: R
+ name: Río Negro
+ - abbr: A
+ name: Salta
+ - abbr: J
+ name: San Juan
+ - abbr: D
+ name: San Luis
+ - abbr: Z
+ name: Santa Cruz
+ - abbr: S
+ name: Santa Fe
+ - abbr: G
+ name: Santiago del Estero
+ - abbr: V
+ name: Tierra del Fuego
+ - abbr: T
+ name: Tucumán
+ - iso: AM
+ iso3: ARM
+ name: Armenia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AG
+ name: Aragacotn
+ - abbr: AR
+ name: Ararat
+ - abbr: AV
+ name: Armavir
+ - abbr: ER
+ name: Erevan
+ - abbr: GR
+ name: Gegark'unik'
+ - abbr: KT
+ name: Kotayk'
+ - abbr: LO
+ name: Lory
+ - abbr: SU
+ name: Syunik'
+ - abbr: TV
+ name: Tavuš
+ - abbr: VD
+ name: Vayoc Jor
+ - abbr: SH
+ name: Širak
+ - iso: AW
+ iso3: ABW
+ name: Aruba
+ states_required: false
+ zipcode_required: false
+ states: []
+ - iso: AU
+ iso3: AUS
+ name: Australia
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: ACT
+ name: Australian Capital Territory
+ - abbr: NSW
+ name: New South Wales
+ - abbr: NT
+ name: Northern Territory
+ - abbr: QLD
+ name: Queensland
+ - abbr: SA
+ name: South Australia
+ - abbr: TAS
+ name: Tasmania
+ - abbr: VIC
+ name: Victoria
+ - abbr: WA
+ name: Western Australia
+ - iso: AT
+ iso3: AUT
+ name: Austria
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '1'
+ name: Burgenland
+ - abbr: '2'
+ name: Kärnten
+ - abbr: '3'
+ name: Niederösterreich
+ - abbr: '4'
+ name: Oberösterreich
+ - abbr: '5'
+ name: Salzburg
+ - abbr: '6'
+ name: Steiermark
+ - abbr: '7'
+ name: Tirol
+ - abbr: '8'
+ name: Vorarlberg
+ - abbr: '9'
+ name: Wien
+ - iso: AZ
+ iso3: AZE
+ name: Azerbaijan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: ABS
+ name: Abseron
+ - abbr: AGC
+ name: Agcabädi
+ - abbr: AGM
+ name: Agdam
+ - abbr: AGS
+ name: Agdas
+ - abbr: AGA
+ name: Agstafa
+ - abbr: AGU
+ name: Agsu
+ - abbr: AST
+ name: Astara
+ - abbr: BAB
+ name: Babäk
+ - abbr: BA
+ name: Baki
+ - abbr: BAL
+ name: Balakän
+ - abbr: BEY
+ name: Beyläqan
+ - abbr: BIL
+ name: Biläsuvar
+ - abbr: BAR
+ name: Bärdä
+ - abbr: CUL
+ name: Culfa
+ - abbr: CAB
+ name: Cäbrayil
+ - abbr: CAL
+ name: Cälilabab
+ - abbr: DAS
+ name: Daskäsän
+ - abbr: FUZ
+ name: Füzuli
+ - abbr: GOR
+ name: Goranboy
+ - abbr: GAD
+ name: Gädäbäy
+ - abbr: GA
+ name: Gäncä
+ - abbr: GYG
+ name: Göygöl
+ - abbr: GOY
+ name: Göyçay
+ - abbr: HAC
+ name: Haciqabul
+ - abbr: IMI
+ name: Imisli
+ - abbr: ISM
+ name: Ismayilli
+ - abbr: KAL
+ name: Kälbäcär
+ - abbr: KUR
+ name: Kürdämir
+ - abbr: KAN
+ name: Kəngərli
+ - abbr: LAC
+ name: Laçin
+ - abbr: LER
+ name: Lerik
+ - abbr: LAN
+ name: Länkäran
+ - abbr: LA
+ name: Länkäran City
+ - abbr: MAS
+ name: Masalli
+ - abbr: MI
+ name: Mingäçevir
+ - abbr: NA
+ name: Naftalan
+ - abbr: NX
+ name: Naxçivan
+ - abbr: NV
+ name: Naxçıvan
+ - abbr: NEF
+ name: Neftçala
+ - abbr: OGU
+ name: Oguz
+ - abbr: ORD
+ name: Ordubad
+ - abbr: QAX
+ name: Qax
+ - abbr: QAZ
+ name: Qazax
+ - abbr: QOB
+ name: Qobustan
+ - abbr: QBA
+ name: Quba
+ - abbr: QBI
+ name: Qubadli
+ - abbr: QUS
+ name: Qusar
+ - abbr: QAB
+ name: Qäbälä
+ - abbr: SAT
+ name: Saatli
+ - abbr: SAB
+ name: Sabirabad
+ - abbr: SAH
+ name: Sahbuz
+ - abbr: SAL
+ name: Salyan
+ - abbr: SMI
+ name: Samaxi
+ - abbr: SMX
+ name: Samux
+ - abbr: SIY
+ name: Siyäzän
+ - abbr: SM
+ name: Sumqayit
+ - abbr: SUS
+ name: Susa
+ - abbr: SAD
+ name: Sädäräk
+ - abbr: SAK
+ name: Säki
+ - abbr: SA
+ name: Säki City
+ - abbr: SKR
+ name: Sämkir
+ - abbr: SAR
+ name: Särur
+ - abbr: TOV
+ name: Tovuz
+ - abbr: TAR
+ name: Tärtär
+ - abbr: UCA
+ name: Ucar
+ - abbr: XA
+ name: Xankändi
+ - abbr: XAC
+ name: Xaçmaz
+ - abbr: XIZ
+ name: Xizi
+ - abbr: XCI
+ name: Xocali
+ - abbr: XVD
+ name: Xocavänd
+ - abbr: YAR
+ name: Yardimli
+ - abbr: YEV
+ name: Yevlax
+ - abbr: YE
+ name: Yevlax City
+ - abbr: ZAQ
+ name: Zaqatala
+ - abbr: ZAN
+ name: Zängilan
+ - abbr: ZAR
+ name: Zärdab
+ - abbr: SBN
+ name: Şabran (rayon)
+ - abbr: SR
+ name: Şirvan
+ - iso: BS
+ iso3: BHS
+ name: Bahamas
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AK
+ name: Acklins
+ - abbr: BY
+ name: Berry Islands
+ - abbr: BI
+ name: Bimini
+ - abbr: BP
+ name: Black Point
+ - abbr: CI
+ name: Cat Island
+ - abbr: CO
+ name: Central Abaco
+ - abbr: CS
+ name: Central Andros
+ - abbr: CE
+ name: Central Eleuthera
+ - abbr: CK
+ name: Crooked Island
+ - abbr: EG
+ name: East Grand Bahama
+ - abbr: EX
+ name: Exuma
+ - abbr: FP
+ name: Freeport
+ - abbr: GC
+ name: Grand Cay
+ - abbr: HI
+ name: Harbour Island
+ - abbr: HT
+ name: Hope Town
+ - abbr: IN
+ name: Inagua
+ - abbr: LI
+ name: Long Island
+ - abbr: MC
+ name: Mangrove Cay
+ - abbr: MG
+ name: Mayaguana
+ - abbr: MI
+ name: Moore’s Island
+ - abbr: NP
+ name: New Providence
+ - abbr: 'NO'
+ name: North Abaco
+ - abbr: NS
+ name: North Andros
+ - abbr: NE
+ name: North Eleuthera
+ - abbr: RI
+ name: Ragged Island
+ - abbr: RC
+ name: Rum Cay
+ - abbr: SS
+ name: San Salvador
+ - abbr: SO
+ name: South Abaco
+ - abbr: SA
+ name: South Andros
+ - abbr: SE
+ name: South Eleuthera
+ - abbr: SW
+ name: Spanish Wells
+ - abbr: WG
+ name: West Grand Bahama
+ - iso: BH
+ iso3: BHR
+ name: Bahrain
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '14'
+ name: Al Janubiyah
+ - abbr: '13'
+ name: Al Manamah (Al ‘Asimah)
+ - abbr: '15'
+ name: Al Muharraq
+ - abbr: '17'
+ name: Ash Shamaliyah
+ - iso: BD
+ iso3: BGD
+ name: Bangladesh
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '05'
+ name: Bagerhat zila
+ - abbr: '01'
+ name: Bandarban zila
+ - abbr: '02'
+ name: Barguna zila
+ - abbr: '06'
+ name: Barisal zila
+ - abbr: '07'
+ name: Bhola zila
+ - abbr: '03'
+ name: Bogra zila
+ - abbr: '04'
+ name: Brahmanbaria zila
+ - abbr: '09'
+ name: Chandpur zila
+ - abbr: '10'
+ name: Chittagong zila
+ - abbr: '12'
+ name: Chuadanga zila
+ - abbr: '08'
+ name: Comilla zila
+ - abbr: '11'
+ name: Cox's Bazar zila
+ - abbr: '13'
+ name: Dhaka zila
+ - abbr: '14'
+ name: Dinajpur zila
+ - abbr: '15'
+ name: Faridpur zila
+ - abbr: '16'
+ name: Feni zila
+ - abbr: '19'
+ name: Gaibandha zila
+ - abbr: '18'
+ name: Gazipur zila
+ - abbr: '17'
+ name: Gopalganj zila
+ - abbr: '20'
+ name: Habiganj zila
+ - abbr: '24'
+ name: Jaipurhat zila
+ - abbr: '21'
+ name: Jamalpur zila
+ - abbr: '22'
+ name: Jessore zila
+ - abbr: '25'
+ name: Jhalakati zila
+ - abbr: '23'
+ name: Jhenaidah zila
+ - abbr: '29'
+ name: Khagrachari zila
+ - abbr: '27'
+ name: Khulna zila
+ - abbr: '26'
+ name: Kishoreganj zila
+ - abbr: '28'
+ name: Kurigram zila
+ - abbr: '30'
+ name: Kushtia zila
+ - abbr: '31'
+ name: Lakshmipur zila
+ - abbr: '32'
+ name: Lalmonirhat zila
+ - abbr: '36'
+ name: Madaripur zila
+ - abbr: '37'
+ name: Magura zila
+ - abbr: '33'
+ name: Manikganj zila
+ - abbr: '39'
+ name: Meherpur zila
+ - abbr: '38'
+ name: Moulvibazar zila
+ - abbr: '35'
+ name: Munshiganj zila
+ - abbr: '34'
+ name: Mymensingh zila
+ - abbr: '48'
+ name: Naogaon zila
+ - abbr: '43'
+ name: Narail zila
+ - abbr: '40'
+ name: Narayanganj zila
+ - abbr: '42'
+ name: Narsingdi zila
+ - abbr: '44'
+ name: Natore zila
+ - abbr: '45'
+ name: Nawabganj zila
+ - abbr: '41'
+ name: Netrakona zila
+ - abbr: '46'
+ name: Nilphamari zila
+ - abbr: '47'
+ name: Noakhali zila
+ - abbr: '49'
+ name: Pabna zila
+ - abbr: '52'
+ name: Panchagarh zila
+ - abbr: '51'
+ name: Patuakhali zila
+ - abbr: '50'
+ name: Pirojpur zila
+ - abbr: '53'
+ name: Rajbari zila
+ - abbr: '54'
+ name: Rajshahi zila
+ - abbr: '56'
+ name: Rangamati zila
+ - abbr: '55'
+ name: Rangpur zila
+ - abbr: '58'
+ name: Satkhira zila
+ - abbr: '62'
+ name: Shariatpur zila
+ - abbr: '57'
+ name: Sherpur zila
+ - abbr: '59'
+ name: Sirajganj zila
+ - abbr: '61'
+ name: Sunamganj zila
+ - abbr: '60'
+ name: Sylhet zila
+ - abbr: '63'
+ name: Tangail zila
+ - abbr: '64'
+ name: Thakurgaon zila
+ - abbr: D
+ name: খুলনা বিভাগ
+ - abbr: B
+ name: চট্টগ্রাম বিভাগ
+ - abbr: C
+ name: ঢাকা বিভাগ
+ - abbr: A
+ name: বরিশাল বিভাগ
+ - abbr: H
+ name: ময়মনসিংহ বিভাগ
+ - abbr: F
+ name: রংপুর বিভাগ
+ - abbr: E
+ name: রাজশাহী বিভাগ
+ - abbr: G
+ name: সিলেট বিভাগ
+ - iso: BB
+ iso3: BRB
+ name: Barbados
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Christ Church
+ - abbr: '02'
+ name: Saint Andrew
+ - abbr: '03'
+ name: Saint George
+ - abbr: '04'
+ name: Saint James
+ - abbr: '05'
+ name: Saint John
+ - abbr: '06'
+ name: Saint Joseph
+ - abbr: '07'
+ name: Saint Lucy
+ - abbr: '08'
+ name: Saint Michael
+ - abbr: '09'
+ name: Saint Peter
+ - abbr: '10'
+ name: Saint Philip
+ - abbr: '11'
+ name: Saint Thomas
+ - iso: BY
+ iso3: BLR
+ name: Belarus
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BR
+ name: Brestskaya voblasts' (be) Brestskaya oblast' (ru)
+ - abbr: HO
+ name: Homyel'skaya voblasts' (be) Gomel'skaya oblast' (ru)
+ - abbr: HR
+ name: Hrodzenskaya voblasts' (be) Grodnenskaya oblast' (ru)
+ - abbr: MA
+ name: Mahilyowskaya voblasts' (be) Mogilevskaya oblast' (ru)
+ - abbr: MI
+ name: Minskaya voblasts' (be) Minskaya oblast' (ru)
+ - abbr: VI
+ name: Vitsyebskaya voblasts' (be) Vitebskaya oblast' (ru)
+ - abbr: HM
+ name: Мінск
+ - iso: BE
+ iso3: BEL
+ name: Belgium
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: VAN
+ name: Antwerpen (nl)
+ - abbr: WBR
+ name: Brabant Wallon (fr)
+ - abbr: BRU
+ name: Brussels
+ - abbr: WHT
+ name: Hainaut (fr)
+ - abbr: VLI
+ name: Limburg (nl)
+ - abbr: WLG
+ name: Liège (fr)
+ - abbr: WLX
+ name: Luxembourg (fr)
+ - abbr: WNA
+ name: Namur (fr)
+ - abbr: VOV
+ name: Oost-Vlaanderen (nl)
+ - abbr: VBR
+ name: Vlaams Brabant (nl)
+ - abbr: VLG
+ name: Vlaams Gewest
+ - abbr: WAL
+ name: Wallonië
+ - abbr: VWV
+ name: West-Vlaanderen (nl)
+ - iso: BZ
+ iso3: BLZ
+ name: Belize
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BZ
+ name: Belize
+ - abbr: CY
+ name: Cayo
+ - abbr: CZL
+ name: Corozal
+ - abbr: OW
+ name: Orange Walk
+ - abbr: SC
+ name: Stann Creek
+ - abbr: TOL
+ name: Toledo
+ - iso: BJ
+ iso3: BEN
+ name: Benin
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AL
+ name: Alibori
+ - abbr: AK
+ name: Atakora
+ - abbr: AQ
+ name: Atlantique
+ - abbr: BO
+ name: Borgou
+ - abbr: CO
+ name: Collines
+ - abbr: DO
+ name: Donga
+ - abbr: KO
+ name: Kouffo
+ - abbr: LI
+ name: Littoral
+ - abbr: MO
+ name: Mono
+ - abbr: OU
+ name: Ouémé
+ - abbr: PL
+ name: Plateau
+ - abbr: ZO
+ name: Zou
+ - iso: BM
+ iso3: BMU
+ name: Bermuda
+ states_required: false
+ zipcode_required: false
+ states: []
+ - iso: BT
+ iso3: BTN
+ name: Bhutan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '33'
+ name: Bumthang
+ - abbr: '12'
+ name: Chhukha
+ - abbr: '22'
+ name: Dagana
+ - abbr: GA
+ name: Gasa
+ - abbr: '13'
+ name: Ha
+ - abbr: '44'
+ name: Lhuentse
+ - abbr: '42'
+ name: Monggar
+ - abbr: '11'
+ name: Paro
+ - abbr: '43'
+ name: Pemagatshel
+ - abbr: '23'
+ name: Punakha
+ - abbr: '45'
+ name: Samdrup Jongkha
+ - abbr: '14'
+ name: Samtse
+ - abbr: '31'
+ name: Sarpang
+ - abbr: '15'
+ name: Thimphu
+ - abbr: TY
+ name: Trashi Yangtse
+ - abbr: '41'
+ name: Trashigang
+ - abbr: '32'
+ name: Trongsa
+ - abbr: '21'
+ name: Tsirang
+ - abbr: '24'
+ name: Wangdue Phodrang
+ - abbr: '34'
+ name: Zhemgang
+ - iso: BO
+ iso3: BOL
+ name: Bolivia
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: H
+ name: Chuquisaca
+ - abbr: C
+ name: Cochabamba
+ - abbr: B
+ name: El Beni
+ - abbr: L
+ name: La Paz
+ - abbr: O
+ name: Oruro
+ - abbr: "N"
+ name: Pando
+ - abbr: P
+ name: Potosí
+ - abbr: S
+ name: Santa Cruz
+ - abbr: T
+ name: Tarija
+ - iso: BQ
+ iso3: BES
+ name: Bonaire, Sint Eustatius and Saba
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BO
+ name: Bonaire
+ - abbr: SA
+ name: Saba
+ - abbr: SE
+ name: Sint Eustatius
+ - iso: BA
+ iso3: BIH
+ name: Bosnia and Herzegovina
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BRC
+ name: Brčko Distrikt
+ - abbr: BIH
+ name: Federacija Bosna i Hercegovina
+ - abbr: SRP
+ name: Republika Srpska
+ - iso: BW
+ iso3: BWA
+ name: Botswana
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: CE
+ name: Central
+ - abbr: CH
+ name: Chobe
+ - abbr: FR
+ name: Francistown
+ - abbr: GA
+ name: Gaborone
+ - abbr: GH
+ name: Ghanzi
+ - abbr: JW
+ name: Jwaneng
+ - abbr: KG
+ name: Kgalagadi
+ - abbr: KL
+ name: Kgatleng
+ - abbr: KW
+ name: Kweneng
+ - abbr: LO
+ name: Lobatse
+ - abbr: NE
+ name: North-East
+ - abbr: NW
+ name: North-West
+ - abbr: SP
+ name: Selibe Phikwe
+ - abbr: SE
+ name: South-East
+ - abbr: SO
+ name: Southern
+ - abbr: ST
+ name: Sowa Town
+ - iso: BR
+ iso3: BRA
+ name: Brazil
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AC
+ name: Acre
+ - abbr: AL
+ name: Alagoas
+ - abbr: AP
+ name: Amapá
+ - abbr: AM
+ name: Amazonas
+ - abbr: BA
+ name: Bahia
+ - abbr: CE
+ name: Ceará
+ - abbr: DF
+ name: Distrito Federal
+ - abbr: ES
+ name: Espírito Santo
+ - abbr: GO
+ name: Goiás
+ - abbr: MA
+ name: Maranhão
+ - abbr: MT
+ name: Mato Grosso
+ - abbr: MS
+ name: Mato Grosso do Sul
+ - abbr: MG
+ name: Minas Gerais
+ - abbr: PR
+ name: Paraná
+ - abbr: PB
+ name: Paraíba
+ - abbr: PA
+ name: Pará
+ - abbr: PE
+ name: Pernambuco
+ - abbr: PI
+ name: Piauí
+ - abbr: RN
+ name: Rio Grande do Norte
+ - abbr: RS
+ name: Rio Grande do Sul
+ - abbr: RJ
+ name: Rio de Janeiro
+ - abbr: RO
+ name: Rondônia
+ - abbr: RR
+ name: Roraima
+ - abbr: SC
+ name: Santa Catarina
+ - abbr: SE
+ name: Sergipe
+ - abbr: SP
+ name: São Paulo
+ - abbr: TO
+ name: Tocantins
+ - iso: BN
+ iso3: BRN
+ name: Brunei Darussalam
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BE
+ name: Belait
+ - abbr: BM
+ name: Brunei-Muara
+ - abbr: TE
+ name: Temburong
+ - abbr: TU
+ name: Tutong
+ - iso: BG
+ iso3: BGR
+ name: Bulgaria
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Blagoevgrad
+ - abbr: '02'
+ name: Burgas
+ - abbr: '08'
+ name: Dobrich
+ - abbr: '07'
+ name: Gabrovo
+ - abbr: '26'
+ name: Haskovo
+ - abbr: '09'
+ name: Kardzhali
+ - abbr: '10'
+ name: Kjustendil
+ - abbr: '11'
+ name: Lovech
+ - abbr: '12'
+ name: Montana
+ - abbr: '13'
+ name: Pazardzhik
+ - abbr: '14'
+ name: Pernik
+ - abbr: '15'
+ name: Pleven
+ - abbr: '16'
+ name: Plovdiv
+ - abbr: '17'
+ name: Razgrad
+ - abbr: '18'
+ name: Ruse
+ - abbr: '19'
+ name: Silistra
+ - abbr: '20'
+ name: Sliven
+ - abbr: '21'
+ name: Smolyan
+ - abbr: '23'
+ name: Sofia
+ - abbr: '22'
+ name: Sofia-Grad
+ - abbr: '24'
+ name: Stara Zagora
+ - abbr: '25'
+ name: Targovishte
+ - abbr: '03'
+ name: Varna
+ - abbr: '04'
+ name: Veliko Tarnovo
+ - abbr: '05'
+ name: Vidin
+ - abbr: '06'
+ name: Vratsa
+ - abbr: '28'
+ name: Yambol
+ - abbr: '27'
+ name: Šumen
+ - iso: BF
+ iso3: BFA
+ name: Burkina Faso
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BAL
+ name: Balé
+ - abbr: BAM
+ name: Bam
+ - abbr: BAN
+ name: Banwa
+ - abbr: BAZ
+ name: Bazèga
+ - abbr: '01'
+ name: Boucle du Mouhoun
+ - abbr: BGR
+ name: Bougouriba
+ - abbr: BLG
+ name: Boulgou
+ - abbr: BLK
+ name: Boulkiemdé
+ - abbr: '02'
+ name: Cascades
+ - abbr: '03'
+ name: Centre
+ - abbr: '04'
+ name: Centre-Est
+ - abbr: '05'
+ name: Centre-Nord
+ - abbr: '06'
+ name: Centre-Ouest
+ - abbr: '07'
+ name: Centre-Sud
+ - abbr: COM
+ name: Comoé
+ - abbr: '08'
+ name: Est
+ - abbr: GAN
+ name: Ganzourgou
+ - abbr: GNA
+ name: Gnagna
+ - abbr: GOU
+ name: Gourma
+ - abbr: '09'
+ name: Hauts-Bassins
+ - abbr: HOU
+ name: Houet
+ - abbr: IOB
+ name: Ioba
+ - abbr: KAD
+ name: Kadiogo
+ - abbr: KMD
+ name: Komondjari
+ - abbr: KMP
+ name: Kompienga
+ - abbr: KOS
+ name: Kossi
+ - abbr: KOP
+ name: Koulpélogo
+ - abbr: KOT
+ name: Kouritenga
+ - abbr: KOW
+ name: Kourwéogo
+ - abbr: KEN
+ name: Kénédougou
+ - abbr: LOR
+ name: Loroum
+ - abbr: LER
+ name: Léraba
+ - abbr: MOU
+ name: Mouhoun
+ - abbr: NAO
+ name: Nahouri
+ - abbr: NAM
+ name: Namentenga
+ - abbr: NAY
+ name: Nayala
+ - abbr: '10'
+ name: Nord
+ - abbr: NOU
+ name: Noumbiel
+ - abbr: OUB
+ name: Oubritenga
+ - abbr: OUD
+ name: Oudalan
+ - abbr: PAS
+ name: Passoré
+ - abbr: '11'
+ name: Plateau-Central
+ - abbr: PON
+ name: Poni
+ - abbr: '12'
+ name: Sahel
+ - abbr: SNG
+ name: Sanguié
+ - abbr: SMT
+ name: Sanmatenga
+ - abbr: SIS
+ name: Sissili
+ - abbr: SOM
+ name: Soum
+ - abbr: SOR
+ name: Sourou
+ - abbr: '13'
+ name: Sud-Ouest
+ - abbr: SEN
+ name: Séno
+ - abbr: TAP
+ name: Tapoa
+ - abbr: TUI
+ name: Tui
+ - abbr: YAG
+ name: Yagha
+ - abbr: YAT
+ name: Yatenga
+ - abbr: ZIR
+ name: Ziro
+ - abbr: ZON
+ name: Zondoma
+ - abbr: ZOU
+ name: Zoundwéogo
+ - iso: BI
+ iso3: BDI
+ name: Burundi
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BB
+ name: Bubanza
+ - abbr: BJ
+ name: Bujumbura
+ - abbr: BR
+ name: Bururi
+ - abbr: CA
+ name: Cankuzo
+ - abbr: CI
+ name: Cibitoke
+ - abbr: GI
+ name: Gitega
+ - abbr: KR
+ name: Karuzi
+ - abbr: KY
+ name: Kayanza
+ - abbr: KI
+ name: Kirundo
+ - abbr: MA
+ name: Makamba
+ - abbr: MU
+ name: Muramvya
+ - abbr: MY
+ name: Muyinga
+ - abbr: MW
+ name: Mwaro
+ - abbr: NG
+ name: Ngozi
+ - abbr: RM
+ name: Province de Rumonge
+ - abbr: RT
+ name: Rutana
+ - abbr: RY
+ name: Ruyigi
+ - abbr: BM
+ name: province de Bujumbura Mairie
+ - abbr: BL
+ name: province de Bujumbura rural
+ - iso: CV
+ iso3: CPV
+ name: Cabo Verde
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BV
+ name: Boa Vista
+ - abbr: BR
+ name: Brava
+ - abbr: CS
+ name: Calheta de São Miguel
+ - abbr: B
+ name: Ilhas de Barlavento
+ - abbr: S
+ name: Ilhas de Sotavento
+ - abbr: MA
+ name: Maio
+ - abbr: MO
+ name: Mosteiros
+ - abbr: PA
+ name: Paúl
+ - abbr: PN
+ name: Porto Novo
+ - abbr: PR
+ name: Praia
+ - abbr: RB
+ name: Ribeira Brava
+ - abbr: RG
+ name: Ribeira Grande
+ - abbr: RS
+ name: Ribeira Grande de Santiago
+ - abbr: SL
+ name: Sal
+ - abbr: CA
+ name: Santa Catarina
+ - abbr: CF
+ name: Santa Catarina do Fogo
+ - abbr: CR
+ name: Santa Cruz
+ - abbr: SD
+ name: São Domingos
+ - abbr: SF
+ name: São Filipe
+ - abbr: SO
+ name: São Lourenço dos Órgãos
+ - abbr: SM
+ name: São Miguel
+ - abbr: SN
+ name: São Nicolau
+ - abbr: SS
+ name: São Salvador do Mundo
+ - abbr: SV
+ name: São Vicente
+ - abbr: TA
+ name: Tarrafal
+ - abbr: TS
+ name: Tarrafal de São Nicolau
+ - iso: KH
+ iso3: KHM
+ name: Cambodia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '2'
+ name: Baat Dambang [Batdâmbâng]
+ - abbr: '1'
+ name: Banteay Mean Chey [Bântéay Méanchey]
+ - abbr: '3'
+ name: Kampong Chaam [Kâmpóng Cham]
+ - abbr: '4'
+ name: Kampong Chhnang [Kâmpóng Chhnang]
+ - abbr: '5'
+ name: Kampong Spueu [Kâmpóng Spœ]
+ - abbr: '6'
+ name: Kampong Thum [Kâmpóng Thum]
+ - abbr: '7'
+ name: Kampot [Kâmpôt]
+ - abbr: '8'
+ name: Kandaal [Kândal]
+ - abbr: '9'
+ name: Kaoh Kong [Kaôh Kong]
+ - abbr: '10'
+ name: Kracheh [Krâchéh]
+ - abbr: '23'
+ name: Krong Kep [Krong Kêb]
+ - abbr: '24'
+ name: Krong Pailin [Krong Pailin]
+ - abbr: '18'
+ name: Krong Preah Sihanouk [Krong Preah Sihanouk]
+ - abbr: '11'
+ name: Mondol Kiri [Môndól Kiri]
+ - abbr: '22'
+ name: 'Otdar Mean Chey [Otdâr Méanchey] '
+ - abbr: '12'
+ name: Phnom Penh [Phnum Pénh]
+ - abbr: '15'
+ name: Pousaat [Pouthisat]
+ - abbr: '13'
+ name: Preah Vihear [Preah Vihéar]
+ - abbr: '14'
+ name: Prey Veaeng [Prey Vêng]
+ - abbr: '16'
+ name: Rotanak Kiri [Rôtânôkiri]
+ - abbr: '17'
+ name: Siem Reab [Siemréab]
+ - abbr: '19'
+ name: Stueng Traeng
+ - abbr: '20'
+ name: Svaay Rieng [Svay Rieng]
+ - abbr: '21'
+ name: Taakaev [Takêv]
+ - abbr: '25'
+ name: Tbong Khmum
+ - iso: CM
+ iso3: CMR
+ name: Cameroon
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AD
+ name: Adamaoua
+ - abbr: CE
+ name: Centre
+ - abbr: ES
+ name: East
+ - abbr: EN
+ name: Far North
+ - abbr: LT
+ name: Littoral
+ - abbr: 'NO'
+ name: North
+ - abbr: NW
+ name: North-West
+ - abbr: SU
+ name: South
+ - abbr: SW
+ name: South-West
+ - abbr: OU
+ name: West
+ - iso: CA
+ iso3: CAN
+ name: Canada
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AB
+ name: Alberta
+ - abbr: BC
+ name: British Columbia
+ - abbr: MB
+ name: Manitoba
+ - abbr: NB
+ name: New Brunswick
+ - abbr: NL
+ name: Newfoundland and Labrador
+ - abbr: NT
+ name: Northwest Territories
+ - abbr: NS
+ name: Nova Scotia
+ - abbr: NU
+ name: Nunavut
+ - abbr: 'ON'
+ name: Ontario
+ - abbr: PE
+ name: Prince Edward Island
+ - abbr: QC
+ name: Quebec
+ - abbr: SK
+ name: Saskatchewan
+ - abbr: YT
+ name: Yukon
+ - iso: KY
+ iso3: CYM
+ name: Cayman Islands
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: CF
+ iso3: CAF
+ name: Central African Republic
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BB
+ name: Bamingui-Bangoran
+ - abbr: BGF
+ name: Bangui
+ - abbr: BK
+ name: Basse-Kotto
+ - abbr: HM
+ name: Haut-Mbomou
+ - abbr: HK
+ name: Haute-Kotto
+ - abbr: KG
+ name: Kémo
+ - abbr: LB
+ name: Lobaye
+ - abbr: HS
+ name: Mambéré-Kadéï
+ - abbr: MB
+ name: Mbomou
+ - abbr: KB
+ name: Nana-Grébizi
+ - abbr: NM
+ name: Nana-Mambéré
+ - abbr: MP
+ name: Ombella-Mpoko
+ - abbr: UK
+ name: Ouaka
+ - abbr: AC
+ name: Ouham
+ - abbr: OP
+ name: Ouham-Pendé
+ - abbr: SE
+ name: Sangha-Mbaéré
+ - abbr: VK
+ name: Vakaga
+ - iso: TD
+ iso3: TCD
+ name: Chad
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BA
+ name: Batha
+ - abbr: CB
+ name: Chari-Baguirmi
+ - abbr: GR
+ name: Guéra
+ - abbr: HL
+ name: Hadjer Lamis
+ - abbr: KA
+ name: Kanem
+ - abbr: LC
+ name: Lac
+ - abbr: LO
+ name: Logone-Occidental
+ - abbr: LR
+ name: Logone-Oriental
+ - abbr: MA
+ name: Mandoul
+ - abbr: ME
+ name: Mayo-Kébbi-Est
+ - abbr: MO
+ name: Mayo-Kébbi-Ouest
+ - abbr: MC
+ name: Moyen-Chari
+ - abbr: ND
+ name: Ndjamena
+ - abbr: OD
+ name: Ouaddaï
+ - abbr: SA
+ name: Salamat
+ - abbr: TA
+ name: Tandjilé
+ - abbr: WF
+ name: Wadi Fira
+ - abbr: EE
+ name: إنيدي الشرقية
+ - abbr: EO
+ name: إنيدي الغربية
+ - abbr: BG
+ name: بحر الغزال
+ - abbr: BO
+ name: منطقة بوركو
+ - abbr: TI
+ name: منطقة تبستي
+ - abbr: SI
+ name: منطقة سيلا
+ - iso: CL
+ iso3: CHL
+ name: Chile
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AI
+ name: Aisén del General Carlos Ibáñez del Campo
+ - abbr: AN
+ name: Antofagasta
+ - abbr: AR
+ name: Araucanía
+ - abbr: AP
+ name: Arica y Parinacota
+ - abbr: AT
+ name: Atacama
+ - abbr: BI
+ name: Bío-Bío
+ - abbr: CO
+ name: Coquimbo
+ - abbr: LI
+ name: Libertador General Bernardo O'Higgins
+ - abbr: LL
+ name: Los Lagos
+ - abbr: LR
+ name: Los Ríos
+ - abbr: MA
+ name: Magallanes
+ - abbr: ML
+ name: Maule
+ - abbr: RM
+ name: Región Metropolitana de Santiago
+ - abbr: NB
+ name: Región de Ñuble
+ - abbr: TA
+ name: Tarapacá
+ - abbr: VS
+ name: Valparaíso
+ - iso: CN
+ iso3: CHN
+ name: China
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AH
+ name: Anhui
+ - abbr: BJ
+ name: Beijing
+ - abbr: CQ
+ name: Chongqing
+ - abbr: FJ
+ name: Fujian
+ - abbr: GS
+ name: Gansu
+ - abbr: GD
+ name: Guangdong
+ - abbr: GX
+ name: Guangxi
+ - abbr: GZ
+ name: Guizhou
+ - abbr: HI
+ name: Hainan
+ - abbr: HE
+ name: Hebei
+ - abbr: HL
+ name: Heilongjiang
+ - abbr: HA
+ name: Henan
+ - abbr: HB
+ name: Hubei
+ - abbr: HN
+ name: Hunan
+ - abbr: JS
+ name: Jiangsu
+ - abbr: JX
+ name: Jiangxi
+ - abbr: JL
+ name: Jilin
+ - abbr: LN
+ name: Liaoning
+ - abbr: NM
+ name: Nei Mongol (mn)
+ - abbr: NX
+ name: Ningxia
+ - abbr: QH
+ name: Qinghai
+ - abbr: SN
+ name: Shaanxi
+ - abbr: SD
+ name: Shandong
+ - abbr: SH
+ name: Shanghai
+ - abbr: SX
+ name: Shanxi
+ - abbr: SC
+ name: Sichuan
+ - abbr: TJ
+ name: Tianjin
+ - abbr: XJ
+ name: Xinjiang
+ - abbr: XZ
+ name: Xizang
+ - abbr: YN
+ name: Yunnan
+ - abbr: ZJ
+ name: Zhejiang
+ - iso: CX
+ iso3: CXR
+ name: Christmas Island
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: CC
+ iso3: CCK
+ name: Cocos (Keeling) Islands
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: CO
+ iso3: COL
+ name: Colombia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AMA
+ name: Amazonas
+ - abbr: ANT
+ name: Antioquia
+ - abbr: ARA
+ name: Arauca
+ - abbr: ATL
+ name: Atlántico
+ - abbr: BOL
+ name: Bolívar
+ - abbr: BOY
+ name: Boyacá
+ - abbr: CAL
+ name: Caldas
+ - abbr: CAQ
+ name: Caquetá
+ - abbr: CAS
+ name: Casanare
+ - abbr: CAU
+ name: Cauca
+ - abbr: CES
+ name: Cesar
+ - abbr: CHO
+ name: Chocó
+ - abbr: CUN
+ name: Cundinamarca
+ - abbr: COR
+ name: Córdoba
+ - abbr: DC
+ name: Distrito Capital de Bogotá
+ - abbr: GUA
+ name: Guainía
+ - abbr: GUV
+ name: Guaviare
+ - abbr: HUI
+ name: Huila
+ - abbr: LAG
+ name: La Guajira
+ - abbr: MAG
+ name: Magdalena
+ - abbr: MET
+ name: Meta
+ - abbr: NAR
+ name: Nariño
+ - abbr: NSA
+ name: Norte de Santander
+ - abbr: PUT
+ name: Putumayo
+ - abbr: QUI
+ name: Quindío
+ - abbr: RIS
+ name: Risaralda
+ - abbr: SAP
+ name: San Andrés, Providencia y Santa Catalina
+ - abbr: SAN
+ name: Santander
+ - abbr: SUC
+ name: Sucre
+ - abbr: TOL
+ name: Tolima
+ - abbr: VAC
+ name: Valle del Cauca
+ - abbr: VAU
+ name: Vaupés
+ - abbr: VID
+ name: Vichada
+ - iso: KM
+ iso3: COM
+ name: Comoros
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: A
+ name: Anjouan
+ - abbr: G
+ name: Grande Comore
+ - abbr: M
+ name: Mohéli
+ - iso: CG
+ iso3: COG
+ name: Congo
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '11'
+ name: Bouenza
+ - abbr: BZV
+ name: Brazzaville
+ - abbr: '8'
+ name: Cuvette
+ - abbr: '15'
+ name: Cuvette-Ouest
+ - abbr: '5'
+ name: Kouilou
+ - abbr: '7'
+ name: Likouala
+ - abbr: '2'
+ name: Lékoumou
+ - abbr: '9'
+ name: Niari
+ - abbr: '14'
+ name: Plateaux
+ - abbr: '16'
+ name: Pointe-Noire
+ - abbr: '12'
+ name: Pool
+ - abbr: '13'
+ name: Sangha
+ - iso: CD
+ iso3: COD
+ name: Congo, The Democratic Republic of the
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BC
+ name: Bas-Congo
+ - abbr: BU
+ name: Bas-Uele
+ - abbr: HK
+ name: Haut-Katanga
+ - abbr: HL
+ name: Haut-Lomami
+ - abbr: HU
+ name: Haut-Uele
+ - abbr: IT
+ name: Ituri
+ - abbr: LO
+ name: Kabinda
+ - abbr: KE
+ name: Kasai-Oriental
+ - abbr: KS
+ name: Kasaï
+ - abbr: KN
+ name: Kinshasa
+ - abbr: KG
+ name: Kwango
+ - abbr: KL
+ name: Kwilu
+ - abbr: LU
+ name: Lualaba
+ - abbr: KC
+ name: Lulua
+ - abbr: MN
+ name: Mai-Ndombe
+ - abbr: MA
+ name: Maniema
+ - abbr: MO
+ name: Mongala
+ - abbr: NK
+ name: Nord-Kivu
+ - abbr: NU
+ name: Nord-Ubangi
+ - abbr: SA
+ name: Sankuru
+ - abbr: SK
+ name: Sud-Kivu
+ - abbr: SU
+ name: Sud-Ubangi
+ - abbr: TA
+ name: Tanganyika
+ - abbr: TO
+ name: Tshopo
+ - abbr: TU
+ name: Tshuapa
+ - abbr: EQ
+ name: Équateur
+ - iso: CK
+ iso3: COK
+ name: Cook Islands
+ states_required: false
+ zipcode_required: false
+ states: []
+ - iso: CR
+ iso3: CRI
+ name: Costa Rica
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: A
+ name: Alajuela
+ - abbr: C
+ name: Cartago
+ - abbr: G
+ name: Guanacaste
+ - abbr: H
+ name: Heredia
+ - abbr: L
+ name: Limón
+ - abbr: P
+ name: Puntarenas
+ - abbr: SJ
+ name: San José
+ - iso: HR
+ iso3: HRV
+ name: Croatia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '07'
+ name: Bjelovarsko-bilogorska županija
+ - abbr: '12'
+ name: Brodsko-posavska županija
+ - abbr: '19'
+ name: Dubrovačko-neretvanska županija
+ - abbr: '21'
+ name: Grad Zagreb
+ - abbr: '18'
+ name: Istarska županija
+ - abbr: '04'
+ name: Karlovačka županija
+ - abbr: '06'
+ name: Koprivničko-križevačka županija
+ - abbr: '02'
+ name: Krapinsko-zagorska županija
+ - abbr: '09'
+ name: Ličko-senjska županija
+ - abbr: '20'
+ name: Međimurska županija
+ - abbr: '14'
+ name: Osječko-baranjska županija
+ - abbr: '11'
+ name: Požeško-slavonska županija
+ - abbr: '08'
+ name: Primorsko-goranska županija
+ - abbr: '03'
+ name: Sisačko-moslavačka županija
+ - abbr: '17'
+ name: Splitsko-dalmatinska županija
+ - abbr: '05'
+ name: Varaždinska županija
+ - abbr: '10'
+ name: Virovitičko-podravska županija
+ - abbr: '16'
+ name: Vukovarsko-srijemska županija
+ - abbr: '13'
+ name: Zadarska županija
+ - abbr: '01'
+ name: Zagrebačka županija
+ - abbr: '15'
+ name: Šibensko-kninska županija
+ - iso: CU
+ iso3: CUB
+ name: Cuba
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '15'
+ name: Artemisa
+ - abbr: '09'
+ name: Camagüey
+ - abbr: '08'
+ name: Ciego de Ávila
+ - abbr: '06'
+ name: Cienfuegos
+ - abbr: '12'
+ name: Granma
+ - abbr: '14'
+ name: Guantánamo
+ - abbr: '11'
+ name: Holguín
+ - abbr: '99'
+ name: Isla de la Juventud
+ - abbr: '03'
+ name: La Habana
+ - abbr: '10'
+ name: Las Tunas
+ - abbr: '04'
+ name: Matanzas
+ - abbr: '16'
+ name: Mayabeque
+ - abbr: '01'
+ name: Pinar del Río
+ - abbr: '07'
+ name: Sancti Spíritus
+ - abbr: '13'
+ name: Santiago de Cuba
+ - abbr: '05'
+ name: Villa Clara
+ - iso: CW
+ iso3: CUW
+ name: Curaçao
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: CY
+ iso3: CYP
+ name: Cyprus
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '04'
+ name: Ammochostos
+ - abbr: '06'
+ name: Keryneia
+ - abbr: '03'
+ name: Larnaka
+ - abbr: '01'
+ name: Lefkosia
+ - abbr: '02'
+ name: Lemesos
+ - abbr: '05'
+ name: Pafos
+ - iso: CZ
+ iso3: CZE
+ name: Czechia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '201'
+ name: Benešov
+ - abbr: '202'
+ name: Beroun
+ - abbr: '641'
+ name: Blansko
+ - abbr: '642'
+ name: Brno-město
+ - abbr: '643'
+ name: Brno-venkov
+ - abbr: '801'
+ name: Bruntál
+ - abbr: '644'
+ name: Břeclav
+ - abbr: '411'
+ name: Cheb
+ - abbr: '422'
+ name: Chomutov
+ - abbr: '531'
+ name: Chrudim
+ - abbr: '321'
+ name: Domažlice
+ - abbr: '421'
+ name: Děčín
+ - abbr: '802'
+ name: Frýdek-Místek
+ - abbr: '631'
+ name: Havlíčkův Brod
+ - abbr: '645'
+ name: Hodonín
+ - abbr: '521'
+ name: Hradec Králové
+ - abbr: '512'
+ name: Jablonec nad Nisou
+ - abbr: '711'
+ name: Jeseník
+ - abbr: '632'
+ name: Jihlava
+ - abbr: '64'
+ name: Jihomoravský kraj
+ - abbr: '31'
+ name: Jihočeský kraj
+ - abbr: '313'
+ name: Jindřichův Hradec
+ - abbr: '522'
+ name: Jičín
+ - abbr: '41'
+ name: Karlovarský kraj
+ - abbr: '412'
+ name: Karlovy Vary
+ - abbr: '803'
+ name: Karviná
+ - abbr: '203'
+ name: Kladno
+ - abbr: '322'
+ name: Klatovy
+ - abbr: '204'
+ name: Kolín
+ - abbr: '63'
+ name: Kraj Vysočina
+ - abbr: '721'
+ name: Kroměříž
+ - abbr: '52'
+ name: Královéhradecký kraj
+ - abbr: '205'
+ name: Kutná Hora
+ - abbr: '513'
+ name: Liberec
+ - abbr: '51'
+ name: Liberecký kraj
+ - abbr: '423'
+ name: Litoměřice
+ - abbr: '424'
+ name: Louny
+ - abbr: '207'
+ name: Mladá Boleslav
+ - abbr: '80'
+ name: Moravskoslezský kraj
+ - abbr: '425'
+ name: Most
+ - abbr: '206'
+ name: Mělník
+ - abbr: '804'
+ name: Nový Jičín
+ - abbr: '208'
+ name: Nymburk
+ - abbr: '523'
+ name: Náchod
+ - abbr: '712'
+ name: Olomouc
+ - abbr: '71'
+ name: Olomoucký kraj
+ - abbr: '805'
+ name: Opava
+ - abbr: '806'
+ name: Ostrava-město
+ - abbr: '532'
+ name: Pardubice
+ - abbr: '53'
+ name: Pardubický kraj
+ - abbr: '633'
+ name: Pelhřimov
+ - abbr: '324'
+ name: Plzeň-jih
+ - abbr: '323'
+ name: Plzeň-město
+ - abbr: '325'
+ name: Plzeň-sever
+ - abbr: '32'
+ name: Plzeňský kraj
+ - abbr: '315'
+ name: Prachatice
+ - abbr: '10'
+ name: Praha, Hlavní město
+ - abbr: '209'
+ name: Praha-východ
+ - abbr: 20A
+ name: Praha-západ
+ - abbr: '713'
+ name: Prostějov
+ - abbr: '314'
+ name: Písek
+ - abbr: '714'
+ name: Přerov
+ - abbr: 20B
+ name: Příbram
+ - abbr: 20C
+ name: Rakovník
+ - abbr: '326'
+ name: Rokycany
+ - abbr: '524'
+ name: Rychnov nad Kněžnou
+ - abbr: '514'
+ name: Semily
+ - abbr: '413'
+ name: Sokolov
+ - abbr: '316'
+ name: Strakonice
+ - abbr: '20'
+ name: Středočeský kraj
+ - abbr: '533'
+ name: Svitavy
+ - abbr: '327'
+ name: Tachov
+ - abbr: '426'
+ name: Teplice
+ - abbr: '525'
+ name: Trutnov
+ - abbr: '317'
+ name: Tábor
+ - abbr: '634'
+ name: Třebíč
+ - abbr: '722'
+ name: Uherské Hradiště
+ - abbr: '723'
+ name: Vsetín
+ - abbr: '646'
+ name: Vyškov
+ - abbr: '724'
+ name: Zlín
+ - abbr: '72'
+ name: Zlínský kraj
+ - abbr: '647'
+ name: Znojmo
+ - abbr: '42'
+ name: Ústecký kraj
+ - abbr: '427'
+ name: Ústí nad Labem
+ - abbr: '534'
+ name: Ústí nad Orlicí
+ - abbr: '511'
+ name: Česká Lípa
+ - abbr: '311'
+ name: České Budějovice
+ - abbr: '312'
+ name: Český Krumlov
+ - abbr: '715'
+ name: Šumperk
+ - abbr: '635'
+ name: Žďár nad Sázavou
+ - iso: CI
+ iso3: CIV
+ name: Côte d'Ivoire
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AB
+ name: Abidjan
+ - abbr: DN
+ name: Denguélé
+ - abbr: CM
+ name: District de la Comoé
+ - abbr: LC
+ name: District des Lacs
+ - abbr: LG
+ name: District des Lagunes
+ - abbr: MG
+ name: District des Montagnes
+ - abbr: BS
+ name: District du Bas-Sassandra
+ - abbr: SM
+ name: District du Sassandra-Marahoué
+ - abbr: WR
+ name: District du Woroba
+ - abbr: GD
+ name: Gôh-Djiboua
+ - abbr: SV
+ name: Savanes
+ - abbr: VB
+ name: Vallée du Bandama
+ - abbr: YM
+ name: Yamoussoukro
+ - abbr: ZZ
+ name: Zanzan
+ - iso: DK
+ iso3: DNK
+ name: Denmark
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '84'
+ name: Hovedstaden
+ - abbr: '82'
+ name: Midtjylland
+ - abbr: '81'
+ name: Nordjylland
+ - abbr: '85'
+ name: Sjælland
+ - abbr: '83'
+ name: Syddanmark
+ - iso: DJ
+ iso3: DJI
+ name: Djibouti
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AS
+ name: Ali Sabieh
+ - abbr: AR
+ name: Arta
+ - abbr: DI
+ name: Dikhil
+ - abbr: DJ
+ name: Djibouti
+ - abbr: OB
+ name: Obock
+ - abbr: TA
+ name: Tadjourah
+ - iso: DM
+ iso3: DMA
+ name: Dominica
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '02'
+ name: Saint Andrew
+ - abbr: '03'
+ name: Saint David
+ - abbr: '04'
+ name: Saint George
+ - abbr: '05'
+ name: Saint John
+ - abbr: '06'
+ name: Saint Joseph
+ - abbr: '07'
+ name: Saint Luke
+ - abbr: '08'
+ name: Saint Mark
+ - abbr: '09'
+ name: Saint Patrick
+ - abbr: '10'
+ name: Saint Paul
+ - abbr: '11'
+ name: Saint Peter
+ - iso: DO
+ iso3: DOM
+ name: Dominican Republic
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '02'
+ name: Azua
+ - abbr: '03'
+ name: Bahoruco
+ - abbr: '04'
+ name: Barahona
+ - abbr: '33'
+ name: Cibao Nordeste
+ - abbr: '34'
+ name: Cibao Noroeste
+ - abbr: '35'
+ name: Cibao Norte
+ - abbr: '36'
+ name: Cibao Sur
+ - abbr: '05'
+ name: Dajabón
+ - abbr: '01'
+ name: Distrito Nacional (Santo Domingo)
+ - abbr: '06'
+ name: Duarte
+ - abbr: '08'
+ name: El Seybo [El Seibo]
+ - abbr: '37'
+ name: El Valle
+ - abbr: '38'
+ name: Enriquillo
+ - abbr: '09'
+ name: Espaillat
+ - abbr: '30'
+ name: Hato Mayor
+ - abbr: '39'
+ name: Higüamo
+ - abbr: '10'
+ name: Independencia
+ - abbr: '11'
+ name: La Altagracia
+ - abbr: '07'
+ name: La Estrelleta [Elías Piña]
+ - abbr: '12'
+ name: La Romana
+ - abbr: '13'
+ name: La Vega
+ - abbr: '14'
+ name: María Trinidad Sánchez
+ - abbr: '28'
+ name: Monseñor Nouel
+ - abbr: '15'
+ name: Monte Cristi
+ - abbr: '29'
+ name: Monte Plata
+ - abbr: '40'
+ name: Ozama
+ - abbr: '16'
+ name: Pedernales
+ - abbr: '17'
+ name: Peravia
+ - abbr: '18'
+ name: Puerto Plata
+ - abbr: '19'
+ name: Salcedo
+ - abbr: '20'
+ name: Samaná
+ - abbr: '21'
+ name: San Cristóbal
+ - abbr: '31'
+ name: San Jose de Ocoa
+ - abbr: '22'
+ name: San Juan
+ - abbr: '23'
+ name: San Pedro de Macorís
+ - abbr: '25'
+ name: Santiago
+ - abbr: '26'
+ name: Santiago Rodríguez
+ - abbr: '32'
+ name: Santo Domingo
+ - abbr: '24'
+ name: Sánchez Ramírez
+ - abbr: '41'
+ name: Valdesia
+ - abbr: '27'
+ name: Valverde
+ - abbr: '42'
+ name: Yuma
+ - iso: EC
+ iso3: ECU
+ name: Ecuador
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: A
+ name: Azuay
+ - abbr: B
+ name: Bolívar
+ - abbr: C
+ name: Carchi
+ - abbr: F
+ name: Cañar
+ - abbr: H
+ name: Chimborazo
+ - abbr: X
+ name: Cotopaxi
+ - abbr: O
+ name: El Oro
+ - abbr: E
+ name: Esmeraldas
+ - abbr: W
+ name: Galápagos
+ - abbr: G
+ name: Guayas
+ - abbr: I
+ name: Imbabura
+ - abbr: L
+ name: Loja
+ - abbr: R
+ name: Los Ríos
+ - abbr: M
+ name: Manabí
+ - abbr: S
+ name: Morona-Santiago
+ - abbr: "N"
+ name: Napo
+ - abbr: D
+ name: Orellana
+ - abbr: "Y"
+ name: Pastaza
+ - abbr: P
+ name: Pichincha
+ - abbr: SE
+ name: Santa Elena
+ - abbr: SD
+ name: Santo Domingo de los Tsachilas
+ - abbr: U
+ name: Sucumbíos
+ - abbr: T
+ name: Tungurahua
+ - abbr: Z
+ name: Zamora-Chinchipe
+ - iso: EG
+ iso3: EGY
+ name: Egypt
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: DK
+ name: Ad Daqahliyah
+ - abbr: BA
+ name: Al Bahr al Ahmar
+ - abbr: BH
+ name: Al Buhayrah
+ - abbr: FYM
+ name: Al Fayyum
+ - abbr: GH
+ name: Al Gharbiyah
+ - abbr: ALX
+ name: Al Iskandariyah
+ - abbr: IS
+ name: Al Ismā`īlīyah
+ - abbr: GZ
+ name: Al Jizah
+ - abbr: MNF
+ name: Al Minufiyah
+ - abbr: MN
+ name: Al Minya
+ - abbr: C
+ name: Al Qahirah
+ - abbr: KB
+ name: Al Qalyubiyah
+ - abbr: WAD
+ name: Al Wadi al Jadid
+ - abbr: SUZ
+ name: As Suways
+ - abbr: SHR
+ name: Ash Sharqiyah
+ - abbr: ASN
+ name: Aswan
+ - abbr: AST
+ name: Asyut
+ - abbr: BNS
+ name: Bani Suwayf
+ - abbr: PTS
+ name: Būr Sa`īd
+ - abbr: DT
+ name: Dumyat
+ - abbr: JS
+ name: Janub Sina'
+ - abbr: KFS
+ name: Kafr ash Shaykh
+ - abbr: MT
+ name: Matrūh
+ - abbr: KN
+ name: Qina
+ - abbr: SIN
+ name: Shamal Sina'
+ - abbr: SHG
+ name: Suhaj
+ - abbr: LX
+ name: al-Uqsur
+ - iso: SV
+ iso3: SLV
+ name: El Salvador
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AH
+ name: Ahuachapán
+ - abbr: CA
+ name: Cabañas
+ - abbr: CH
+ name: Chalatenango
+ - abbr: CU
+ name: Cuscatlán
+ - abbr: LI
+ name: La Libertad
+ - abbr: PA
+ name: La Paz
+ - abbr: UN
+ name: La Unión
+ - abbr: MO
+ name: Morazán
+ - abbr: SM
+ name: San Miguel
+ - abbr: SS
+ name: San Salvador
+ - abbr: SV
+ name: San Vicente
+ - abbr: SA
+ name: Santa Ana
+ - abbr: SO
+ name: Sonsonate
+ - abbr: US
+ name: Usulután
+ - iso: GQ
+ iso3: GNQ
+ name: Equatorial Guinea
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AN
+ name: Annobón
+ - abbr: BN
+ name: Bioko Norte
+ - abbr: BS
+ name: Bioko Sur
+ - abbr: CS
+ name: Centro Sur
+ - abbr: DJ
+ name: Djibloho
+ - abbr: KN
+ name: Kie-Ntem
+ - abbr: LI
+ name: Litoral
+ - abbr: C
+ name: Región Continental
+ - abbr: I
+ name: Región Insular
+ - abbr: WN
+ name: Wele-Nzás
+ - iso: ER
+ iso3: ERI
+ name: Eritrea
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AN
+ name: Anseba
+ - abbr: DU
+ name: Debub
+ - abbr: DK
+ name: Debubawi Keyih Bahri [Debub-Keih-Bahri]
+ - abbr: GB
+ name: Gash-Barka
+ - abbr: MA
+ name: Maakel [Maekel]
+ - abbr: SK
+ name: Semenawi Keyih Bahri [Semien-Keih-Bahri]
+ - iso: EE
+ iso3: EST
+ name: Estonia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '130'
+ name: Alutaguse
+ - abbr: '141'
+ name: Anija
+ - abbr: '142'
+ name: Antsla
+ - abbr: '171'
+ name: Elva
+ - abbr: '184'
+ name: Haapsalu
+ - abbr: '191'
+ name: Haljala
+ - abbr: '37'
+ name: Harjumaa
+ - abbr: '198'
+ name: Harku
+ - abbr: '205'
+ name: Hiiumaa
+ - abbr: '39'
+ name: Hiiumaa
+ - abbr: '214'
+ name: Häädemeeste
+ - abbr: '45'
+ name: Ida-Virumaa
+ - abbr: '255'
+ name: Järva
+ - abbr: '52'
+ name: Järvamaa
+ - abbr: '245'
+ name: Jõelähtme
+ - abbr: '247'
+ name: Jõgeva
+ - abbr: '50'
+ name: Jõgevamaa
+ - abbr: '251'
+ name: Jõhvi
+ - abbr: '272'
+ name: Kadrina
+ - abbr: '283'
+ name: Kambja
+ - abbr: '284'
+ name: Kanepi
+ - abbr: '291'
+ name: Kastre
+ - abbr: '293'
+ name: Kehtna
+ - abbr: '296'
+ name: Keila
+ - abbr: '303'
+ name: Kihnu
+ - abbr: '305'
+ name: Kiili
+ - abbr: '317'
+ name: Kohila
+ - abbr: '321'
+ name: Kohtla-Järve
+ - abbr: '338'
+ name: Kose
+ - abbr: '353'
+ name: Kuusalu
+ - abbr: '424'
+ name: Loksa
+ - abbr: '432'
+ name: Luunja
+ - abbr: '431'
+ name: Lääne-Harju
+ - abbr: '441'
+ name: Lääne-Nigula
+ - abbr: '60'
+ name: Lääne-Virumaa
+ - abbr: '56'
+ name: Läänemaa
+ - abbr: '430'
+ name: Lääneranna
+ - abbr: '442'
+ name: Lüganuse
+ - abbr: '446'
+ name: Maardu
+ - abbr: '478'
+ name: Muhu
+ - abbr: '480'
+ name: Mulgi
+ - abbr: '486'
+ name: Mustvee
+ - abbr: '503'
+ name: Märjamaa
+ - abbr: '511'
+ name: Narva
+ - abbr: '514'
+ name: Narva-Jõesuu
+ - abbr: '528'
+ name: Nõo
+ - abbr: '557'
+ name: Otepää
+ - abbr: '567'
+ name: Paide
+ - abbr: '586'
+ name: Peipsiääre
+ - abbr: '624'
+ name: Pärnu
+ - abbr: '68'
+ name: Pärnumaa
+ - abbr: '638'
+ name: Põhja-Pärnumaa
+ - abbr: '615'
+ name: Põhja-Sakala
+ - abbr: '618'
+ name: Põltsamaa
+ - abbr: '622'
+ name: Põlva
+ - abbr: '64'
+ name: Põlvamaa
+ - abbr: '651'
+ name: Raasiku
+ - abbr: '653'
+ name: Rae
+ - abbr: '661'
+ name: Rakvere
+ - abbr: '663'
+ name: Rakvere
+ - abbr: '668'
+ name: Rapla
+ - abbr: '71'
+ name: Raplamaa
+ - abbr: '689'
+ name: Ruhnu
+ - abbr: '708'
+ name: Räpina
+ - abbr: '698'
+ name: Rõuge
+ - abbr: '712'
+ name: Saarde
+ - abbr: '714'
+ name: Saaremaa
+ - abbr: '74'
+ name: Saaremaa
+ - abbr: '719'
+ name: Saku
+ - abbr: '726'
+ name: Saue
+ - abbr: '732'
+ name: Setomaa
+ - abbr: '735'
+ name: Sillamäe
+ - abbr: '784'
+ name: Tallinn
+ - abbr: '792'
+ name: Tapa
+ - abbr: '793'
+ name: Tartu
+ - abbr: '796'
+ name: Tartu
+ - abbr: '79'
+ name: Tartumaa
+ - abbr: '803'
+ name: Toila
+ - abbr: '809'
+ name: Tori
+ - abbr: '824'
+ name: Tõrva
+ - abbr: '834'
+ name: Türi
+ - abbr: '855'
+ name: Valga
+ - abbr: '81'
+ name: Valgamaa
+ - abbr: '890'
+ name: Viimsi
+ - abbr: '899'
+ name: Viljandi
+ - abbr: '897'
+ name: Viljandi
+ - abbr: '84'
+ name: Viljandimaa
+ - abbr: '901'
+ name: Vinni
+ - abbr: '903'
+ name: Viru-Nigula
+ - abbr: '907'
+ name: Vormsi
+ - abbr: '928'
+ name: Väike-Maarja
+ - abbr: '917'
+ name: Võru
+ - abbr: '919'
+ name: Võru
+ - abbr: '87'
+ name: Võrumaa
+ - iso: SZ
+ iso3: SWZ
+ name: Eswatini
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: HH
+ name: Hhohho
+ - abbr: LU
+ name: Lubombo
+ - abbr: MA
+ name: Manzini
+ - abbr: SH
+ name: Shiselweni
+ - iso: ET
+ iso3: ETH
+ name: Ethiopia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AA
+ name: Adis Abeba
+ - abbr: AF
+ name: Afar
+ - abbr: AM
+ name: Amara
+ - abbr: BE
+ name: Binshangul Gumuz
+ - abbr: DD
+ name: Dire Dawa
+ - abbr: GA
+ name: Gambela Hizboch
+ - abbr: HA
+ name: Hareri Hizb
+ - abbr: OR
+ name: Oromiya
+ - abbr: SO
+ name: Sumale
+ - abbr: TI
+ name: Tigray
+ - abbr: SN
+ name: YeDebub Biheroch Bihereseboch na Hizboch
+ - iso: FK
+ iso3: FLK
+ name: Falkland Islands (Malvinas)
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: FO
+ iso3: FRO
+ name: Faroe Islands
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: FJ
+ iso3: FJI
+ name: Fiji
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '01'
+ name: Ba
+ - abbr: '02'
+ name: Bua
+ - abbr: '03'
+ name: Cakaudrove
+ - abbr: C
+ name: Central
+ - abbr: E
+ name: Eastern
+ - abbr: '04'
+ name: Kadavu
+ - abbr: '05'
+ name: Lau
+ - abbr: '06'
+ name: Lomaiviti
+ - abbr: '07'
+ name: Macuata
+ - abbr: '08'
+ name: Nadroga-Navosa
+ - abbr: '09'
+ name: Naitasiri
+ - abbr: '10'
+ name: Namosi
+ - abbr: "N"
+ name: Northern
+ - abbr: '11'
+ name: Ra
+ - abbr: '12'
+ name: Rewa
+ - abbr: R
+ name: Rotuma
+ - abbr: '13'
+ name: Serua
+ - abbr: '14'
+ name: Tailevu
+ - abbr: W
+ name: Western
+ - iso: FI
+ iso3: FIN
+ name: Finland
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Ahvenanmaan maakunta
+ - abbr: '02'
+ name: Etelä-Karjala
+ - abbr: '03'
+ name: Etelä-Pohjanmaa
+ - abbr: '04'
+ name: Etelä-Savo
+ - abbr: '05'
+ name: Kainuu
+ - abbr: '06'
+ name: Kanta-Häme
+ - abbr: '07'
+ name: Keski-Pohjanmaa
+ - abbr: '08'
+ name: Keski-Suomi
+ - abbr: '09'
+ name: Kymenlaakso
+ - abbr: '10'
+ name: Lappi
+ - abbr: '11'
+ name: Pirkanmaa
+ - abbr: '12'
+ name: Pohjanmaa
+ - abbr: '13'
+ name: Pohjois-Karjala
+ - abbr: '14'
+ name: Pohjois-Pohjanmaa
+ - abbr: '15'
+ name: Pohjois-Savo
+ - abbr: '16'
+ name: Päijät-Häme
+ - abbr: '17'
+ name: Satakunta
+ - abbr: '18'
+ name: Uusimaa
+ - abbr: '19'
+ name: Varsinais-Suomi
+ - iso: FR
+ iso3: FRA
+ name: France
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Ain
+ - abbr: '02'
+ name: Aisne
+ - abbr: '03'
+ name: Allier
+ - abbr: '06'
+ name: Alpes-Maritimes
+ - abbr: '04'
+ name: Alpes-de-Haute-Provence
+ - abbr: 6AE
+ name: Alsace
+ - abbr: '08'
+ name: Ardennes
+ - abbr: '07'
+ name: Ardèche
+ - abbr: '09'
+ name: Ariège
+ - abbr: '10'
+ name: Aube
+ - abbr: '11'
+ name: Aude
+ - abbr: ARA
+ name: Auvergne-Rhône-Alpes
+ - abbr: '12'
+ name: Aveyron
+ - abbr: '67'
+ name: Bas-Rhin
+ - abbr: '13'
+ name: Bouches-du-Rhône
+ - abbr: BFC
+ name: Bourgogne-Franche-Comté
+ - abbr: BRE
+ name: Bretagne
+ - abbr: '14'
+ name: Calvados
+ - abbr: '15'
+ name: Cantal
+ - abbr: CVL
+ name: Centre-Val de Loire
+ - abbr: '16'
+ name: Charente
+ - abbr: '17'
+ name: Charente-Maritime
+ - abbr: '18'
+ name: Cher
+ - abbr: CP
+ name: Clipperton
+ - abbr: '19'
+ name: Corrèze
+ - abbr: 20R
+ name: Corse
+ - abbr: 2A
+ name: Corse-du-Sud
+ - abbr: '23'
+ name: Creuse
+ - abbr: '21'
+ name: Côte-d'Or
+ - abbr: '22'
+ name: Côtes-d'Armor
+ - abbr: '79'
+ name: Deux-Sèvres
+ - abbr: '24'
+ name: Dordogne
+ - abbr: '25'
+ name: Doubs
+ - abbr: '26'
+ name: Drôme
+ - abbr: '91'
+ name: Essonne
+ - abbr: '27'
+ name: Eure
+ - abbr: '28'
+ name: Eure-et-Loir
+ - abbr: '29'
+ name: Finistère
+ - abbr: '30'
+ name: Gard
+ - abbr: '32'
+ name: Gers
+ - abbr: '33'
+ name: Gironde
+ - abbr: GES
+ name: Grand Est
+ - abbr: '971'
+ name: Guadeloupe
+ - abbr: '973'
+ name: Guyane (française)
+ - abbr: '68'
+ name: Haut-Rhin
+ - abbr: 2B
+ name: Haute-Corse
+ - abbr: '31'
+ name: Haute-Garonne
+ - abbr: '43'
+ name: Haute-Loire
+ - abbr: '52'
+ name: Haute-Marne
+ - abbr: '74'
+ name: Haute-Savoie
+ - abbr: '70'
+ name: Haute-Saône
+ - abbr: '87'
+ name: Haute-Vienne
+ - abbr: '05'
+ name: Hautes-Alpes
+ - abbr: '65'
+ name: Hautes-Pyrénées
+ - abbr: HDF
+ name: Hauts-de-France
+ - abbr: '92'
+ name: Hauts-de-Seine
+ - abbr: '34'
+ name: Hérault
+ - abbr: '35'
+ name: Ille-et-Vilaine
+ - abbr: '36'
+ name: Indre
+ - abbr: '37'
+ name: Indre-et-Loire
+ - abbr: '38'
+ name: Isère
+ - abbr: '39'
+ name: Jura
+ - abbr: '974'
+ name: La Réunion
+ - abbr: '40'
+ name: Landes
+ - abbr: '41'
+ name: Loir-et-Cher
+ - abbr: '42'
+ name: Loire
+ - abbr: '44'
+ name: Loire-Atlantique
+ - abbr: '45'
+ name: Loiret
+ - abbr: '46'
+ name: Lot
+ - abbr: '47'
+ name: Lot-et-Garonne
+ - abbr: '48'
+ name: Lozère
+ - abbr: '49'
+ name: Maine-et-Loire
+ - abbr: '50'
+ name: Manche
+ - abbr: '51'
+ name: Marne
+ - abbr: '972'
+ name: Martinique
+ - abbr: '53'
+ name: Mayenne
+ - abbr: '976'
+ name: Mayotte
+ - abbr: '54'
+ name: Meurthe-et-Moselle
+ - abbr: '55'
+ name: Meuse
+ - abbr: '56'
+ name: Morbihan
+ - abbr: '57'
+ name: Moselle
+ - abbr: 69M
+ name: Métropole de Lyon
+ - abbr: '58'
+ name: Nièvre
+ - abbr: '59'
+ name: Nord
+ - abbr: NOR
+ name: Normandie
+ - abbr: NAQ
+ name: Nouvelle-Aquitaine
+ - abbr: NC
+ name: Nouvelle-Calédonie
+ - abbr: OCC
+ name: Occitanie
+ - abbr: '60'
+ name: Oise
+ - abbr: '61'
+ name: Orne
+ - abbr: 75C
+ name: Paris
+ - abbr: '62'
+ name: Pas-de-Calais
+ - abbr: PDL
+ name: Pays de la Loire
+ - abbr: PF
+ name: Polynésie française
+ - abbr: PAC
+ name: Provence-Alpes-Côte d'Azur
+ - abbr: '63'
+ name: Puy-de-Dôme
+ - abbr: '64'
+ name: Pyrénées-Atlantiques
+ - abbr: '66'
+ name: Pyrénées-Orientales
+ - abbr: '69'
+ name: Rhône
+ - abbr: BL
+ name: Saint-Barthélemy
+ - abbr: MF
+ name: Saint-Martin
+ - abbr: PM
+ name: Saint-Pierre-et-Miquelon
+ - abbr: '72'
+ name: Sarthe
+ - abbr: '73'
+ name: Savoie
+ - abbr: '71'
+ name: Saône-et-Loire
+ - abbr: '76'
+ name: Seine-Maritime
+ - abbr: '93'
+ name: Seine-Saint-Denis
+ - abbr: '77'
+ name: Seine-et-Marne
+ - abbr: '80'
+ name: Somme
+ - abbr: '81'
+ name: Tarn
+ - abbr: '82'
+ name: Tarn-et-Garonne
+ - abbr: TF
+ name: Terres Australes Françaises
+ - abbr: '90'
+ name: Territoire de Belfort
+ - abbr: '95'
+ name: Val-d'Oise
+ - abbr: '94'
+ name: Val-de-Marne
+ - abbr: '83'
+ name: Var
+ - abbr: '84'
+ name: Vaucluse
+ - abbr: '85'
+ name: Vendée
+ - abbr: '86'
+ name: Vienne
+ - abbr: '88'
+ name: Vosges
+ - abbr: WF
+ name: Wallis-et-Futuna
+ - abbr: '89'
+ name: Yonne
+ - abbr: '78'
+ name: Yvelines
+ - abbr: IDF
+ name: Île-de-France
+ - iso: GF
+ iso3: GUF
+ name: French Guiana
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: PF
+ iso3: PYF
+ name: French Polynesia
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: GA
+ iso3: GAB
+ name: Gabon
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '1'
+ name: Estuaire
+ - abbr: '2'
+ name: Haut-Ogooué
+ - abbr: '3'
+ name: Moyen-Ogooué
+ - abbr: '4'
+ name: Ngounié
+ - abbr: '5'
+ name: Nyanga
+ - abbr: '6'
+ name: Ogooué-Ivindo
+ - abbr: '7'
+ name: Ogooué-Lolo
+ - abbr: '8'
+ name: Ogooué-Maritime
+ - abbr: '9'
+ name: Woleu-Ntem
+ - iso: GM
+ iso3: GMB
+ name: Gambia
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: B
+ name: Banjul
+ - abbr: L
+ name: Lower River
+ - abbr: M
+ name: MacCarthy Island
+ - abbr: "N"
+ name: North Bank
+ - abbr: U
+ name: Upper River
+ - abbr: W
+ name: Western
+ - iso: GE
+ iso3: GEO
+ name: Georgia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AB
+ name: Abkhazia
+ - abbr: AJ
+ name: Ajaria
+ - abbr: GU
+ name: Guria
+ - abbr: IM
+ name: Imereti
+ - abbr: KA
+ name: Kakheti
+ - abbr: KK
+ name: Kvemo Kartli
+ - abbr: MM
+ name: Mtskheta-Mtianeti
+ - abbr: RL
+ name: Racha-Lechkhumi [and] Kvemo Svaneti
+ - abbr: SZ
+ name: Samegrelo-Zemo Svaneti
+ - abbr: SJ
+ name: Samtskhe-Javakheti
+ - abbr: SK
+ name: Shida Kartli
+ - abbr: TB
+ name: Tbilisi
+ - iso: DE
+ iso3: DEU
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BW
+ name: Baden-Württemberg
+ - abbr: BY
+ name: Bayern
+ - abbr: BE
+ name: Berlin
+ - abbr: BB
+ name: Brandenburg
+ - abbr: HB
+ name: Bremen
+ - abbr: HH
+ name: Hamburg
+ - abbr: HE
+ name: Hessen
+ - abbr: MV
+ name: Mecklenburg-Vorpommern
+ - abbr: NI
+ name: Niedersachsen
+ - abbr: NW
+ name: Nordrhein-Westfalen
+ - abbr: RP
+ name: Rheinland-Pfalz
+ - abbr: SL
+ name: Saarland
+ - abbr: SN
+ name: Sachsen
+ - abbr: ST
+ name: Sachsen-Anhalt
+ - abbr: SH
+ name: Schleswig-Holstein
+ - abbr: TH
+ name: Thüringen
+ - iso: GH
+ iso3: GHA
+ name: Ghana
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AF
+ name: Ahafo
+ - abbr: AH
+ name: Ashanti
+ - abbr: BO
+ name: Bono
+ - abbr: BE
+ name: Bono East
+ - abbr: CP
+ name: Central
+ - abbr: EP
+ name: Eastern
+ - abbr: AA
+ name: Greater Accra
+ - abbr: NE
+ name: North East
+ - abbr: NP
+ name: Northern
+ - abbr: OT
+ name: Oti
+ - abbr: SV
+ name: Savannah
+ - abbr: UE
+ name: Upper East
+ - abbr: UW
+ name: Upper West
+ - abbr: TV
+ name: Volta
+ - abbr: WP
+ name: Western
+ - abbr: WN
+ name: Western North
+ - iso: GI
+ iso3: GIB
+ name: Gibraltar
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: GR
+ iso3: GRC
+ name: Greece
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: A
+ name: Anatolikí Makedonía kai Thráki
+ - abbr: I
+ name: Attikí
+ - abbr: G
+ name: Dytikí Elláda
+ - abbr: C
+ name: Dytikí Makedonía
+ - abbr: F
+ name: Ionía Nísia
+ - abbr: B
+ name: Kentrikí Makedonía
+ - abbr: M
+ name: Kríti
+ - abbr: L
+ name: Nótio Aigaío
+ - abbr: J
+ name: Pelopónnisos
+ - abbr: H
+ name: Stereá Elláda
+ - abbr: E
+ name: Thessalía
+ - abbr: K
+ name: Vóreio Aigaío
+ - abbr: '69'
+ name: Ágion Óros
+ - abbr: D
+ name: Ípeiros
+ - iso: GL
+ iso3: GRL
+ name: Greenland
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AV
+ name: Avannaata Kommunia
+ - abbr: QT
+ name: Kommune Qeqertalik
+ - abbr: KU
+ name: Kujalleq
+ - abbr: QE
+ name: Qeqqata
+ - abbr: SM
+ name: Sermersooq
+ - iso: GD
+ iso3: GRD
+ name: Grenada
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '01'
+ name: Saint Andrew
+ - abbr: '02'
+ name: Saint David
+ - abbr: '03'
+ name: Saint George
+ - abbr: '04'
+ name: Saint John
+ - abbr: '05'
+ name: Saint Mark
+ - abbr: '06'
+ name: Saint Patrick
+ - abbr: '10'
+ name: Southern Grenadine Islands
+ - iso: GP
+ iso3: GLP
+ name: Guadeloupe
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: GU
+ iso3: GUM
+ name: Guam
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: GT
+ iso3: GTM
+ name: Guatemala
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '16'
+ name: Alta Verapaz
+ - abbr: '15'
+ name: Baja Verapaz
+ - abbr: '04'
+ name: Chimaltenango
+ - abbr: '20'
+ name: Chiquimula
+ - abbr: '02'
+ name: El Progreso
+ - abbr: '05'
+ name: Escuintla
+ - abbr: '01'
+ name: Guatemala
+ - abbr: '13'
+ name: Huehuetenango
+ - abbr: '18'
+ name: Izabal
+ - abbr: '21'
+ name: Jalapa
+ - abbr: '22'
+ name: Jutiapa
+ - abbr: '17'
+ name: Petén
+ - abbr: '09'
+ name: Quetzaltenango
+ - abbr: '14'
+ name: Quiché
+ - abbr: '11'
+ name: Retalhuleu
+ - abbr: '03'
+ name: Sacatepéquez
+ - abbr: '12'
+ name: San Marcos
+ - abbr: '06'
+ name: Santa Rosa
+ - abbr: '07'
+ name: Sololá
+ - abbr: '10'
+ name: Suchitepéquez
+ - abbr: '08'
+ name: Totonicapán
+ - abbr: '19'
+ name: Zacapa
+ - iso: GG
+ iso3: GGY
+ name: Guernsey
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: GN
+ iso3: GIN
+ name: Guinea
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BE
+ name: Beyla
+ - abbr: BF
+ name: Boffa
+ - abbr: BK
+ name: Boké
+ - abbr: C
+ name: Conakry
+ - abbr: CO
+ name: Coyah
+ - abbr: DB
+ name: Dabola
+ - abbr: DL
+ name: Dalaba
+ - abbr: DI
+ name: Dinguiraye
+ - abbr: DU
+ name: Dubréka
+ - abbr: FA
+ name: Faranah
+ - abbr: FO
+ name: Forécariah
+ - abbr: FR
+ name: Fria
+ - abbr: GA
+ name: Gaoual
+ - abbr: GU
+ name: Guékédou
+ - abbr: KA
+ name: Kankan
+ - abbr: KD
+ name: Kindia
+ - abbr: KS
+ name: Kissidougou
+ - abbr: KB
+ name: Koubia
+ - abbr: KN
+ name: Koundara
+ - abbr: KO
+ name: Kouroussa
+ - abbr: KE
+ name: Kérouané
+ - abbr: LA
+ name: Labé
+ - abbr: LO
+ name: Lola
+ - abbr: LE
+ name: Lélouma
+ - abbr: MC
+ name: Macenta
+ - abbr: ML
+ name: Mali
+ - abbr: MM
+ name: Mamou
+ - abbr: MD
+ name: Mandiana
+ - abbr: NZ
+ name: Nzérékoré
+ - abbr: PI
+ name: Pita
+ - abbr: B
+ name: Région de Boké
+ - abbr: F
+ name: Région de Faranah
+ - abbr: K
+ name: Région de Kankan
+ - abbr: D
+ name: Région de Kindia
+ - abbr: L
+ name: Région de Labé
+ - abbr: M
+ name: Région de Mamou
+ - abbr: "N"
+ name: Région de Nzérékoré
+ - abbr: SI
+ name: Siguiri
+ - abbr: TO
+ name: Tougué
+ - abbr: TE
+ name: Télimélé
+ - abbr: YO
+ name: Yomou
+ - iso: GW
+ iso3: GNB
+ name: Guinea-Bissau
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BA
+ name: Bafatá
+ - abbr: BM
+ name: Biombo
+ - abbr: BS
+ name: Bissau
+ - abbr: BL
+ name: Bolama
+ - abbr: CA
+ name: Cacheu
+ - abbr: GA
+ name: Gabú
+ - abbr: L
+ name: Leste
+ - abbr: "N"
+ name: Norte
+ - abbr: OI
+ name: Oio
+ - abbr: QU
+ name: Quinara
+ - abbr: S
+ name: Sul
+ - abbr: TO
+ name: Tombali
+ - iso: GY
+ iso3: GUY
+ name: Guyana
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BA
+ name: Barima-Waini
+ - abbr: CU
+ name: Cuyuni-Mazaruni
+ - abbr: DE
+ name: Demerara-Mahaica
+ - abbr: EB
+ name: East Berbice-Corentyne
+ - abbr: ES
+ name: Essequibo Islands-West Demerara
+ - abbr: MA
+ name: Mahaica-Berbice
+ - abbr: PM
+ name: Pomeroon-Supenaam
+ - abbr: PT
+ name: Potaro-Siparuni
+ - abbr: UD
+ name: Upper Demerara-Berbice
+ - abbr: UT
+ name: Upper Takutu-Upper Essequibo
+ - iso: HT
+ iso3: HTI
+ name: Haiti
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AR
+ name: Artibonite
+ - abbr: CE
+ name: Centre
+ - abbr: GA
+ name: Grande-Anse
+ - abbr: NI
+ name: Nippes
+ - abbr: ND
+ name: Nord
+ - abbr: NE
+ name: Nord-Est
+ - abbr: 'NO'
+ name: Nord-Ouest
+ - abbr: OU
+ name: Ouest
+ - abbr: SD
+ name: Sud
+ - abbr: SE
+ name: Sud-Est
+ - iso: VA
+ iso3: VAT
+ name: Holy See (Vatican City State)
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: HN
+ iso3: HND
+ name: Honduras
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AT
+ name: Atlántida
+ - abbr: CH
+ name: Choluteca
+ - abbr: CL
+ name: Colón
+ - abbr: CM
+ name: Comayagua
+ - abbr: CP
+ name: Copán
+ - abbr: CR
+ name: Cortés
+ - abbr: EP
+ name: El Paraíso
+ - abbr: FM
+ name: Francisco Morazán
+ - abbr: GD
+ name: Gracias a Dios
+ - abbr: IN
+ name: Intibucá
+ - abbr: IB
+ name: Islas de la Bahía
+ - abbr: LP
+ name: La Paz
+ - abbr: LE
+ name: Lempira
+ - abbr: OC
+ name: Ocotepeque
+ - abbr: OL
+ name: Olancho
+ - abbr: SB
+ name: Santa Bárbara
+ - abbr: VA
+ name: Valle
+ - abbr: YO
+ name: Yoro
+ - iso: HK
+ iso3: HKG
+ name: Hong Kong
+ states_required: true
+ zipcode_required: false
+ states: []
+ - iso: HU
+ iso3: HUN
+ name: Hungary
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BA
+ name: Baranya
+ - abbr: BZ
+ name: Borsod-Abaúj-Zemplén
+ - abbr: BU
+ name: Budapest
+ - abbr: BK
+ name: Bács-Kiskun
+ - abbr: BE
+ name: Békés
+ - abbr: BC
+ name: Békéscsaba
+ - abbr: CS
+ name: Csongrád
+ - abbr: DE
+ name: Debrecen
+ - abbr: DU
+ name: Dunaújváros
+ - abbr: EG
+ name: Eger
+ - abbr: FE
+ name: Fejér
+ - abbr: GY
+ name: Győr
+ - abbr: GS
+ name: Győr-Moson-Sopron
+ - abbr: HB
+ name: Hajdú-Bihar
+ - abbr: HE
+ name: Heves
+ - abbr: HV
+ name: Hódmezővásárhely
+ - abbr: JN
+ name: Jász-Nagykun-Szolnok
+ - abbr: KV
+ name: Kaposvár
+ - abbr: KM
+ name: Kecskemét
+ - abbr: KE
+ name: Komárom-Esztergom
+ - abbr: MI
+ name: Miskolc
+ - abbr: NK
+ name: Nagykanizsa
+ - abbr: NY
+ name: Nyíregyháza
+ - abbr: 'NO'
+ name: Nógrád
+ - abbr: PE
+ name: Pest
+ - abbr: PS
+ name: Pécs
+ - abbr: ST
+ name: Salgótarján
+ - abbr: SO
+ name: Somogy
+ - abbr: SN
+ name: Sopron
+ - abbr: SZ
+ name: Szabolcs-Szatmár-Bereg
+ - abbr: SD
+ name: Szeged
+ - abbr: SS
+ name: Szekszárd
+ - abbr: SK
+ name: Szolnok
+ - abbr: SH
+ name: Szombathely
+ - abbr: SF
+ name: Székesfehérvár
+ - abbr: TB
+ name: Tatabánya
+ - abbr: TO
+ name: Tolna
+ - abbr: VA
+ name: Vas
+ - abbr: VE
+ name: Veszprém
+ - abbr: VM
+ name: Veszprém
+ - abbr: ZA
+ name: Zala
+ - abbr: ZE
+ name: Zalaegerszeg
+ - abbr: ER
+ name: Érd
+ - iso: IS
+ iso3: ISL
+ name: Iceland
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AKH
+ name: Akrahreppur
+ - abbr: AKN
+ name: Akraneskaupstaður
+ - abbr: AKU
+ name: Akureyrarbær
+ - abbr: '7'
+ name: Austurland
+ - abbr: BLA
+ name: Bláskógabyggð
+ - abbr: BLO
+ name: Blönduósbær
+ - abbr: BOL
+ name: Bolungarvíkurkaupstaður
+ - abbr: BOG
+ name: Borgarbyggð
+ - abbr: DAB
+ name: Dalabyggð
+ - abbr: DAV
+ name: Dalvíkurbyggð
+ - abbr: EOM
+ name: Eyja- og Miklaholtshreppur
+ - abbr: EYF
+ name: Eyjafjarðarsveit
+ - abbr: FJL
+ name: Fjallabyggð
+ - abbr: FJD
+ name: Fjarðabyggð
+ - abbr: FLR
+ name: Fljótsdalshreppur
+ - abbr: FLA
+ name: Flóahreppur
+ - abbr: GAR
+ name: Garðabær
+ - abbr: GRN
+ name: Grindavíkurbær
+ - abbr: GRU
+ name: Grundarfjarðarbær
+ - abbr: GOG
+ name: Grímsnes- og Grafningshreppur
+ - abbr: GRY
+ name: Grýtubakkahreppur
+ - abbr: HAF
+ name: Hafnarfjarðarkaupstaður
+ - abbr: HEL
+ name: Helgafellssveit
+ - abbr: HRU
+ name: Hrunamannahreppur
+ - abbr: HVA
+ name: Hvalfjarðarsveit
+ - abbr: HVE
+ name: Hveragerðisbær
+ - abbr: '1'
+ name: Höfuðborgarsvæði utan Reykjavíkur
+ - abbr: HRG
+ name: Hörgársveit
+ - abbr: HUT
+ name: Húnavatnshreppur
+ - abbr: HUV
+ name: Húnaþing vestra
+ - abbr: KAL
+ name: Kaldrananeshreppur
+ - abbr: KJO
+ name: Kjósarhreppur
+ - abbr: KOP
+ name: Kópavogsbær
+ - abbr: LAN
+ name: Langanesbyggð
+ - abbr: MOS
+ name: Mosfellsbær
+ - abbr: MUL
+ name: Múlaþing
+ - abbr: MYR
+ name: Mýrdalshreppur
+ - abbr: '6'
+ name: Norðurland eystra
+ - abbr: '5'
+ name: Norðurland vestra
+ - abbr: NOR
+ name: Norðurþing
+ - abbr: RGE
+ name: Rangárþing eystra
+ - abbr: RGY
+ name: Rangárþing ytra
+ - abbr: RHH
+ name: Reykhólahreppur
+ - abbr: RKN
+ name: Reykjanesbær
+ - abbr: '0'
+ name: Reykjavík
+ - abbr: RKV
+ name: Reykjavíkurborg
+ - abbr: SEL
+ name: Seltjarnarnesbær
+ - abbr: SKF
+ name: Skaftárhreppur
+ - abbr: SKG
+ name: Skagabyggð
+ - abbr: SOG
+ name: Skeiða- og Gnúpverjahreppur
+ - abbr: SKO
+ name: Skorradalshreppur
+ - abbr: SKU
+ name: Skútustaðahreppur
+ - abbr: SNF
+ name: Snæfellsbær
+ - abbr: STR
+ name: Strandabyggð
+ - abbr: STY
+ name: Stykkishólmsbær
+ - abbr: '8'
+ name: Suðurland
+ - abbr: '2'
+ name: Suðurnes
+ - abbr: SDN
+ name: Suðurnesjabær
+ - abbr: SBH
+ name: Svalbarðshreppur
+ - abbr: SBT
+ name: Svalbarðsstrandarhreppur
+ - abbr: SHF
+ name: Sveitarfélagið Hornafjörður
+ - abbr: SSF
+ name: Sveitarfélagið Skagafjörður
+ - abbr: SSS
+ name: Sveitarfélagið Skagaströnd
+ - abbr: SVG
+ name: Sveitarfélagið Vogar
+ - abbr: SFA
+ name: Sveitarfélagið Árborg
+ - abbr: SOL
+ name: Sveitarfélagið Ölfus
+ - abbr: SDV
+ name: Súðavíkurhreppur
+ - abbr: TJO
+ name: Tjörneshreppur
+ - abbr: TAL
+ name: Tálknafjarðarhreppur
+ - abbr: '4'
+ name: Vestfirðir
+ - abbr: VEM
+ name: Vestmannaeyjabær
+ - abbr: VER
+ name: Vesturbyggð
+ - abbr: '3'
+ name: Vesturland
+ - abbr: VOP
+ name: Vopnafjarðarhreppur
+ - abbr: ARN
+ name: Árneshreppur
+ - abbr: ASA
+ name: Ásahreppur
+ - abbr: ISA
+ name: Ísafjarðarbær
+ - abbr: THG
+ name: Þingeyjarsveit
+ - iso: IN
+ iso3: IND
+ name: India
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AN
+ name: Andaman and Nicobar Islands
+ - abbr: AP
+ name: Andhra Pradesh
+ - abbr: AR
+ name: Arunachal Pradesh
+ - abbr: AS
+ name: Assam
+ - abbr: BR
+ name: Bihar
+ - abbr: CH
+ name: Chandigarh
+ - abbr: CG
+ name: Chhattisgarh
+ - abbr: DL
+ name: Delhi
+ - abbr: DH
+ name: Dādra and Nagar Haveli and Damān and Diu
+ - abbr: GA
+ name: Goa
+ - abbr: GJ
+ name: Gujarat
+ - abbr: HR
+ name: Haryana
+ - abbr: HP
+ name: Himachal Pradesh
+ - abbr: JK
+ name: Jammu and Kashmir
+ - abbr: JH
+ name: Jharkhand
+ - abbr: KA
+ name: Karnataka
+ - abbr: KL
+ name: Kerala
+ - abbr: LA
+ name: Ladakh
+ - abbr: LD
+ name: Lakshadweep
+ - abbr: MP
+ name: Madhya Pradesh
+ - abbr: MH
+ name: Maharashtra
+ - abbr: MN
+ name: Manipur
+ - abbr: ML
+ name: Meghalaya
+ - abbr: MZ
+ name: Mizoram
+ - abbr: NL
+ name: Nagaland
+ - abbr: OD
+ name: Odisha
+ - abbr: PY
+ name: Pondicherry
+ - abbr: PB
+ name: Punjab
+ - abbr: RJ
+ name: Rajasthan
+ - abbr: SK
+ name: Sikkim
+ - abbr: TN
+ name: Tamil Nadu
+ - abbr: TR
+ name: Tripura
+ - abbr: UP
+ name: Uttar Pradesh
+ - abbr: WB
+ name: West Bengal
+ - abbr: UK
+ name: उत्तराखण्ड
+ - abbr: TS
+ name: तेलंगाना
+ - iso: ID
+ iso3: IDN
+ name: Indonesia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AC
+ name: Aceh
+ - abbr: BA
+ name: Bali
+ - abbr: BT
+ name: Banten
+ - abbr: BE
+ name: Bengkulu
+ - abbr: JK
+ name: Daerah Khusus Ibukota Jakarta
+ - abbr: GO
+ name: Gorontalo
+ - abbr: JA
+ name: Jambi
+ - abbr: JW
+ name: Jawa
+ - abbr: JB
+ name: Jawa Barat
+ - abbr: JT
+ name: Jawa Tengah
+ - abbr: JI
+ name: Jawa Timur
+ - abbr: KA
+ name: Kalimantan
+ - abbr: KB
+ name: Kalimantan Barat
+ - abbr: KS
+ name: Kalimantan Selatan
+ - abbr: KT
+ name: Kalimantan Tengah
+ - abbr: KI
+ name: Kalimantan Timur
+ - abbr: KU
+ name: Kalimantan Utara
+ - abbr: BB
+ name: Kepulauan Bangka Belitung
+ - abbr: ML
+ name: Kepulauan Maluku
+ - abbr: NU
+ name: Kepulauan Nusa Tenggara
+ - abbr: KR
+ name: Kepulauan Riau
+ - abbr: LA
+ name: Lampung
+ - abbr: MA
+ name: Maluku
+ - abbr: MU
+ name: Maluku Utara
+ - abbr: NB
+ name: Nusa Tenggara Barat
+ - abbr: NT
+ name: Nusa Tenggara Timur
+ - abbr: PA
+ name: Papua
+ - abbr: PB
+ name: Papua Barat
+ - abbr: PP
+ name: Papua bagian barat
+ - abbr: RI
+ name: Riau
+ - abbr: SL
+ name: Sulawesi
+ - abbr: SR
+ name: Sulawesi Barat
+ - abbr: SN
+ name: Sulawesi Selatan
+ - abbr: ST
+ name: Sulawesi Tengah
+ - abbr: SG
+ name: Sulawesi Tenggara
+ - abbr: SA
+ name: Sulawesi Utara
+ - abbr: SM
+ name: Sumatera
+ - abbr: SB
+ name: Sumatera Barat
+ - abbr: SS
+ name: Sumatera Selatan
+ - abbr: SU
+ name: Sumatera Utara
+ - abbr: YO
+ name: Yogyakarta
+ - iso: IR
+ iso3: IRN
+ name: Iran
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '24'
+ name: Ardabil
+ - abbr: '04'
+ name: Az¯arbayjan-e Gharbi
+ - abbr: '03'
+ name: Az¯arbayjan-e Sharqi
+ - abbr: '18'
+ name: Bushehr
+ - abbr: '14'
+ name: Chahar Mah¸all va Bakhtiari
+ - abbr: '10'
+ name: Esfahan
+ - abbr: '07'
+ name: Fars
+ - abbr: '01'
+ name: Gilan
+ - abbr: '27'
+ name: Golestan
+ - abbr: '13'
+ name: Hamadan
+ - abbr: '22'
+ name: Hormozgan
+ - abbr: '16'
+ name: Ilam
+ - abbr: '08'
+ name: Kerman
+ - abbr: '05'
+ name: Kermanshah
+ - abbr: '29'
+ name: Khorasan-e Janubi
+ - abbr: '09'
+ name: Khorasan-e Razavi
+ - abbr: '28'
+ name: Khorasan-e Shemali
+ - abbr: '06'
+ name: Khuzestan
+ - abbr: '17'
+ name: Kohkiluyeh va Buyer Ahmad
+ - abbr: '12'
+ name: Kordestan
+ - abbr: '15'
+ name: Lorestan
+ - abbr: '00'
+ name: Markazi
+ - abbr: '02'
+ name: Mazandaran
+ - abbr: '26'
+ name: Qazvin
+ - abbr: '25'
+ name: Qom
+ - abbr: '20'
+ name: Semnan
+ - abbr: '11'
+ name: Sistan va Baluchestan
+ - abbr: '23'
+ name: Tehran
+ - abbr: '21'
+ name: Yazd
+ - abbr: '19'
+ name: Zanjan
+ - abbr: '30'
+ name: استان البرز
+ - iso: IQ
+ iso3: IRQ
+ name: Iraq
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AN
+ name: Al Anbar
+ - abbr: BA
+ name: Al Basrah
+ - abbr: MU
+ name: Al Muthanná
+ - abbr: QA
+ name: Al Qadisiyah
+ - abbr: NA
+ name: An Najaf
+ - abbr: AR
+ name: Arbil
+ - abbr: SU
+ name: As Sulaymaniyah
+ - abbr: BB
+ name: Babil
+ - abbr: BG
+ name: Baghdad
+ - abbr: DA
+ name: Dahuk
+ - abbr: DQ
+ name: Dhi Qar
+ - abbr: DI
+ name: Diyalá
+ - abbr: KA
+ name: Karbala'
+ - abbr: MA
+ name: Maysan
+ - abbr: NI
+ name: Ninawá
+ - abbr: SD
+ name: Salah ad Din
+ - abbr: WA
+ name: Wasit
+ - abbr: KR
+ name: إقليم كردستان
+ - abbr: KI
+ name: كركوك
+ - iso: IE
+ iso3: IRL
+ name: Ireland
+ states_required: true
+ zipcode_required: false
+ states:
+ - abbr: CW
+ name: Carlow
+ - abbr: CN
+ name: Cavan
+ - abbr: CE
+ name: Clare
+ - abbr: C
+ name: Connacht
+ - abbr: CO
+ name: Cork
+ - abbr: DL
+ name: Donegal
+ - abbr: D
+ name: Dublin
+ - abbr: G
+ name: Galway
+ - abbr: KY
+ name: Kerry
+ - abbr: KE
+ name: Kildare
+ - abbr: KK
+ name: Kilkenny
+ - abbr: LS
+ name: Laois
+ - abbr: L
+ name: Leinster
+ - abbr: LM
+ name: Leitrim
+ - abbr: LK
+ name: Limerick
+ - abbr: LD
+ name: Longford
+ - abbr: LH
+ name: Louth
+ - abbr: MO
+ name: Mayo
+ - abbr: MH
+ name: Meath
+ - abbr: MN
+ name: Monaghan
+ - abbr: M
+ name: Munster
+ - abbr: OY
+ name: Offaly
+ - abbr: RN
+ name: Roscommon
+ - abbr: SO
+ name: Sligo
+ - abbr: TA
+ name: Tipperary
+ - abbr: U
+ name: Ulster
+ - abbr: WD
+ name: Waterford
+ - abbr: WH
+ name: Westmeath
+ - abbr: WX
+ name: Wexford
+ - abbr: WW
+ name: Wicklow
+ - iso: IM
+ iso3: IMN
+ name: Isle of Man
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: IL
+ iso3: ISR
+ name: Israel
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: D
+ name: HaDarom
+ - abbr: M
+ name: HaMerkaz
+ - abbr: Z
+ name: HaZafon
+ - abbr: HA
+ name: Haifa
+ - abbr: TA
+ name: Tel-Aviv
+ - abbr: JM
+ name: Yerushalayim
+ - iso: IT
+ iso3: ITA
+ name: Italy
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: '65'
+ name: Abruzzo
+ - abbr: AG
+ name: Agrigento
+ - abbr: AL
+ name: Alessandria
+ - abbr: AN
+ name: Ancona
+ - abbr: AR
+ name: Arezzo
+ - abbr: AP
+ name: Ascoli Piceno
+ - abbr: AT
+ name: Asti
+ - abbr: AV
+ name: Avellino
+ - abbr: BA
+ name: Bari
+ - abbr: BT
+ name: Barletta-Andria-Trani
+ - abbr: '77'
+ name: Basilicata
+ - abbr: BL
+ name: Belluno
+ - abbr: BN
+ name: Benevento
+ - abbr: BG
+ name: Bergamo
+ - abbr: BI
+ name: Biella
+ - abbr: BO
+ name: Bologna
+ - abbr: BZ
+ name: Bolzano
+ - abbr: BS
+ name: Brescia
+ - abbr: BR
+ name: Brindisi
+ - abbr: CA
+ name: Cagliari
+ - abbr: '78'
+ name: Calabria
+ - abbr: CL
+ name: Caltanissetta
+ - abbr: '72'
+ name: Campania
+ - abbr: CB
+ name: Campobasso
+ - abbr: CI
+ name: Carbonia-Iglesias
+ - abbr: CE
+ name: Caserta
+ - abbr: CT
+ name: Catania
+ - abbr: CZ
+ name: Catanzaro
+ - abbr: CH
+ name: Chieti
+ - abbr: CO
+ name: Como
+ - abbr: CS
+ name: Cosenza
+ - abbr: CR
+ name: Cremona
+ - abbr: KR
+ name: Crotone
+ - abbr: CN
+ name: Cuneo
+ - abbr: '45'
+ name: Emilia-Romagna
+ - abbr: EN
+ name: Enna
+ - abbr: FM
+ name: Fermo
+ - abbr: FE
+ name: Ferrara
+ - abbr: FI
+ name: Firenze
+ - abbr: FG
+ name: Foggia
+ - abbr: FC
+ name: Forlì-Cesena
+ - abbr: '36'
+ name: Friuli Venezia Giulia
+ - abbr: FR
+ name: Frosinone
+ - abbr: GE
+ name: Genova
+ - abbr: GO
+ name: Gorizia
+ - abbr: GR
+ name: Grosseto
+ - abbr: IM
+ name: Imperia
+ - abbr: IS
+ name: Isernia
+ - abbr: AQ
+ name: L'Aquila
+ - abbr: SP
+ name: La Spezia
+ - abbr: LT
+ name: Latina
+ - abbr: '62'
+ name: Lazio
+ - abbr: LE
+ name: Lecce
+ - abbr: LC
+ name: Lecco
+ - abbr: '42'
+ name: Liguria
+ - abbr: LI
+ name: Livorno
+ - abbr: LO
+ name: Lodi
+ - abbr: '25'
+ name: Lombardia
+ - abbr: LU
+ name: Lucca
+ - abbr: MC
+ name: Macerata
+ - abbr: MN
+ name: Mantova
+ - abbr: '57'
+ name: Marche
+ - abbr: MS
+ name: Massa-Carrara
+ - abbr: MT
+ name: Matera
+ - abbr: VS
+ name: Medio Campidano
+ - abbr: ME
+ name: Messina
+ - abbr: MI
+ name: Milano
+ - abbr: MO
+ name: Modena
+ - abbr: '67'
+ name: Molise
+ - abbr: MB
+ name: Monza e Brianza
+ - abbr: NA
+ name: Napoli
+ - abbr: 'NO'
+ name: Novara
+ - abbr: NU
+ name: Nuoro
+ - abbr: OG
+ name: Ogliastra
+ - abbr: OT
+ name: Olbia-Tempio
+ - abbr: OR
+ name: Oristano
+ - abbr: PD
+ name: Padova
+ - abbr: PA
+ name: Palermo
+ - abbr: PR
+ name: Parma
+ - abbr: PV
+ name: Pavia
+ - abbr: PG
+ name: Perugia
+ - abbr: PU
+ name: Pesaro e Urbino
+ - abbr: PE
+ name: Pescara
+ - abbr: PC
+ name: Piacenza
+ - abbr: '21'
+ name: Piemonte
+ - abbr: PI
+ name: Pisa
+ - abbr: PT
+ name: Pistoia
+ - abbr: PN
+ name: Pordenone
+ - abbr: PZ
+ name: Potenza
+ - abbr: PO
+ name: Prato
+ - abbr: '75'
+ name: Puglia
+ - abbr: RG
+ name: Ragusa
+ - abbr: RA
+ name: Ravenna
+ - abbr: RC
+ name: Reggio Calabria
+ - abbr: RE
+ name: Reggio Emilia
+ - abbr: RI
+ name: Rieti
+ - abbr: RN
+ name: Rimini
+ - abbr: RM
+ name: Roma
+ - abbr: RO
+ name: Rovigo
+ - abbr: SA
+ name: Salerno
+ - abbr: '88'
+ name: Sardegna
+ - abbr: SS
+ name: Sassari
+ - abbr: SV
+ name: Savona
+ - abbr: '82'
+ name: Sicilia
+ - abbr: SI
+ name: Siena
+ - abbr: SR
+ name: Siracusa
+ - abbr: SO
+ name: Sondrio
+ - abbr: SU
+ name: Sud Sardegna
+ - abbr: TA
+ name: Taranto
+ - abbr: TE
+ name: Teramo
+ - abbr: TR
+ name: Terni
+ - abbr: TO
+ name: Torino
+ - abbr: '52'
+ name: Toscana
+ - abbr: TP
+ name: Trapani
+ - abbr: '32'
+ name: Trentino-Alto Adige
+ - abbr: TN
+ name: Trento
+ - abbr: TV
+ name: Treviso
+ - abbr: TS
+ name: Trieste
+ - abbr: UD
+ name: Udine
+ - abbr: '55'
+ name: Umbria
+ - abbr: '23'
+ name: Valle d'Aosta
+ - abbr: VA
+ name: Varese
+ - abbr: '34'
+ name: Veneto
+ - abbr: VE
+ name: Venezia
+ - abbr: VB
+ name: Verbano-Cusio-Ossola
+ - abbr: VC
+ name: Vercelli
+ - abbr: VR
+ name: Verona
+ - abbr: VV
+ name: Vibo Valentia
+ - abbr: VI
+ name: Vicenza
+ - abbr: VT
+ name: Viterbo
+ - iso: JM
+ iso3: JAM
+ name: Jamaica
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '13'
+ name: Clarendon
+ - abbr: '09'
+ name: Hanover
+ - abbr: '01'
+ name: Kingston
+ - abbr: '12'
+ name: Manchester
+ - abbr: '04'
+ name: Portland
+ - abbr: '02'
+ name: Saint Andrew
+ - abbr: '06'
+ name: Saint Ann
+ - abbr: '14'
+ name: Saint Catherine
+ - abbr: '11'
+ name: Saint Elizabeth
+ - abbr: '08'
+ name: Saint James
+ - abbr: '05'
+ name: Saint Mary
+ - abbr: '03'
+ name: Saint Thomas
+ - abbr: '07'
+ name: Trelawny
+ - abbr: '10'
+ name: Westmoreland
+ - iso: JP
+ iso3: JPN
+ name: Japan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '23'
+ name: Aichi
+ - abbr: '05'
+ name: Akita
+ - abbr: '02'
+ name: Aomori
+ - abbr: '12'
+ name: Chiba
+ - abbr: '38'
+ name: Ehime
+ - abbr: '18'
+ name: Fukui
+ - abbr: '40'
+ name: Fukuoka
+ - abbr: '07'
+ name: Fukushima
+ - abbr: '21'
+ name: Gifu
+ - abbr: '10'
+ name: Gunma
+ - abbr: '34'
+ name: Hiroshima
+ - abbr: '01'
+ name: Hokkaido
+ - abbr: '28'
+ name: Hyogo
+ - abbr: '08'
+ name: Ibaraki
+ - abbr: '17'
+ name: Ishikawa
+ - abbr: '03'
+ name: Iwate
+ - abbr: '37'
+ name: Kagawa
+ - abbr: '46'
+ name: Kagoshima
+ - abbr: '14'
+ name: Kanagawa
+ - abbr: '39'
+ name: Kochi
+ - abbr: '43'
+ name: Kumamoto
+ - abbr: '26'
+ name: Kyoto
+ - abbr: '24'
+ name: Mie
+ - abbr: '04'
+ name: Miyagi
+ - abbr: '45'
+ name: Miyazaki
+ - abbr: '20'
+ name: Nagano
+ - abbr: '42'
+ name: Nagasaki
+ - abbr: '29'
+ name: Nara
+ - abbr: '15'
+ name: Niigata
+ - abbr: '44'
+ name: Oita
+ - abbr: '33'
+ name: Okayama
+ - abbr: '47'
+ name: Okinawa
+ - abbr: '27'
+ name: Osaka
+ - abbr: '41'
+ name: Saga
+ - abbr: '11'
+ name: Saitama
+ - abbr: '25'
+ name: Shiga
+ - abbr: '32'
+ name: Shimane
+ - abbr: '22'
+ name: Shizuoka
+ - abbr: '09'
+ name: Tochigi
+ - abbr: '36'
+ name: Tokushima
+ - abbr: '13'
+ name: Tokyo
+ - abbr: '31'
+ name: Tottori
+ - abbr: '16'
+ name: Toyama
+ - abbr: '30'
+ name: Wakayama
+ - abbr: '06'
+ name: Yamagata
+ - abbr: '35'
+ name: Yamaguchi
+ - abbr: '19'
+ name: Yamanashi
+ - iso: JE
+ iso3: JEY
+ name: Jersey
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: JO
+ iso3: JOR
+ name: Jordan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AJ
+ name: Ajlun
+ - abbr: BA
+ name: Al Balqa'
+ - abbr: KA
+ name: Al Karak
+ - abbr: MA
+ name: Al Mafraq
+ - abbr: AM
+ name: Amman
+ - abbr: AQ
+ name: Aqaba
+ - abbr: AT
+ name: At Tafilah
+ - abbr: AZ
+ name: Az Zarqa'
+ - abbr: IR
+ name: Irbid
+ - abbr: JA
+ name: Jarash
+ - abbr: MN
+ name: Ma`an
+ - abbr: MD
+ name: Madaba
+ - iso: KZ
+ iso3: KAZ
+ name: Kazakhstan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: ALA
+ name: Almaty
+ - abbr: ALM
+ name: Almaty oblysy
+ - abbr: AKM
+ name: Aqmola oblysy
+ - abbr: AKT
+ name: Aqtöbe oblysy
+ - abbr: AST
+ name: Astana
+ - abbr: ATY
+ name: Atyrau oblysy
+ - abbr: ZAP
+ name: Batys Qazaqstan oblysy
+ - abbr: MAN
+ name: Mangghystau oblysy
+ - abbr: YUZ
+ name: Ongtüstik Qazaqstan oblysy
+ - abbr: PAV
+ name: Pavlodar oblysy
+ - abbr: KAR
+ name: Qaraghandy oblysy
+ - abbr: KUS
+ name: Qostanay oblysy
+ - abbr: KZY
+ name: Qyzylorda oblysy
+ - abbr: VOS
+ name: Shyghys Qazaqstan oblysy
+ - abbr: SHY
+ name: Shymkent
+ - abbr: SEV
+ name: Soltüstik Qazaqstan oblysy
+ - abbr: ZHA
+ name: Zhambyl oblysy
+ - iso: KE
+ iso3: KEN
+ name: Kenya
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Baringo
+ - abbr: '02'
+ name: Bomet
+ - abbr: '03'
+ name: Bungoma
+ - abbr: '04'
+ name: Busia
+ - abbr: '05'
+ name: Elgeyo/Marakwet
+ - abbr: '06'
+ name: Embu
+ - abbr: '07'
+ name: Garissa
+ - abbr: '08'
+ name: Homa Bay
+ - abbr: '09'
+ name: Isiolo
+ - abbr: '10'
+ name: Kajiado
+ - abbr: '11'
+ name: Kakamega
+ - abbr: '12'
+ name: Kericho
+ - abbr: '13'
+ name: Kiambu
+ - abbr: '14'
+ name: Kilifi
+ - abbr: '15'
+ name: Kirinyaga
+ - abbr: '16'
+ name: Kisii
+ - abbr: '17'
+ name: Kisumu
+ - abbr: '18'
+ name: Kitui
+ - abbr: '19'
+ name: Kwale
+ - abbr: '20'
+ name: Laikipia
+ - abbr: '21'
+ name: Lamu
+ - abbr: '22'
+ name: Machakos
+ - abbr: '23'
+ name: Makueni
+ - abbr: '24'
+ name: Mandera
+ - abbr: '25'
+ name: Marsabit
+ - abbr: '26'
+ name: Meru
+ - abbr: '27'
+ name: Migori
+ - abbr: '28'
+ name: Mombasa
+ - abbr: '29'
+ name: Murang’a
+ - abbr: '30'
+ name: Nairobi City
+ - abbr: '31'
+ name: Nakuru
+ - abbr: '32'
+ name: Nandi
+ - abbr: '33'
+ name: Narok
+ - abbr: '34'
+ name: Nyamira
+ - abbr: '35'
+ name: Nyandarua
+ - abbr: '36'
+ name: Nyeri
+ - abbr: '37'
+ name: Samburu
+ - abbr: '38'
+ name: Siaya
+ - abbr: '39'
+ name: Taita-Taveta
+ - abbr: '40'
+ name: Tana River
+ - abbr: '41'
+ name: Tharaka-Nithi
+ - abbr: '42'
+ name: Trans-Nzoia
+ - abbr: '43'
+ name: Turkana
+ - abbr: '44'
+ name: Uasin Gishu
+ - abbr: '45'
+ name: Vihiga
+ - abbr: '46'
+ name: Wajir
+ - abbr: '47'
+ name: West Pokot
+ - iso: KI
+ iso3: KIR
+ name: Kiribati
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: G
+ name: Gilbert Islands
+ - abbr: L
+ name: Line Islands
+ - abbr: P
+ name: Phoenix Islands
+ - iso: KW
+ iso3: KWT
+ name: Kuwait
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AH
+ name: Al Ahmadi
+ - abbr: FA
+ name: Al Farwaniyah
+ - abbr: JA
+ name: Al Jahrah
+ - abbr: KU
+ name: Al Kuwayt
+ - abbr: HA
+ name: Hawalli
+ - abbr: MU
+ name: Mubarak al-Kabir
+ - iso: KG
+ iso3: KGZ
+ name: Kyrgyzstan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: B
+ name: Batken
+ - abbr: GB
+ name: Bishkek
+ - abbr: C
+ name: Chü
+ - abbr: J
+ name: Jalal-Abad
+ - abbr: "N"
+ name: Naryn
+ - abbr: O
+ name: Osh
+ - abbr: T
+ name: Talas
+ - abbr: "Y"
+ name: Ysyk-Köl
+ - abbr: GO
+ name: Ош
+ - iso: LA
+ iso3: LAO
+ name: Lao People's Democratic Republic
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AT
+ name: Attapu [Attopeu]
+ - abbr: BK
+ name: Bokèo
+ - abbr: BL
+ name: Bolikhamxai [Borikhane]
+ - abbr: CH
+ name: Champasak [Champassak]
+ - abbr: HO
+ name: Houaphan
+ - abbr: KH
+ name: Khammouan
+ - abbr: LM
+ name: Louang Namtha
+ - abbr: LP
+ name: Louangphabang [Louang Prabang]
+ - abbr: OU
+ name: Oudômxai [Oudomsai]
+ - abbr: PH
+ name: Phôngsali [Phong Saly]
+ - abbr: SL
+ name: Salavan [Saravane]
+ - abbr: SV
+ name: Savannakhét
+ - abbr: VI
+ name: Vientiane
+ - abbr: VT
+ name: Vientiane Prefecture
+ - abbr: XA
+ name: Xaignabouli [Sayaboury]
+ - abbr: XI
+ name: Xiangkhoang [Xieng Khouang]
+ - abbr: XE
+ name: Xékong [Sékong]
+ - abbr: XS
+ name: ແຂວງໄຊສົມບູນ
+ - iso: LV
+ iso3: LVA
+ name: Latvia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '002'
+ name: Aizkraukles novads
+ - abbr: '007'
+ name: Alūksnes novads
+ - abbr: '111'
+ name: Augšdaugavas novads
+ - abbr: '015'
+ name: Balvu novads
+ - abbr: '016'
+ name: Bauskas novads
+ - abbr: '022'
+ name: Cēsu novads
+ - abbr: DGV
+ name: Daugavpils
+ - abbr: '112'
+ name: Dienvidkurzemes Novads
+ - abbr: '026'
+ name: Dobeles novads
+ - abbr: '033'
+ name: Gulbenes novads
+ - abbr: JEL
+ name: Jelgava
+ - abbr: '041'
+ name: Jelgavas novads
+ - abbr: JUR
+ name: Jurmala
+ - abbr: '042'
+ name: Jēkabpils novads
+ - abbr: '047'
+ name: Krāslavas novads
+ - abbr: '050'
+ name: Kuldīgas novads
+ - abbr: LPX
+ name: Liepaja
+ - abbr: '054'
+ name: Limbažu novads
+ - abbr: '058'
+ name: Ludzas novads
+ - abbr: '056'
+ name: Līvānu novads
+ - abbr: '059'
+ name: Madonas novads
+ - abbr: '062'
+ name: Mārupes novads
+ - abbr: '067'
+ name: Ogres novads
+ - abbr: '068'
+ name: Olaines novads
+ - abbr: '073'
+ name: Preiļu novads
+ - abbr: REZ
+ name: Rezekne
+ - abbr: RIX
+ name: Riga
+ - abbr: '080'
+ name: Ropažu novads
+ - abbr: '077'
+ name: Rēzeknes novads
+ - abbr: '087'
+ name: Salaspils novads
+ - abbr: '088'
+ name: Saldus novads
+ - abbr: '089'
+ name: Saulkrastu novads
+ - abbr: '091'
+ name: Siguldas novads
+ - abbr: '094'
+ name: Smiltenes novads
+ - abbr: '097'
+ name: Talsu novads
+ - abbr: '099'
+ name: Tukuma novads
+ - abbr: '101'
+ name: Valkas novads
+ - abbr: '113'
+ name: Valmieras Novads
+ - abbr: '102'
+ name: Varakļānu novads
+ - abbr: VEN
+ name: Ventspils
+ - abbr: '106'
+ name: Ventspils novads
+ - abbr: '011'
+ name: Ādažu novads
+ - abbr: '052'
+ name: Ķekavas novads
+ - iso: LB
+ iso3: LBN
+ name: Lebanon
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BA
+ name: Beirut
+ - abbr: BI
+ name: El Béqaa
+ - abbr: JL
+ name: Jabal Loubnâne
+ - abbr: AS
+ name: Loubnâne ech Chemâli
+ - abbr: JA
+ name: Loubnâne ej Jnoûbi
+ - abbr: NA
+ name: Nabatîyé
+ - abbr: BH
+ name: محافظة بعلبك الهرمل
+ - abbr: AK
+ name: محافظة عكار
+ - iso: LS
+ iso3: LSO
+ name: Lesotho
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: D
+ name: Berea
+ - abbr: B
+ name: Butha-Buthe
+ - abbr: C
+ name: Leribe
+ - abbr: E
+ name: Mafeteng
+ - abbr: A
+ name: Maseru
+ - abbr: F
+ name: Mohale's Hoek
+ - abbr: J
+ name: Mokhotlong
+ - abbr: H
+ name: Qacha's Nek
+ - abbr: G
+ name: Quthing
+ - abbr: K
+ name: Thaba-Tseka
+ - iso: LR
+ iso3: LBR
+ name: Liberia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BM
+ name: Bomi
+ - abbr: BG
+ name: Bong
+ - abbr: X1~
+ name: Gbarpolu
+ - abbr: GP
+ name: Gbarpolu
+ - abbr: GB
+ name: Grand Bassa
+ - abbr: CM
+ name: Grand Cape Mount
+ - abbr: GG
+ name: Grand Gedeh
+ - abbr: GK
+ name: Grand Kru
+ - abbr: LO
+ name: Lofa
+ - abbr: MG
+ name: Margibi
+ - abbr: MY
+ name: Maryland
+ - abbr: MO
+ name: Montserrado
+ - abbr: NI
+ name: Nimba
+ - abbr: RG
+ name: River Gee
+ - abbr: X2~
+ name: River Gee
+ - abbr: RI
+ name: Rivercess
+ - abbr: SI
+ name: Sinoe
+ - iso: LY
+ iso3: LBY
+ name: Libya
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BU
+ name: Al Butnan
+ - abbr: JA
+ name: Al Jabal al Akhḑar
+ - abbr: JG
+ name: Al Jabal al Gharbī
+ - abbr: JI
+ name: Al Jifarah
+ - abbr: JU
+ name: Al Jufrah
+ - abbr: KF
+ name: Al Kufrah
+ - abbr: MJ
+ name: Al Marj
+ - abbr: MB
+ name: Al Murqub
+ - abbr: WA
+ name: Al Wahat
+ - abbr: NQ
+ name: An Nuqaţ al Khams
+ - abbr: ZA
+ name: Az Zawiyah
+ - abbr: BA
+ name: Banghazi
+ - abbr: DR
+ name: Darnah
+ - abbr: GT
+ name: Ghat
+ - abbr: MI
+ name: Mişrātah
+ - abbr: MQ
+ name: Murzuq
+ - abbr: NL
+ name: Nālūt
+ - abbr: SB
+ name: Sabhā
+ - abbr: SR
+ name: Sirte
+ - abbr: TB
+ name: Tarabulus
+ - abbr: WD
+ name: Wādī al Ḩayāt
+ - abbr: WS
+ name: Wādī ash Shāţiʾ
+ - iso: LI
+ iso3: LIE
+ name: Liechtenstein
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Balzers
+ - abbr: '02'
+ name: Eschen
+ - abbr: '03'
+ name: Gamprin
+ - abbr: '04'
+ name: Mauren
+ - abbr: '05'
+ name: Planken
+ - abbr: '06'
+ name: Ruggell
+ - abbr: '07'
+ name: Schaan
+ - abbr: '08'
+ name: Schellenberg
+ - abbr: '09'
+ name: Triesen
+ - abbr: '10'
+ name: Triesenberg
+ - abbr: '11'
+ name: Vaduz
+ - iso: LT
+ iso3: LTU
+ name: Lithuania
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Akmenės rajono savivaldybė
+ - abbr: AL
+ name: Alytaus Apskritis
+ - abbr: '02'
+ name: Alytaus miesto savivaldybė
+ - abbr: '03'
+ name: Alytaus rajono savivaldybė
+ - abbr: '04'
+ name: Anykščių rajono savivaldybė
+ - abbr: '05'
+ name: Birštono savivaldybė
+ - abbr: '06'
+ name: Biržų rajono savivaldybė
+ - abbr: '07'
+ name: Druskininkų savivaldybė
+ - abbr: '08'
+ name: Elektrėnų savivaldybė
+ - abbr: '09'
+ name: Ignalinos rajono savivaldybė
+ - abbr: '10'
+ name: Jonavos rajono savivaldybė
+ - abbr: '11'
+ name: Joniškio rajono savivaldybė
+ - abbr: '12'
+ name: Jurbarko rajono savivaldybė
+ - abbr: '13'
+ name: Kaišiadorių rajono savivaldybė
+ - abbr: '14'
+ name: Kalvarijos savivaldybė
+ - abbr: KU
+ name: Kauno Apskritis
+ - abbr: '15'
+ name: Kauno miesto savivaldybė
+ - abbr: '16'
+ name: Kauno rajono savivaldybė
+ - abbr: '17'
+ name: Kazlų Rūdos savivaldybė
+ - abbr: '19'
+ name: Kelmės rajono savivaldybė
+ - abbr: KL
+ name: Klaipedos Apskritis
+ - abbr: '20'
+ name: Klaipėdos miesto savivaldybė
+ - abbr: '21'
+ name: Klaipėdos rajono savivaldybė
+ - abbr: '22'
+ name: Kretingos rajono savivaldybė
+ - abbr: '23'
+ name: Kupiškio rajono savivaldybė
+ - abbr: '18'
+ name: Kėdainių rajono savivaldybė
+ - abbr: '24'
+ name: Lazdijų rajono savivaldybė
+ - abbr: MR
+ name: Marijampoles Apskritis
+ - abbr: '25'
+ name: Marijampolės savivaldybė
+ - abbr: '26'
+ name: Mažeikių rajono savivaldybė
+ - abbr: '27'
+ name: Molėtų rajono savivaldybė
+ - abbr: '28'
+ name: Neringos savivaldybė
+ - abbr: '29'
+ name: Pagėgių savivaldybė
+ - abbr: '30'
+ name: Pakruojo rajono savivaldybė
+ - abbr: '31'
+ name: Palangos miesto savivaldybė
+ - abbr: PN
+ name: Panevežio Apskritis
+ - abbr: '32'
+ name: Panevėžio miesto savivaldybė
+ - abbr: '33'
+ name: Panevėžio rajono savivaldybė
+ - abbr: '34'
+ name: Pasvalio rajono savivaldybė
+ - abbr: '35'
+ name: Plungės rajono savivaldybė
+ - abbr: '36'
+ name: Prienų rajono savivaldybė
+ - abbr: '37'
+ name: Radviliškio rajono savivaldybė
+ - abbr: '38'
+ name: Raseinių rajono savivaldybė
+ - abbr: '39'
+ name: Rietavo savivaldybė
+ - abbr: '40'
+ name: Rokiškio rajono savivaldybė
+ - abbr: '48'
+ name: Skuodo rajono savivaldybė
+ - abbr: TA
+ name: Taurages Apskritis
+ - abbr: '50'
+ name: Tauragės rajono savivaldybė
+ - abbr: TE
+ name: Telšiu Apskritis
+ - abbr: '51'
+ name: Telšių rajono savivaldybė
+ - abbr: '52'
+ name: Trakų rajono savivaldybė
+ - abbr: '53'
+ name: Ukmergės rajono savivaldybė
+ - abbr: UT
+ name: Utenos Apskritis
+ - abbr: '54'
+ name: Utenos rajono savivaldybė
+ - abbr: '55'
+ name: Varėnos rajono savivaldybė
+ - abbr: '56'
+ name: Vilkaviškio rajono savivaldybė
+ - abbr: VL
+ name: Vilniaus Apskritis
+ - abbr: '57'
+ name: Vilniaus miesto savivaldybė
+ - abbr: '58'
+ name: Vilniaus rajono savivaldybė
+ - abbr: '59'
+ name: Visagino savivaldybė
+ - abbr: '60'
+ name: Zarasų rajono savivaldybė
+ - abbr: '41'
+ name: Šakių rajono savivaldybė
+ - abbr: '42'
+ name: Šalčininkų rajono savivaldybė
+ - abbr: SA
+ name: Šiauliu Apskritis
+ - abbr: '43'
+ name: Šiaulių miesto savivaldybė
+ - abbr: '44'
+ name: Šiaulių rajono savivaldybė
+ - abbr: '45'
+ name: Šilalės rajono savivaldybė
+ - abbr: '46'
+ name: Šilutės rajono savivaldybė
+ - abbr: '47'
+ name: Širvintų rajono savivaldybė
+ - abbr: '49'
+ name: Švenčionių rajono savivaldybė
+ - iso: LU
+ iso3: LUX
+ name: Luxembourg
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: DI
+ name: Diekrech
+ - abbr: ES
+ name: Esch-Uelzecht
+ - abbr: GR
+ name: Gréivemaacher
+ - abbr: EC
+ name: Iechternach
+ - abbr: CA
+ name: Kapellen
+ - abbr: CL
+ name: Klierf
+ - abbr: LU
+ name: Lëtzebuerg
+ - abbr: ME
+ name: Miersch
+ - abbr: RD
+ name: Réiden-Atert
+ - abbr: RM
+ name: Réimech
+ - abbr: VD
+ name: Veianen
+ - abbr: WI
+ name: Wolz
+ - iso: MO
+ iso3: MAC
+ name: Macao
+ states_required: false
+ zipcode_required: false
+ states: []
+ - iso: MG
+ iso3: MDG
+ name: Madagascar
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: T
+ name: Antananarivo
+ - abbr: D
+ name: Antsiranana
+ - abbr: F
+ name: Fianarantsoa
+ - abbr: M
+ name: Mahajanga
+ - abbr: A
+ name: Toamasina
+ - abbr: U
+ name: Toliara
+ - iso: MW
+ iso3: MWI
+ name: Malawi
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BA
+ name: Balaka
+ - abbr: BL
+ name: Blantyre
+ - abbr: C
+ name: Central
+ - abbr: CK
+ name: Chikwawa
+ - abbr: CR
+ name: Chiradzulu
+ - abbr: CT
+ name: Chitipa
+ - abbr: DE
+ name: Dedza
+ - abbr: DO
+ name: Dowa
+ - abbr: KR
+ name: Karonga
+ - abbr: KS
+ name: Kasungu
+ - abbr: LK
+ name: Likoma Island
+ - abbr: LI
+ name: Lilongwe
+ - abbr: MH
+ name: Machinga
+ - abbr: MG
+ name: Mangochi
+ - abbr: MC
+ name: Mchinji
+ - abbr: MU
+ name: Mulanje
+ - abbr: MW
+ name: Mwanza
+ - abbr: MZ
+ name: Mzimba
+ - abbr: NE
+ name: Neno
+ - abbr: NB
+ name: Nkhata Bay
+ - abbr: NK
+ name: Nkhotakota
+ - abbr: "N"
+ name: Northern
+ - abbr: NS
+ name: Nsanje
+ - abbr: NU
+ name: Ntcheu
+ - abbr: NI
+ name: Ntchisi
+ - abbr: PH
+ name: Phalombe
+ - abbr: RU
+ name: Rumphi
+ - abbr: SA
+ name: Salima
+ - abbr: S
+ name: Southern
+ - abbr: TH
+ name: Thyolo
+ - abbr: ZO
+ name: Zomba
+ - iso: MY
+ iso3: MYS
+ name: Malaysia
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Johor
+ - abbr: '02'
+ name: Kedah
+ - abbr: '03'
+ name: Kelantan
+ - abbr: '04'
+ name: Melaka
+ - abbr: '05'
+ name: Negeri Sembilan
+ - abbr: '06'
+ name: Pahang
+ - abbr: '08'
+ name: Perak
+ - abbr: '09'
+ name: Perlis
+ - abbr: '07'
+ name: Pulau Pinang
+ - abbr: '12'
+ name: Sabah
+ - abbr: '13'
+ name: Sarawak
+ - abbr: '10'
+ name: Selangor
+ - abbr: '11'
+ name: Terengganu
+ - abbr: '14'
+ name: Wilayah Persekutuan Kuala Lumpur
+ - abbr: '15'
+ name: Wilayah Persekutuan Labuan
+ - abbr: '16'
+ name: Wilayah Persekutuan Putrajaya
+ - iso: MV
+ iso3: MDV
+ name: Maldives
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Addu
+ - abbr: '00'
+ name: Ariatholhu Dhekunuburi
+ - abbr: '02'
+ name: Ariatholhu Uthuruburi
+ - abbr: '03'
+ name: Faadhippolhu
+ - abbr: '04'
+ name: Felidheatholhu
+ - abbr: '29'
+ name: Fuvammulah
+ - abbr: '05'
+ name: Hahdhunmathi
+ - abbr: '28'
+ name: Huvadhuatholhu Dhekunuburi
+ - abbr: '27'
+ name: Huvadhuatholhu Uthuruburi
+ - abbr: '08'
+ name: Kolhumadulu
+ - abbr: '26'
+ name: Maaleatholhu
+ - abbr: '20'
+ name: Maalhosmadulu Dhekunuburi
+ - abbr: '13'
+ name: Maalhosmadulu Uthuruburi
+ - abbr: MLE
+ name: Male
+ - abbr: '25'
+ name: Miladhunmadulu Dhekunuburi
+ - abbr: '24'
+ name: Miladhunmadulu Uthuruburi
+ - abbr: '12'
+ name: Mulakatholhu
+ - abbr: '17'
+ name: Nilandheatholhu Dhekunuburi
+ - abbr: '14'
+ name: Nilandheatholhu Uthuruburi
+ - abbr: '23'
+ name: Thiladhunmathee Dhekunuburi
+ - abbr: '07'
+ name: Thiladhunmathee Uthuruburi
+ - iso: ML
+ iso3: MLI
+ name: Mali
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BKO
+ name: Bamako
+ - abbr: '7'
+ name: Gao
+ - abbr: '1'
+ name: Kayes
+ - abbr: '8'
+ name: Kidal
+ - abbr: '2'
+ name: Koulikoro
+ - abbr: '5'
+ name: Mopti
+ - abbr: '9'
+ name: Région de Ménaka
+ - abbr: '10'
+ name: Région de Taoudénit
+ - abbr: '3'
+ name: Sikasso
+ - abbr: '4'
+ name: Ségou
+ - abbr: '6'
+ name: Tombouctou
+ - iso: MT
+ iso3: MLT
+ name: Malta
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Attard
+ - abbr: '02'
+ name: Balzan
+ - abbr: '03'
+ name: Birgu
+ - abbr: '04'
+ name: Birkirkara
+ - abbr: '05'
+ name: Birżebbuġa
+ - abbr: '06'
+ name: Bormla
+ - abbr: '07'
+ name: Dingli
+ - abbr: '08'
+ name: Fgura
+ - abbr: '09'
+ name: Floriana
+ - abbr: '10'
+ name: Fontana
+ - abbr: '11'
+ name: Gudja
+ - abbr: '13'
+ name: Għajnsielem
+ - abbr: '14'
+ name: Għarb
+ - abbr: '15'
+ name: Għargħur
+ - abbr: '16'
+ name: Għasri
+ - abbr: '17'
+ name: Għaxaq
+ - abbr: '12'
+ name: Gżira
+ - abbr: '19'
+ name: Iklin
+ - abbr: '20'
+ name: Isla
+ - abbr: '21'
+ name: Kalkara
+ - abbr: '22'
+ name: Kerċem
+ - abbr: '23'
+ name: Kirkop
+ - abbr: '24'
+ name: Lija
+ - abbr: '25'
+ name: Luqa
+ - abbr: '26'
+ name: Marsa
+ - abbr: '27'
+ name: Marsaskala
+ - abbr: '28'
+ name: Marsaxlokk
+ - abbr: '29'
+ name: Mdina
+ - abbr: '30'
+ name: Mellieħa
+ - abbr: '32'
+ name: Mosta
+ - abbr: '33'
+ name: Mqabba
+ - abbr: '34'
+ name: Msida
+ - abbr: '35'
+ name: Mtarfa
+ - abbr: '36'
+ name: Munxar
+ - abbr: '31'
+ name: Mġarr
+ - abbr: '37'
+ name: Nadur
+ - abbr: '38'
+ name: Naxxar
+ - abbr: '39'
+ name: Paola
+ - abbr: '40'
+ name: Pembroke
+ - abbr: '41'
+ name: Pietà
+ - abbr: '42'
+ name: Qala
+ - abbr: '43'
+ name: Qormi
+ - abbr: '44'
+ name: Qrendi
+ - abbr: '45'
+ name: Rabat Gozo
+ - abbr: '46'
+ name: Rabat Malta
+ - abbr: '47'
+ name: Safi
+ - abbr: '49'
+ name: Saint John
+ - abbr: '48'
+ name: Saint Julian's
+ - abbr: '50'
+ name: Saint Lawrence
+ - abbr: '53'
+ name: Saint Lucia's
+ - abbr: '51'
+ name: Saint Paul's Bay
+ - abbr: '52'
+ name: Sannat
+ - abbr: '54'
+ name: Santa Venera
+ - abbr: '55'
+ name: Siġġiewi
+ - abbr: '56'
+ name: Sliema
+ - abbr: '57'
+ name: Swieqi
+ - abbr: '58'
+ name: Ta' Xbiex
+ - abbr: '59'
+ name: Tarxien
+ - abbr: '60'
+ name: Valletta
+ - abbr: '61'
+ name: Xagħra
+ - abbr: '62'
+ name: Xewkija
+ - abbr: '63'
+ name: Xgħajra
+ - abbr: '18'
+ name: Ħamrun
+ - abbr: '64'
+ name: Żabbar
+ - abbr: '65'
+ name: Żebbuġ Gozo
+ - abbr: '66'
+ name: Żebbuġ Malta
+ - abbr: '67'
+ name: Żejtun
+ - abbr: '68'
+ name: Żurrieq
+ - iso: MH
+ iso3: MHL
+ name: Marshall Islands
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: ALL
+ name: Ailinglapalap
+ - abbr: ALK
+ name: Ailuk
+ - abbr: ARN
+ name: Arno
+ - abbr: AUR
+ name: Aur
+ - abbr: EBO
+ name: Ebon
+ - abbr: ENI
+ name: Eniwetok
+ - abbr: JAB
+ name: Jabat
+ - abbr: JAL
+ name: Jaluit
+ - abbr: KIL
+ name: Kili
+ - abbr: KWA
+ name: Kwajalein
+ - abbr: LAE
+ name: Lae
+ - abbr: LIB
+ name: Lib
+ - abbr: LIK
+ name: Likiep
+ - abbr: MAJ
+ name: Majuro
+ - abbr: MAL
+ name: Maloelap
+ - abbr: MEJ
+ name: Mejit
+ - abbr: MIL
+ name: Mili
+ - abbr: NMK
+ name: Namorik
+ - abbr: NMU
+ name: Namu
+ - abbr: L
+ name: Ralik Chain
+ - abbr: T
+ name: Ratak Chain
+ - abbr: RON
+ name: Rongelap
+ - abbr: UJA
+ name: Ujae
+ - abbr: UJL
+ name: Ujelang
+ - abbr: UTI
+ name: Utirik
+ - abbr: WTH
+ name: Wotho
+ - abbr: WTJ
+ name: Wotje
+ - iso: MQ
+ iso3: MTQ
+ name: Martinique
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: MR
+ iso3: MRT
+ name: Mauritania
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '07'
+ name: Adrar
+ - abbr: '03'
+ name: Assaba
+ - abbr: '05'
+ name: Brakna
+ - abbr: '08'
+ name: Dakhlet Nouâdhibou
+ - abbr: '04'
+ name: Gorgol
+ - abbr: '10'
+ name: Guidimaka
+ - abbr: '01'
+ name: Hodh ech Chargui
+ - abbr: '02'
+ name: Hodh el Gharbi
+ - abbr: '12'
+ name: Inchiri
+ - abbr: '13'
+ name: Nouakchott Ouest
+ - abbr: '09'
+ name: Tagant
+ - abbr: '11'
+ name: Tiris Zemmour
+ - abbr: '06'
+ name: Trarza
+ - abbr: '15'
+ name: نواكشوط الجنوبية
+ - abbr: '14'
+ name: نواكشوط الشمالية
+ - iso: MU
+ iso3: MUS
+ name: Mauritius
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AG
+ name: Agalega Islands
+ - abbr: BL
+ name: Black River
+ - abbr: CC
+ name: Cargados Carajos Shoals [Saint Brandon Islands]
+ - abbr: FL
+ name: Flacq
+ - abbr: GP
+ name: Grand Port
+ - abbr: MO
+ name: Moka
+ - abbr: PA
+ name: Pamplemousses
+ - abbr: PW
+ name: Plaines Wilhems
+ - abbr: PL
+ name: Port Louis City
+ - abbr: RR
+ name: Rivière du Rempart
+ - abbr: RO
+ name: Rodrigues Island
+ - abbr: SA
+ name: Savanne
+ - iso: YT
+ iso3: MYT
+ name: Mayotte
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: MX
+ iso3: MEX
+ name: Mexico
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AGU
+ name: Aguascalientes
+ - abbr: BCN
+ name: Baja California
+ - abbr: BCS
+ name: Baja California Sur
+ - abbr: CAM
+ name: Campeche
+ - abbr: CHP
+ name: Chiapas
+ - abbr: CHH
+ name: Chihuahua
+ - abbr: CMX
+ name: Ciudad de México
+ - abbr: COA
+ name: Coahuila
+ - abbr: COL
+ name: Colima
+ - abbr: DUR
+ name: Durango
+ - abbr: GUA
+ name: Guanajuato
+ - abbr: GRO
+ name: Guerrero
+ - abbr: HID
+ name: Hidalgo
+ - abbr: JAL
+ name: Jalisco
+ - abbr: MIC
+ name: Michoacán
+ - abbr: MOR
+ name: Morelos
+ - abbr: MEX
+ name: México
+ - abbr: NAY
+ name: Nayarit
+ - abbr: NLE
+ name: Nuevo León
+ - abbr: OAX
+ name: Oaxaca
+ - abbr: PUE
+ name: Puebla
+ - abbr: QUE
+ name: Querétaro
+ - abbr: ROO
+ name: Quintana Roo
+ - abbr: SLP
+ name: San Luis Potosí
+ - abbr: SIN
+ name: Sinaloa
+ - abbr: SON
+ name: Sonora
+ - abbr: TAB
+ name: Tabasco
+ - abbr: TAM
+ name: Tamaulipas
+ - abbr: TLA
+ name: Tlaxcala
+ - abbr: VER
+ name: Veracruz
+ - abbr: YUC
+ name: Yucatán
+ - abbr: ZAC
+ name: Zacatecas
+ - iso: FM
+ iso3: FSM
+ name: Micronesia, Federated States of
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: TRK
+ name: Chuuk
+ - abbr: KSA
+ name: Kosrae
+ - abbr: PNI
+ name: Pohnpei
+ - abbr: YAP
+ name: Yap
+ - iso: MD
+ iso3: MDA
+ name: Moldova
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AN
+ name: Anenii Noi
+ - abbr: BA
+ name: Balti
+ - abbr: BS
+ name: Basarabeasca
+ - abbr: BD
+ name: Bender [Tighina]
+ - abbr: BR
+ name: Briceni
+ - abbr: CA
+ name: Cahul
+ - abbr: CT
+ name: Cantemir
+ - abbr: CU
+ name: Chisinau
+ - abbr: CM
+ name: Cimișlia
+ - abbr: CR
+ name: Criuleni
+ - abbr: CL
+ name: Călărași
+ - abbr: CS
+ name: Căușeni
+ - abbr: DO
+ name: Dondușeni
+ - abbr: DR
+ name: Drochia
+ - abbr: DU
+ name: Dubăsari
+ - abbr: ED
+ name: Edinet
+ - abbr: FL
+ name: Florești
+ - abbr: FA
+ name: Fălești
+ - abbr: GA
+ name: Gagauzia, Unitate Teritoriala Autonoma (UTAG)
+ - abbr: GL
+ name: Glodeni
+ - abbr: HI
+ name: Hîncești
+ - abbr: IA
+ name: Ialoveni
+ - abbr: LE
+ name: Leova
+ - abbr: NI
+ name: Nisporeni
+ - abbr: OC
+ name: Ocnița
+ - abbr: OR
+ name: Orhei
+ - abbr: RE
+ name: Rezina
+ - abbr: RI
+ name: Rîșcani
+ - abbr: SO
+ name: Soroca
+ - abbr: ST
+ name: Strășeni
+ - abbr: SN
+ name: Stînga Nistrului, unitatea teritoriala din
+ - abbr: SI
+ name: Sîngerei
+ - abbr: TA
+ name: Taraclia
+ - abbr: TE
+ name: Telenești
+ - abbr: UN
+ name: Ungheni
+ - abbr: SD
+ name: Șoldănești
+ - abbr: SV
+ name: Ștefan Vodă
+ - iso: MC
+ iso3: MCO
+ name: Monaco
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: FO
+ name: Fontvieille
+ - abbr: CL
+ name: La Colle
+ - abbr: CO
+ name: La Condamine
+ - abbr: GA
+ name: La Gare
+ - abbr: SR
+ name: La Rousse
+ - abbr: SO
+ name: La Source
+ - abbr: LA
+ name: Larvotto/Bas Moulins
+ - abbr: MA
+ name: Malbousquet
+ - abbr: MO
+ name: Monaco-Ville
+ - abbr: MG
+ name: Moneghetti
+ - abbr: MC
+ name: Monte-Carlo
+ - abbr: MU
+ name: Moulins
+ - abbr: PH
+ name: Port Hercule
+ - abbr: SP
+ name: Spélugues
+ - abbr: VR
+ name: Vallon de la Rousse
+ - abbr: JE
+ name: jardin exotique de Monaco
+ - abbr: SD
+ name: église Sainte-Dévote
+ - iso: MN
+ iso3: MNG
+ name: Mongolia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '073'
+ name: Arhangay
+ - abbr: '071'
+ name: Bayan-Ölgiy
+ - abbr: '069'
+ name: Bayanhongor
+ - abbr: '067'
+ name: Bulgan
+ - abbr: '037'
+ name: Darhan uul
+ - abbr: '061'
+ name: Dornod
+ - abbr: '063'
+ name: Dornogovi
+ - abbr: '059'
+ name: Dundgovi
+ - abbr: '057'
+ name: Dzavhan
+ - abbr: '065'
+ name: Govi-Altay
+ - abbr: '064'
+ name: Govi-Sümber
+ - abbr: '039'
+ name: Hentiy
+ - abbr: '043'
+ name: Hovd
+ - abbr: '041'
+ name: Hövsgöl
+ - abbr: '035'
+ name: Orhon
+ - abbr: '049'
+ name: Selenge
+ - abbr: '051'
+ name: Sühbaatar
+ - abbr: '047'
+ name: Töv
+ - abbr: '1'
+ name: Ulaanbaatar
+ - abbr: '046'
+ name: Uvs
+ - abbr: '053'
+ name: Ömnögovi
+ - abbr: '055'
+ name: Övörhangay
+ - iso: ME
+ iso3: MNE
+ name: Montenegro
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Andrijevica
+ - abbr: '02'
+ name: Bar
+ - abbr: '03'
+ name: Berane
+ - abbr: '04'
+ name: Bijelo Polje
+ - abbr: '05'
+ name: Budva
+ - abbr: '06'
+ name: Cetinje
+ - abbr: '07'
+ name: Danilovgrad
+ - abbr: '08'
+ name: Herceg-Novi
+ - abbr: '09'
+ name: Kolašin
+ - abbr: '10'
+ name: Kotor
+ - abbr: '11'
+ name: Mojkovac
+ - abbr: '12'
+ name: Nikšic´
+ - abbr: '13'
+ name: Plav
+ - abbr: '14'
+ name: Pljevlja
+ - abbr: '15'
+ name: Plužine
+ - abbr: '16'
+ name: Podgorica
+ - abbr: '17'
+ name: Rožaje
+ - abbr: '19'
+ name: Tivat
+ - abbr: '24'
+ name: Tuzi
+ - abbr: '20'
+ name: Ulcinj
+ - abbr: '18'
+ name: Šavnik
+ - abbr: '21'
+ name: Žabljak
+ - abbr: '22'
+ name: Општина Гусиње
+ - abbr: '23'
+ name: Општина Петњица
+ - iso: MS
+ iso3: MSR
+ name: Montserrat
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: MA
+ iso3: MAR
+ name: Morocco
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AGD
+ name: Agadir*
+ - abbr: HAO
+ name: Al Haouz
+ - abbr: HOC
+ name: Al Hoceïma
+ - abbr: AOU
+ name: Aousserd
+ - abbr: ASZ
+ name: Assa-Zag
+ - abbr: AZI
+ name: Azilal
+ - abbr: BAH
+ name: Aït Baha
+ - abbr: MEL
+ name: Aït Melloul
+ - abbr: BES
+ name: Ben Slimane
+ - abbr: BEM
+ name: Beni Mellal
+ - abbr: BER
+ name: Berkane
+ - abbr: BRR
+ name: Berrechid
+ - abbr: BOD
+ name: Boujdour (EH)
+ - abbr: BOM
+ name: Boulemane
+ - abbr: '05'
+ name: Béni Mellal-Khénifra
+ - abbr: CAS
+ name: Casablanca [Dar el Beïda]
+ - abbr: '06'
+ name: Casablanca-Settat
+ - abbr: CHE
+ name: Chefchaouene
+ - abbr: CHI
+ name: Chichaoua
+ - abbr: CHT
+ name: Chtouka-Ait Baha
+ - abbr: '12'
+ name: Dakhla-Oued Ed-Dahab (EH)
+ - abbr: DRI
+ name: Driouch
+ - abbr: '08'
+ name: Drâa-Tafilalet
+ - abbr: HAJ
+ name: El Hajeb
+ - abbr: JDI
+ name: El Jadida
+ - abbr: ERR
+ name: Errachidia
+ - abbr: ESM
+ name: Es Smara (EH)
+ - abbr: ESI
+ name: Essaouira
+ - abbr: FAH
+ name: Fahs-Beni Makada
+ - abbr: FIG
+ name: Figuig
+ - abbr: FQH
+ name: Fquih Ben Salah
+ - abbr: FES
+ name: Fès
+ - abbr: '03'
+ name: Fès-Meknès
+ - abbr: GUE
+ name: Guelmim
+ - abbr: '10'
+ name: Guelmim-Oued Noun (EH-partial)
+ - abbr: GUF
+ name: Guercif
+ - abbr: IFR
+ name: Ifrane
+ - abbr: JRA
+ name: Jerada
+ - abbr: KES
+ name: Kelaat Sraghna
+ - abbr: KHE
+ name: Khemisset
+ - abbr: KHN
+ name: Khenifra
+ - abbr: KHO
+ name: Khouribga
+ - abbr: KEN
+ name: Kénitra
+ - abbr: '02'
+ name: L'Oriental
+ - abbr: X1~
+ name: Laayoune-Boujdour-Sakia El Hamra
+ - abbr: LAR
+ name: Larache
+ - abbr: LAA
+ name: Laâyoune* (EH)
+ - abbr: '11'
+ name: Laâyoune-Sakia El Hamra (EH-partial)
+ - abbr: MAR
+ name: Marrakech
+ - abbr: '07'
+ name: Marrakech-Safi
+ - abbr: MEK
+ name: Meknès*
+ - abbr: MID
+ name: Midelt
+ - abbr: MOU
+ name: Moulay Yacoub
+ - abbr: MED
+ name: Médiouna
+ - abbr: MDF
+ name: M’diq-Fnideq
+ - abbr: NAD
+ name: Nador
+ - abbr: NOU
+ name: Nouaceur
+ - abbr: OUA
+ name: Ouarzazate
+ - abbr: OUD
+ name: Oued ed Dahab (EH)
+ - abbr: OUZ
+ name: Ouezzane
+ - abbr: OUJ
+ name: Oujda-Angad
+ - abbr: '04'
+ name: Rabat-Salé-Kénitra
+ - abbr: REH
+ name: Rehamna
+ - abbr: SAF
+ name: Safi
+ - abbr: SAL
+ name: Salé
+ - abbr: SEF
+ name: Sefrou
+ - abbr: SET
+ name: Settat
+ - abbr: SIB
+ name: Sidi Bennour
+ - abbr: SIF
+ name: Sidi Ifni
+ - abbr: SIK
+ name: Sidi Kacem
+ - abbr: SIL
+ name: Sidi Slimane
+ - abbr: SYB
+ name: Sidi Youssef Ben Ali
+ - abbr: SKH
+ name: Skhirate-Témara
+ - abbr: '09'
+ name: Souss-Massa
+ - abbr: TNT
+ name: Tan-Tan
+ - abbr: TNG
+ name: Tanger-Assilah
+ - abbr: '01'
+ name: Tanger-Tétouan-Al Hoceïma
+ - abbr: TAO
+ name: Taounate
+ - abbr: TAI
+ name: Taourirt
+ - abbr: TAF
+ name: Tarfaya (EH-partial)
+ - abbr: TAR
+ name: Taroudannt
+ - abbr: TAT
+ name: Tata
+ - abbr: TAZ
+ name: Taza
+ - abbr: TIN
+ name: Tinghir
+ - abbr: TIZ
+ name: Tiznit
+ - abbr: TET
+ name: Tétouan*
+ - abbr: YUS
+ name: Youssoufia
+ - abbr: ZAG
+ name: Zagora
+ - abbr: RAB
+ name: الرباط
+ - abbr: MOH
+ name: المحمدية
+ - abbr: INE
+ name: عمالة إنزكان آيت ملول
+ - abbr: MMD
+ name: مراكش
+ - abbr: MMN
+ name: مراكش²
+ - iso: MZ
+ iso3: MOZ
+ name: Mozambique
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: P
+ name: Cabo Delgado
+ - abbr: G
+ name: Gaza
+ - abbr: I
+ name: Inhambane
+ - abbr: B
+ name: Manica
+ - abbr: L
+ name: Maputo
+ - abbr: MPM
+ name: Maputo City
+ - abbr: "N"
+ name: Nampula
+ - abbr: A
+ name: Niassa
+ - abbr: S
+ name: Sofala
+ - abbr: T
+ name: Tete
+ - abbr: Q
+ name: Zambézia
+ - iso: MM
+ iso3: MMR
+ name: Myanmar
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '07'
+ name: Ayeyarwady
+ - abbr: '02'
+ name: Bago
+ - abbr: '14'
+ name: Chin
+ - abbr: '11'
+ name: Kachin
+ - abbr: '12'
+ name: Kayah
+ - abbr: '13'
+ name: Kayin
+ - abbr: '03'
+ name: Magway
+ - abbr: '04'
+ name: Mandalay
+ - abbr: '15'
+ name: Mon
+ - abbr: '16'
+ name: Rakhine
+ - abbr: '01'
+ name: Sagaing
+ - abbr: '17'
+ name: Shan
+ - abbr: '05'
+ name: Tanintharyi
+ - abbr: '06'
+ name: Yangon
+ - abbr: '18'
+ name: နေပြည်တော် ပြည်ထောင်စုနယ်မြေ
+ - iso: NA
+ iso3: NAM
+ name: Namibia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: ER
+ name: Erongo
+ - abbr: HA
+ name: Hardap
+ - abbr: KA
+ name: Karas
+ - abbr: KE
+ name: Kavango East
+ - abbr: KW
+ name: Kavango West
+ - abbr: KH
+ name: Khomas
+ - abbr: KU
+ name: Kunene
+ - abbr: OW
+ name: Ohangwena
+ - abbr: OH
+ name: Omaheke
+ - abbr: OS
+ name: Omusati
+ - abbr: 'ON'
+ name: Oshana
+ - abbr: OT
+ name: Oshikoto
+ - abbr: OD
+ name: Otjozondjupa
+ - abbr: CA
+ name: Zambezi
+ - iso: NR
+ iso3: NRU
+ name: Nauru
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '01'
+ name: Aiwo
+ - abbr: '02'
+ name: Anabar
+ - abbr: '03'
+ name: Anetan
+ - abbr: '04'
+ name: Anibare
+ - abbr: '05'
+ name: Baiti
+ - abbr: '06'
+ name: Boe
+ - abbr: '07'
+ name: Buada
+ - abbr: '08'
+ name: Denigomodu
+ - abbr: '09'
+ name: Ewa
+ - abbr: '10'
+ name: Ijuw
+ - abbr: '11'
+ name: Meneng
+ - abbr: '12'
+ name: Nibok
+ - abbr: '13'
+ name: Uaboe
+ - abbr: '14'
+ name: Yaren
+ - iso: NP
+ iso3: NPL
+ name: Nepal
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BA
+ name: Bagmati
+ - abbr: P3
+ name: Bagmati Province
+ - abbr: BH
+ name: Bheri
+ - abbr: DH
+ name: Dhawalagiri
+ - abbr: GA
+ name: Gandaki
+ - abbr: P4
+ name: Gandaki Province
+ - abbr: JA
+ name: Janakpur
+ - abbr: KA
+ name: Karnali
+ - abbr: P6
+ name: Karnali Province
+ - abbr: P1
+ name: Koshi Province
+ - abbr: KO
+ name: Kosi [Koshi]
+ - abbr: LU
+ name: Lumbini
+ - abbr: P5
+ name: Lumbini Province
+ - abbr: P2
+ name: Madhesh Province
+ - abbr: MA
+ name: Mahakali
+ - abbr: ME
+ name: Mechi
+ - abbr: NA
+ name: Narayani
+ - abbr: RA
+ name: Rapti
+ - abbr: SA
+ name: Sagarmatha
+ - abbr: SE
+ name: Seti
+ - abbr: P7
+ name: Sudurpashchim Province
+ - abbr: '3'
+ name: पश्चिमाञ्चल विकास क्षेत्र
+ - abbr: '4'
+ name: पूर्वाञ्चल विकास क्षेत्र
+ - abbr: '2'
+ name: मध्य-पश्चिमाञ्चल विकास क्षेत्र
+ - abbr: '1'
+ name: मध्यमाञ्चल विकास क्षेत्र
+ - abbr: '5'
+ name: सुदूर-पश्चिमाञ्चल विकास क्षेत्र
+ - iso: NL
+ iso3: NLD
+ name: Netherlands
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AW
+ name: Aruba
+ - abbr: BQ1
+ name: Bonaire
+ - abbr: CW
+ name: Curaçao
+ - abbr: DR
+ name: Drenthe
+ - abbr: FL
+ name: Flevoland
+ - abbr: FR
+ name: Friesland
+ - abbr: GE
+ name: Gelderland
+ - abbr: GR
+ name: Groningen
+ - abbr: LI
+ name: Limburg
+ - abbr: NB
+ name: Noord-Brabant
+ - abbr: NH
+ name: Noord-Holland
+ - abbr: OV
+ name: Overijssel
+ - abbr: BQ2
+ name: Saba
+ - abbr: BQ3
+ name: Sint Eustatius
+ - abbr: SX
+ name: Sint Maarten
+ - abbr: UT
+ name: Utrecht
+ - abbr: ZE
+ name: Zeeland
+ - abbr: ZH
+ name: Zuid-Holland
+ - iso: NC
+ iso3: NCL
+ name: New Caledonia
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: NZ
+ iso3: NZL
+ name: New Zealand
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AUK
+ name: Auckland
+ - abbr: BOP
+ name: Bay of Plenty
+ - abbr: CAN
+ name: Canterbury
+ - abbr: CIT
+ name: Chatham Islands Territory
+ - abbr: GIS
+ name: Gisborne
+ - abbr: HKB
+ name: Hawke's Bay
+ - abbr: MWT
+ name: Manawatu-Wanganui
+ - abbr: MBH
+ name: Marlborough
+ - abbr: NSN
+ name: Nelson
+ - abbr: NTL
+ name: Northland
+ - abbr: OTA
+ name: Otago
+ - abbr: STL
+ name: Southland
+ - abbr: TKI
+ name: Taranaki
+ - abbr: TAS
+ name: Tasman
+ - abbr: WKO
+ name: Waikato
+ - abbr: WGN
+ name: Wellington
+ - abbr: WTC
+ name: West Coast
+ - iso: NI
+ iso3: NIC
+ name: Nicaragua
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AN
+ name: Atlántico Norte*
+ - abbr: AS
+ name: Atlántico Sur*
+ - abbr: BO
+ name: Boaco
+ - abbr: CA
+ name: Carazo
+ - abbr: CI
+ name: Chinandega
+ - abbr: CO
+ name: Chontales
+ - abbr: ES
+ name: Estelí
+ - abbr: GR
+ name: Granada
+ - abbr: JI
+ name: Jinotega
+ - abbr: LE
+ name: León
+ - abbr: MD
+ name: Madriz
+ - abbr: MN
+ name: Managua
+ - abbr: MS
+ name: Masaya
+ - abbr: MT
+ name: Matagalpa
+ - abbr: NS
+ name: Nueva Segovia
+ - abbr: RI
+ name: Rivas
+ - abbr: SJ
+ name: Río San Juan
+ - iso: NE
+ iso3: NER
+ name: Niger
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '1'
+ name: Agadez
+ - abbr: '2'
+ name: Diffa
+ - abbr: '3'
+ name: Dosso
+ - abbr: '4'
+ name: Maradi
+ - abbr: '8'
+ name: Niamey
+ - abbr: '5'
+ name: Tahoua
+ - abbr: '6'
+ name: Tillabéri
+ - abbr: '7'
+ name: Zinder
+ - iso: NG
+ iso3: NGA
+ name: Nigeria
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AB
+ name: Abia
+ - abbr: FC
+ name: Abuja Capital Territory
+ - abbr: AD
+ name: Adamawa
+ - abbr: AK
+ name: Akwa Ibom
+ - abbr: AN
+ name: Anambra
+ - abbr: BA
+ name: Bauchi
+ - abbr: BY
+ name: Bayelsa
+ - abbr: BE
+ name: Benue
+ - abbr: BO
+ name: Borno
+ - abbr: CR
+ name: Cross River
+ - abbr: DE
+ name: Delta
+ - abbr: EB
+ name: Ebonyi
+ - abbr: ED
+ name: Edo
+ - abbr: EK
+ name: Ekiti
+ - abbr: EN
+ name: Enugu
+ - abbr: GO
+ name: Gombe
+ - abbr: IM
+ name: Imo
+ - abbr: JI
+ name: Jigawa
+ - abbr: KD
+ name: Kaduna
+ - abbr: KN
+ name: Kano
+ - abbr: KT
+ name: Katsina
+ - abbr: KE
+ name: Kebbi
+ - abbr: KO
+ name: Kogi
+ - abbr: KW
+ name: Kwara
+ - abbr: LA
+ name: Lagos
+ - abbr: NA
+ name: Nassarawa
+ - abbr: NI
+ name: Niger
+ - abbr: OG
+ name: Ogun
+ - abbr: 'ON'
+ name: Ondo
+ - abbr: OS
+ name: Osun
+ - abbr: OY
+ name: Oyo
+ - abbr: PL
+ name: Plateau
+ - abbr: RI
+ name: Rivers
+ - abbr: SO
+ name: Sokoto
+ - abbr: TA
+ name: Taraba
+ - abbr: YO
+ name: Yobe
+ - abbr: ZA
+ name: Zamfara
+ - iso: NU
+ iso3: NIU
+ name: Niue
+ states_required: false
+ zipcode_required: false
+ states: []
+ - iso: NF
+ iso3: NFK
+ name: Norfolk Island
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: KP
+ iso3: PRK
+ name: North Korea
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '07'
+ name: 강원도
+ - abbr: '14'
+ name: 남포특별시
+ - abbr: '13'
+ name: 라선특별시
+ - abbr: '10'
+ name: 량강도
+ - abbr: '04'
+ name: 자강도
+ - abbr: '02'
+ name: 평안남도
+ - abbr: '03'
+ name: 평안북도
+ - abbr: '01'
+ name: 평양직할시
+ - abbr: '08'
+ name: 함경남도
+ - abbr: '09'
+ name: 함경북도
+ - abbr: '05'
+ name: 황해남도
+ - abbr: '06'
+ name: 황해북도
+ - iso: MK
+ iso3: MKD
+ name: North Macedonia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '801'
+ name: Aerodrom †
+ - abbr: '802'
+ name: Aračinovo
+ - abbr: '201'
+ name: Berovo
+ - abbr: '501'
+ name: Bitola
+ - abbr: '401'
+ name: Bogdanci
+ - abbr: '601'
+ name: Bogovinje
+ - abbr: '402'
+ name: Bosilovo
+ - abbr: '602'
+ name: Brvenica
+ - abbr: '803'
+ name: Butel †
+ - abbr: '313'
+ name: Centar Župa
+ - abbr: '814'
+ name: Centar †
+ - abbr: '303'
+ name: Debar
+ - abbr: '304'
+ name: Debarca
+ - abbr: '203'
+ name: Delčevo
+ - abbr: '502'
+ name: Demir Hisar
+ - abbr: '103'
+ name: Demir Kapija
+ - abbr: '406'
+ name: Dojran
+ - abbr: '503'
+ name: Dolneni
+ - abbr: '804'
+ name: Gazi Baba †
+ - abbr: '405'
+ name: Gevgelija
+ - abbr: '805'
+ name: Gjorče Petrov †
+ - abbr: '604'
+ name: Gostivar
+ - abbr: '102'
+ name: Gradsko
+ - abbr: '807'
+ name: Ilinden
+ - abbr: '606'
+ name: Jegunovce
+ - abbr: '205'
+ name: Karbinci
+ - abbr: '808'
+ name: Karpoš †
+ - abbr: '104'
+ name: Kavadarci
+ - abbr: '809'
+ name: Kisela Voda †
+ - abbr: '307'
+ name: Kičevo
+ - abbr: '407'
+ name: Konče
+ - abbr: '206'
+ name: Kočani
+ - abbr: '701'
+ name: Kratovo
+ - abbr: '702'
+ name: Kriva Palanka
+ - abbr: '504'
+ name: Krivogaštani
+ - abbr: '505'
+ name: Kruševo
+ - abbr: '703'
+ name: Kumanovo
+ - abbr: '704'
+ name: Lipkovo
+ - abbr: '105'
+ name: Lozovo
+ - abbr: '207'
+ name: Makedonska Kamenica
+ - abbr: '308'
+ name: Makedonski Brod
+ - abbr: '607'
+ name: Mavrovo i Rostuša
+ - abbr: '506'
+ name: Mogila
+ - abbr: '106'
+ name: Negotino
+ - abbr: '507'
+ name: Novaci
+ - abbr: '408'
+ name: Novo Selo
+ - abbr: '310'
+ name: Ohrid
+ - abbr: '208'
+ name: Pehčevo
+ - abbr: '810'
+ name: Petrovec
+ - abbr: '311'
+ name: Plasnica
+ - abbr: '508'
+ name: Prilep
+ - abbr: '209'
+ name: Probištip
+ - abbr: '409'
+ name: Radoviš
+ - abbr: '705'
+ name: Rankovce
+ - abbr: '509'
+ name: Resen
+ - abbr: '107'
+ name: Rosoman
+ - abbr: '811'
+ name: Saraj †
+ - abbr: '812'
+ name: Sopište
+ - abbr: '706'
+ name: Staro Nagoričane
+ - abbr: '312'
+ name: Struga
+ - abbr: '410'
+ name: Strumica
+ - abbr: '813'
+ name: Studeničani
+ - abbr: '108'
+ name: Sveti Nikole
+ - abbr: '608'
+ name: Tearce
+ - abbr: '609'
+ name: Tetovo
+ - abbr: '403'
+ name: Valandovo
+ - abbr: '404'
+ name: Vasilevo
+ - abbr: '101'
+ name: Veles
+ - abbr: '301'
+ name: Vevčani
+ - abbr: '202'
+ name: Vinica
+ - abbr: '603'
+ name: Vrapčište
+ - abbr: '806'
+ name: Zelenikovo
+ - abbr: '204'
+ name: Zrnovci
+ - abbr: '815'
+ name: Čair †
+ - abbr: '109'
+ name: Čaška
+ - abbr: '210'
+ name: Češinovo-Obleševo
+ - abbr: '816'
+ name: Čučer-Sandevo
+ - abbr: '211'
+ name: Štip
+ - abbr: '817'
+ name: Šuto Orizari †
+ - abbr: '605'
+ name: Želino
+ - iso: MP
+ iso3: MNP
+ name: Northern Mariana Islands
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: 'NO'
+ iso3: NOR
+ name: Norway
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '42'
+ name: Agder
+ - abbr: '34'
+ name: Innlandet
+ - abbr: '22'
+ name: Jan Mayen (Arctic Region)
+ - abbr: '15'
+ name: Møre og Romsdal
+ - abbr: '18'
+ name: Nordland
+ - abbr: '03'
+ name: Oslo
+ - abbr: '11'
+ name: Rogaland
+ - abbr: '21'
+ name: Svalbard (Arctic Region)
+ - abbr: '54'
+ name: Troms og Finnmark
+ - abbr: '50'
+ name: Trøndelag
+ - abbr: '38'
+ name: Vestfold og Telemark
+ - abbr: '46'
+ name: Vestland
+ - abbr: '30'
+ name: Viken
+ - iso: OM
+ iso3: OMN
+ name: Oman
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: DA
+ name: Ad Dakhiliyah
+ - abbr: ZA
+ name: Adh Dhahirah
+ - abbr: WU
+ name: Al Wustá
+ - abbr: MA
+ name: Masqat
+ - abbr: MU
+ name: Musandam
+ - abbr: BU
+ name: محافظة البريمي
+ - abbr: BJ
+ name: محافظة جنوب الباطنة
+ - abbr: SJ
+ name: محافظة جنوب الشرقية
+ - abbr: BS
+ name: محافظة شمال الباطنة
+ - abbr: SS
+ name: محافظة شمال الشرقية
+ - abbr: ZU
+ name: محافظة ظفار
+ - iso: PK
+ iso3: PAK
+ name: Pakistan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: JK
+ name: Azad Kashmir
+ - abbr: BA
+ name: Baluchistan (en)
+ - abbr: GB
+ name: Gilgit-Baltistan
+ - abbr: IS
+ name: Islamabad
+ - abbr: KP
+ name: Khyber Pakhtunkhwa
+ - abbr: PB
+ name: Punjab
+ - abbr: SD
+ name: Sind (en)
+ - iso: PW
+ iso3: PLW
+ name: Palau
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '002'
+ name: Aimeliik
+ - abbr: '004'
+ name: Airai
+ - abbr: '010'
+ name: Angaur
+ - abbr: '050'
+ name: Hatobohei
+ - abbr: '100'
+ name: Kayangel
+ - abbr: '150'
+ name: Koror
+ - abbr: '212'
+ name: Melekeok
+ - abbr: '214'
+ name: Ngaraard
+ - abbr: '218'
+ name: Ngarchelong
+ - abbr: '222'
+ name: Ngardmau
+ - abbr: '224'
+ name: Ngatpang
+ - abbr: '226'
+ name: Ngchesar
+ - abbr: '227'
+ name: Ngeremlengui
+ - abbr: '228'
+ name: Ngiwal
+ - abbr: '350'
+ name: Peleliu
+ - abbr: '370'
+ name: Sonsorol
+ - iso: PS
+ iso3: PSE
+ name: Palestine, State of
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: JRH
+ name: أريحا
+ - abbr: JEM
+ name: القدس
+ - abbr: DEB
+ name: الوسطى
+ - abbr: JEN
+ name: جنين
+ - abbr: RBH
+ name: رام الله والبيرة
+ - abbr: NGZ
+ name: شمال غزة
+ - abbr: HBN
+ name: محافظة الخليل
+ - abbr: BTH
+ name: محافظة بيت لحم
+ - abbr: KYS
+ name: محافظة خان يونس
+ - abbr: RFH
+ name: محافظة رفح الفلسطينية
+ - abbr: SLT
+ name: محافظة سلفيت
+ - abbr: TBS
+ name: محافظة طوباس
+ - abbr: TKM
+ name: محافظة طولكرم
+ - abbr: GZA
+ name: محافظة غزة
+ - abbr: QQA
+ name: محافظة قلقيلية
+ - abbr: NBS
+ name: محافظة نابلس
+ - iso: PA
+ iso3: PAN
+ name: Panama
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '1'
+ name: Bocas del Toro
+ - abbr: '4'
+ name: Chiriquí
+ - abbr: '2'
+ name: Coclé
+ - abbr: '3'
+ name: Colón
+ - abbr: '5'
+ name: Darién
+ - abbr: EM
+ name: Emberá-Wounaan
+ - abbr: KY
+ name: Guna Yala
+ - abbr: '6'
+ name: Herrera
+ - abbr: '7'
+ name: Los Santos
+ - abbr: NB
+ name: Ngäbe-Buglé
+ - abbr: '8'
+ name: Panamá
+ - abbr: '10'
+ name: Panamá Oeste
+ - abbr: '9'
+ name: Veraguas
+ - iso: PG
+ iso3: PNG
+ name: Papua New Guinea
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: NSB
+ name: Bougainville
+ - abbr: CPM
+ name: Central
+ - abbr: CPK
+ name: Chimbu
+ - abbr: EBR
+ name: East New Britain
+ - abbr: ESW
+ name: East Sepik
+ - abbr: EHG
+ name: Eastern Highlands
+ - abbr: EPW
+ name: Enga
+ - abbr: GPK
+ name: Gulf
+ - abbr: HLA
+ name: Hela
+ - abbr: JWK
+ name: Jiwaka
+ - abbr: MPM
+ name: Madang
+ - abbr: MRL
+ name: Manus
+ - abbr: MBA
+ name: Milne Bay
+ - abbr: MPL
+ name: Morobe
+ - abbr: NCD
+ name: National Capital District (Port Moresby)
+ - abbr: NIK
+ name: New Ireland
+ - abbr: NPP
+ name: Northern
+ - abbr: SAN
+ name: Sandaun [West Sepik]
+ - abbr: SHM
+ name: Southern Highlands
+ - abbr: WBK
+ name: West New Britain
+ - abbr: WPD
+ name: Western
+ - abbr: WHM
+ name: Western Highlands
+ - iso: PY
+ iso3: PRY
+ name: Paraguay
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '16'
+ name: Alto Paraguay
+ - abbr: '10'
+ name: Alto Paraná
+ - abbr: '13'
+ name: Amambay
+ - abbr: ASU
+ name: Asunción
+ - abbr: '19'
+ name: Boquerón
+ - abbr: '5'
+ name: Caaguazú
+ - abbr: '6'
+ name: Caazapá
+ - abbr: '14'
+ name: Canindeyú
+ - abbr: '11'
+ name: Central
+ - abbr: '1'
+ name: Concepción
+ - abbr: '3'
+ name: Cordillera
+ - abbr: '4'
+ name: Guairá
+ - abbr: '7'
+ name: Itapúa
+ - abbr: '8'
+ name: Misiones
+ - abbr: '9'
+ name: Paraguarí
+ - abbr: '15'
+ name: Presidente Hayes
+ - abbr: '2'
+ name: San Pedro
+ - abbr: '12'
+ name: Ñeembucú
+ - iso: PE
+ iso3: PER
+ name: Peru
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AMA
+ name: Amazonas
+ - abbr: ANC
+ name: Ancash
+ - abbr: APU
+ name: Apurímac
+ - abbr: ARE
+ name: Arequipa
+ - abbr: AYA
+ name: Ayacucho
+ - abbr: CAJ
+ name: Cajamarca
+ - abbr: CUS
+ name: Cuzco [Cusco]
+ - abbr: CAL
+ name: El Callao
+ - abbr: HUV
+ name: Huancavelica
+ - abbr: HUC
+ name: Huánuco
+ - abbr: ICA
+ name: Ica
+ - abbr: JUN
+ name: Junín
+ - abbr: LAL
+ name: La Libertad
+ - abbr: LAM
+ name: Lambayeque
+ - abbr: LIM
+ name: Lima
+ - abbr: LMA
+ name: Lima Metropolitana
+ - abbr: LOR
+ name: Loreto
+ - abbr: MDD
+ name: Madre de Dios
+ - abbr: MOQ
+ name: Moquegua
+ - abbr: PAS
+ name: Pasco
+ - abbr: PIU
+ name: Piura
+ - abbr: PUN
+ name: Puno
+ - abbr: SAM
+ name: San Martín
+ - abbr: TAC
+ name: Tacna
+ - abbr: TUM
+ name: Tumbes
+ - abbr: UCA
+ name: Ucayali
+ - iso: PH
+ iso3: PHL
+ name: Philippines
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: ABR
+ name: Abra
+ - abbr: AGN
+ name: Agusan del Norte
+ - abbr: AGS
+ name: Agusan del Sur
+ - abbr: AKL
+ name: Aklan
+ - abbr: ALB
+ name: Albay
+ - abbr: ANT
+ name: Antique
+ - abbr: APA
+ name: Apayao
+ - abbr: AUR
+ name: Aurora
+ - abbr: BAS
+ name: Basilan
+ - abbr: BAN
+ name: Bataan
+ - abbr: BTN
+ name: Batanes
+ - abbr: BTG
+ name: Batangas
+ - abbr: BEN
+ name: Benguet
+ - abbr: '05'
+ name: Bicol
+ - abbr: BIL
+ name: Biliran
+ - abbr: BOH
+ name: Bohol
+ - abbr: BUK
+ name: Bukidnon
+ - abbr: BUL
+ name: Bulacan
+ - abbr: CAG
+ name: Cagayan
+ - abbr: '02'
+ name: Cagayan Valley
+ - abbr: '40'
+ name: Calabarzon
+ - abbr: CAN
+ name: Camarines Norte
+ - abbr: CAS
+ name: Camarines Sur
+ - abbr: CAM
+ name: Camiguin
+ - abbr: CAP
+ name: Capiz
+ - abbr: '13'
+ name: Caraga
+ - abbr: CAT
+ name: Catanduanes
+ - abbr: CAV
+ name: Cavite
+ - abbr: CEB
+ name: Cebu
+ - abbr: '03'
+ name: Central Luzon
+ - abbr: '07'
+ name: Central Visayas
+ - abbr: COM
+ name: Compostela Valley
+ - abbr: '15'
+ name: Cordillera Administrative
+ - abbr: '11'
+ name: Davao
+ - abbr: DVO
+ name: Davao Occidental
+ - abbr: DAO
+ name: Davao Oriental
+ - abbr: DAV
+ name: Davao del Norte
+ - abbr: DAS
+ name: Davao del Sur
+ - abbr: DIN
+ name: Dinagat Islands
+ - abbr: EAS
+ name: Eastern Samar
+ - abbr: '08'
+ name: Eastern Visayas
+ - abbr: GUI
+ name: Guimaras
+ - abbr: IFU
+ name: Ifugao
+ - abbr: '01'
+ name: Ilocos
+ - abbr: ILN
+ name: Ilocos Norte
+ - abbr: ILS
+ name: Ilocos Sur
+ - abbr: ILI
+ name: Iloilo
+ - abbr: ISA
+ name: Isabela
+ - abbr: KAL
+ name: Kalinga
+ - abbr: LUN
+ name: La Union
+ - abbr: LAG
+ name: Laguna
+ - abbr: LAN
+ name: Lanao del Norte
+ - abbr: LAS
+ name: Lanao del Sur
+ - abbr: LEY
+ name: Leyte
+ - abbr: MAG
+ name: Maguindanao
+ - abbr: MAD
+ name: Marinduque
+ - abbr: MAS
+ name: Masbate
+ - abbr: '41'
+ name: Mimaropa
+ - abbr: MDC
+ name: Mindoro Occidental
+ - abbr: MDR
+ name: Mindoro Oriental
+ - abbr: MSC
+ name: Misamis Occidental
+ - abbr: MSR
+ name: Misamis Oriental
+ - abbr: MOU
+ name: Mountain Province
+ - abbr: '14'
+ name: Muslim Mindanao
+ - abbr: '00'
+ name: National Capital Region
+ - abbr: NEC
+ name: Negros Occidental
+ - abbr: NER
+ name: Negros Oriental
+ - abbr: NCO
+ name: North Cotabato
+ - abbr: '10'
+ name: Northern Mindanao
+ - abbr: NSA
+ name: Northern Samar
+ - abbr: NUE
+ name: Nueva Ecija
+ - abbr: NUV
+ name: Nueva Vizcaya
+ - abbr: PLW
+ name: Palawan
+ - abbr: PAM
+ name: Pampanga
+ - abbr: PAN
+ name: Pangasinan
+ - abbr: QUE
+ name: Quezon
+ - abbr: QUI
+ name: Quirino
+ - abbr: RIZ
+ name: Rizal
+ - abbr: ROM
+ name: Romblon
+ - abbr: SAR
+ name: Sarangani
+ - abbr: SIG
+ name: Siquijor
+ - abbr: '12'
+ name: Soccsksargen
+ - abbr: SOR
+ name: Sorsogon
+ - abbr: SCO
+ name: South Cotabato
+ - abbr: SLE
+ name: Southern Leyte
+ - abbr: SUK
+ name: Sultan Kudarat
+ - abbr: SLU
+ name: Sulu
+ - abbr: SUN
+ name: Surigao del Norte
+ - abbr: SUR
+ name: Surigao del Sur
+ - abbr: TAR
+ name: Tarlac
+ - abbr: TAW
+ name: Tawi-Tawi
+ - abbr: WSA
+ name: Western Samar
+ - abbr: '06'
+ name: Western Visayas
+ - abbr: ZMB
+ name: Zambales
+ - abbr: '09'
+ name: Zamboanga Peninsula
+ - abbr: ZSI
+ name: Zamboanga Sibuguey [Zamboanga Sibugay]
+ - abbr: ZAN
+ name: Zamboanga del Norte
+ - abbr: ZAS
+ name: Zamboanga del Sur
+ - iso: PN
+ iso3: PCN
+ name: Pitcairn
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: PL
+ iso3: POL
+ name: Poland
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '02'
+ name: Dolnośląskie
+ - abbr: '04'
+ name: Kujawsko-pomorskie
+ - abbr: '06'
+ name: Lubelskie
+ - abbr: '08'
+ name: Lubuskie
+ - abbr: '14'
+ name: Mazowieckie
+ - abbr: '12'
+ name: Małopolskie
+ - abbr: '16'
+ name: Opolskie
+ - abbr: '18'
+ name: Podkarpackie
+ - abbr: '20'
+ name: Podlaskie
+ - abbr: '22'
+ name: Pomorskie
+ - abbr: '28'
+ name: Warmińsko-mazurskie
+ - abbr: '30'
+ name: Wielkopolskie
+ - abbr: '32'
+ name: Zachodniopomorskie
+ - abbr: '10'
+ name: Łódzkie
+ - abbr: '24'
+ name: Śląskie
+ - abbr: '26'
+ name: Świętokrzyskie
+ - iso: PT
+ iso3: PRT
+ name: Portugal
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Aveiro
+ - abbr: '20'
+ name: Açores
+ - abbr: '02'
+ name: Beja
+ - abbr: '03'
+ name: Braga
+ - abbr: '04'
+ name: Bragança
+ - abbr: '05'
+ name: Castelo Branco
+ - abbr: '06'
+ name: Coimbra
+ - abbr: '08'
+ name: Faro
+ - abbr: '09'
+ name: Guarda
+ - abbr: '10'
+ name: Leiria
+ - abbr: '11'
+ name: Lisboa
+ - abbr: '30'
+ name: Madeira
+ - abbr: '12'
+ name: Portalegre
+ - abbr: '13'
+ name: Porto
+ - abbr: '14'
+ name: Santarém
+ - abbr: '15'
+ name: Setúbal
+ - abbr: '16'
+ name: Viana do Castelo
+ - abbr: '17'
+ name: Vila Real
+ - abbr: '18'
+ name: Viseu
+ - abbr: '07'
+ name: Évora
+ - iso: PR
+ iso3: PRI
+ name: Puerto Rico
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: QA
+ iso3: QAT
+ name: Qatar
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: DA
+ name: Ad Dawhah
+ - abbr: KH
+ name: Al Khawr
+ - abbr: WA
+ name: Al Wakrah
+ - abbr: RA
+ name: Ar Rayyan
+ - abbr: MS
+ name: Madinat ash Shamal
+ - abbr: US
+ name: Umm Salal
+ - abbr: SH
+ name: الشحانية
+ - abbr: ZA
+ name: بلدية الضعاين
+ - iso: RO
+ iso3: ROU
+ name: Romania
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AB
+ name: Alba
+ - abbr: AR
+ name: Arad
+ - abbr: AG
+ name: Arges
+ - abbr: BC
+ name: Bacau
+ - abbr: BH
+ name: Bihor
+ - abbr: BN
+ name: Bistrita-Nasaud
+ - abbr: BT
+ name: Botosani
+ - abbr: BR
+ name: Braila
+ - abbr: BV
+ name: Brasov
+ - abbr: B
+ name: Bucuresti
+ - abbr: BZ
+ name: Buzau
+ - abbr: CL
+ name: Calarasi
+ - abbr: CS
+ name: Caras-Severin
+ - abbr: CJ
+ name: Cluj
+ - abbr: CT
+ name: Constanta
+ - abbr: CV
+ name: Covasna
+ - abbr: DJ
+ name: Dolj
+ - abbr: DB
+ name: Dâmbovita
+ - abbr: GL
+ name: Galati
+ - abbr: GR
+ name: Giurgiu
+ - abbr: GJ
+ name: Gorj
+ - abbr: HR
+ name: Harghita
+ - abbr: HD
+ name: Hunedoara
+ - abbr: IL
+ name: Ialomita
+ - abbr: IS
+ name: Iasi
+ - abbr: IF
+ name: Ilfov
+ - abbr: MM
+ name: Maramures
+ - abbr: MH
+ name: Mehedinti
+ - abbr: MS
+ name: Mures
+ - abbr: NT
+ name: Neamt
+ - abbr: OT
+ name: Olt
+ - abbr: PH
+ name: Prahova
+ - abbr: SJ
+ name: Salaj
+ - abbr: SM
+ name: Satu Mare
+ - abbr: SB
+ name: Sibiu
+ - abbr: SV
+ name: Suceava
+ - abbr: TR
+ name: Teleorman
+ - abbr: TM
+ name: Timis
+ - abbr: TL
+ name: Tulcea
+ - abbr: VS
+ name: Vaslui
+ - abbr: VN
+ name: Vrancea
+ - abbr: VL
+ name: Vâlcea
+ - iso: RU
+ iso3: RUS
+ name: Russian Federation
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AD
+ name: Adygeya, Respublika
+ - abbr: AL
+ name: Altay, Respublika
+ - abbr: ALT
+ name: Altayskiy kray
+ - abbr: AMU
+ name: Amurskaya oblast'
+ - abbr: ARK
+ name: Arkhangel'skaya oblast'
+ - abbr: AST
+ name: Astrakhanskaya oblast'
+ - abbr: BA
+ name: Bashkortostan, Respublika
+ - abbr: BEL
+ name: Belgorodskaya oblast'
+ - abbr: BRY
+ name: Bryanskaya oblast'
+ - abbr: BU
+ name: Buryatiya, Respublika
+ - abbr: CE
+ name: Chechenskaya Respublika
+ - abbr: CHE
+ name: Chelyabinskaya oblast'
+ - abbr: CHU
+ name: Chukotskiy avtonomnyy okrug
+ - abbr: CU
+ name: Chuvashskaya Respublika
+ - abbr: DA
+ name: Dagestan, Respublika
+ - abbr: IN
+ name: Ingushskaya Respublika [Respublika Ingushetiya]
+ - abbr: IRK
+ name: Irkutskaya oblast'
+ - abbr: IVA
+ name: Ivanovskaya oblast'
+ - abbr: KB
+ name: Kabardino-Balkarskaya Respublika
+ - abbr: KGD
+ name: Kaliningradskaya oblast'
+ - abbr: KL
+ name: Kalmykiya, Respublika
+ - abbr: KLU
+ name: Kaluzhskaya oblast'
+ - abbr: KAM
+ name: Kamchatskaya oblast'
+ - abbr: KC
+ name: Karachayevo-Cherkesskaya Respublika
+ - abbr: KR
+ name: Kareliya, Respublika
+ - abbr: KEM
+ name: Kemerovskaya oblast'
+ - abbr: KHA
+ name: Khabarovskiy kray
+ - abbr: KK
+ name: Khakasiya, Respublika
+ - abbr: KHM
+ name: Khanty-Mansiyskiy avtonomnyy okrug [Yugra]
+ - abbr: KIR
+ name: Kirovskaya oblast'
+ - abbr: KO
+ name: Komi, Respublika
+ - abbr: KOS
+ name: Kostromskaya oblast'
+ - abbr: KDA
+ name: Krasnodarskiy kray
+ - abbr: KYA
+ name: Krasnoyarskiy kray
+ - abbr: KGN
+ name: Kurganskaya oblast'
+ - abbr: KRS
+ name: Kurskaya oblast'
+ - abbr: LEN
+ name: Leningradskaya oblast'
+ - abbr: LIP
+ name: Lipetskaya oblast'
+ - abbr: MAG
+ name: Magadanskaya oblast'
+ - abbr: ME
+ name: Mariy El, Respublika
+ - abbr: MO
+ name: Mordoviya, Respublika
+ - abbr: MOS
+ name: Moskovskaya oblast'
+ - abbr: MOW
+ name: Moskva
+ - abbr: MUR
+ name: Murmanskaya oblast'
+ - abbr: NEN
+ name: Nenetskiy avtonomnyy okrug
+ - abbr: NIZ
+ name: Nizhegorodskaya oblast'
+ - abbr: NGR
+ name: Novgorodskaya oblast'
+ - abbr: NVS
+ name: Novosibirskaya oblast'
+ - abbr: OMS
+ name: Omskaya oblast'
+ - abbr: ORE
+ name: Orenburgskaya oblast'
+ - abbr: ORL
+ name: Orlovskaya oblast'
+ - abbr: PNZ
+ name: Penzenskaya oblast'
+ - abbr: PER
+ name: Perm
+ - abbr: PRI
+ name: Primorskiy kray
+ - abbr: PSK
+ name: Pskovskaya oblast'
+ - abbr: ROS
+ name: Rostovskaya oblast'
+ - abbr: RYA
+ name: Ryazanskaya oblast'
+ - abbr: SA
+ name: Sakha, Respublika [Yakutiya]
+ - abbr: SAK
+ name: Sakhalinskaya oblast'
+ - abbr: SAM
+ name: Samarskaya oblast'
+ - abbr: SPE
+ name: Sankt-Peterburg
+ - abbr: SAR
+ name: Saratovskaya oblast'
+ - abbr: SE
+ name: Severnaya Osetiya, Respublika [Alaniya] [Respublika Severnaya
+ Osetiya-Alaniya]
+ - abbr: SMO
+ name: Smolenskaya oblast'
+ - abbr: STA
+ name: Stavropol'skiy kray
+ - abbr: SVE
+ name: Sverdlovskaya oblast'
+ - abbr: TAM
+ name: Tambovskaya oblast'
+ - abbr: TA
+ name: Tatarstan, Respublika
+ - abbr: TOM
+ name: Tomskaya oblast'
+ - abbr: TUL
+ name: Tul'skaya oblast'
+ - abbr: TVE
+ name: Tverskaya oblast'
+ - abbr: TYU
+ name: Tyumenskaya oblast'
+ - abbr: TY
+ name: Tyva, Respublika [Tuva]
+ - abbr: UD
+ name: Udmurtskaya Respublika
+ - abbr: ULY
+ name: Ul'yanovskaya oblast'
+ - abbr: VLA
+ name: Vladimirskaya oblast'
+ - abbr: VGG
+ name: Volgogradskaya oblast'
+ - abbr: VLG
+ name: Vologodskaya oblast'
+ - abbr: VOR
+ name: Voronezhskaya oblast'
+ - abbr: YAN
+ name: Yamalo-Nenetskiy avtonomnyy okrug
+ - abbr: YAR
+ name: Yaroslavskaya oblast'
+ - abbr: YEV
+ name: Yevreyskaya avtonomnaya oblast'
+ - abbr: ZAB
+ name: Zabaykal'skij kray
+ - iso: RW
+ iso3: RWA
+ name: Rwanda
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '02'
+ name: Est
+ - abbr: '03'
+ name: Nord
+ - abbr: '04'
+ name: Ouest
+ - abbr: '05'
+ name: Sud
+ - abbr: '01'
+ name: Ville de Kigali
+ - iso: RE
+ iso3: REU
+ name: Réunion
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: BL
+ iso3: BLM
+ name: Saint Barthélemy
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: SH
+ iso3: SHN
+ name: Saint Helena, Ascension and Tristan da Cunha
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AC
+ name: Ascension
+ - abbr: HL
+ name: Saint Helena
+ - abbr: TA
+ name: Tristan da Cunha
+ - iso: KN
+ iso3: KNA
+ name: Saint Kitts and Nevis
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '01'
+ name: Christ Church Nichola Town
+ - abbr: "N"
+ name: Nevis
+ - abbr: '02'
+ name: Saint Anne Sandy Point
+ - abbr: '03'
+ name: Saint George Basseterre
+ - abbr: '04'
+ name: Saint George Gingerland
+ - abbr: '05'
+ name: Saint James Windward
+ - abbr: '06'
+ name: Saint John Capisterre
+ - abbr: '07'
+ name: Saint John Figtree
+ - abbr: K
+ name: Saint Kitts
+ - abbr: '08'
+ name: Saint Mary Cayon
+ - abbr: '09'
+ name: Saint Paul Capisterre
+ - abbr: '10'
+ name: Saint Paul Charlestown
+ - abbr: '11'
+ name: Saint Peter Basseterre
+ - abbr: '12'
+ name: Saint Thomas Lowland
+ - abbr: '13'
+ name: Saint Thomas Middle Island
+ - abbr: '15'
+ name: Trinity Palmetto Point
+ - iso: LC
+ iso3: LCA
+ name: Saint Lucia
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '01'
+ name: Anse la Raye
+ - abbr: '12'
+ name: Canaries
+ - abbr: '02'
+ name: Castries
+ - abbr: '03'
+ name: Choiseul
+ - abbr: '05'
+ name: Dennery
+ - abbr: '06'
+ name: Gros Islet
+ - abbr: '07'
+ name: Laborie
+ - abbr: '08'
+ name: Micoud
+ - abbr: '10'
+ name: Soufrière
+ - abbr: '11'
+ name: Vieux Fort
+ - iso: MF
+ iso3: MAF
+ name: Saint Martin (French part)
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: PM
+ iso3: SPM
+ name: Saint Pierre and Miquelon
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: VC
+ iso3: VCT
+ name: Saint Vincent and the Grenadines
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Charlotte
+ - abbr: '06'
+ name: Grenadines
+ - abbr: '02'
+ name: Saint Andrew
+ - abbr: '03'
+ name: Saint David
+ - abbr: '04'
+ name: Saint George
+ - abbr: '05'
+ name: Saint Patrick
+ - iso: WS
+ iso3: WSM
+ name: Samoa
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AA
+ name: A'ana
+ - abbr: AL
+ name: Aiga-i-le-Tai
+ - abbr: AT
+ name: Atua
+ - abbr: FA
+ name: Fa'asaleleaga
+ - abbr: GE
+ name: Gaga'emauga
+ - abbr: GI
+ name: Gagaifomauga
+ - abbr: PA
+ name: Palauli
+ - abbr: SA
+ name: Satupa'itea
+ - abbr: TU
+ name: Tuamasaga
+ - abbr: VF
+ name: Va'a-o-Fonoti
+ - abbr: VS
+ name: Vaisigano
+ - iso: SM
+ iso3: SMR
+ name: San Marino
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Acquaviva
+ - abbr: '06'
+ name: Borgo Maggiore
+ - abbr: '02'
+ name: Chiesanuova
+ - abbr: '03'
+ name: Domagnano
+ - abbr: '04'
+ name: Faetano
+ - abbr: '05'
+ name: Fiorentino
+ - abbr: '08'
+ name: Montegiardino
+ - abbr: '07'
+ name: San Marino
+ - abbr: '09'
+ name: Serravalle
+ - iso: ST
+ iso3: STP
+ name: Sao Tome and Principe
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '02'
+ name: Cantagalo
+ - abbr: '03'
+ name: Caué
+ - abbr: '04'
+ name: Lembá
+ - abbr: '05'
+ name: Lobata
+ - abbr: '06'
+ name: Mé-Zóchi
+ - abbr: P
+ name: Príncipe
+ - abbr: '01'
+ name: Água Grande
+ - iso: SA
+ iso3: SAU
+ name: Saudi Arabia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '14'
+ name: "'Asīr"
+ - abbr: '11'
+ name: Al Bāḩah
+ - abbr: '12'
+ name: Al Jawf
+ - abbr: '03'
+ name: Al Madinah
+ - abbr: '05'
+ name: Al Qasim
+ - abbr: '08'
+ name: Al Ḩudūd ash Shamālīyah
+ - abbr: '01'
+ name: Ar Riyāḑ
+ - abbr: '04'
+ name: Ash Sharqiyah
+ - abbr: '09'
+ name: Jāzān
+ - abbr: '02'
+ name: Makkah al Mukarramah
+ - abbr: '10'
+ name: Najrān
+ - abbr: '07'
+ name: Tabūk
+ - abbr: '06'
+ name: Ḩā'il
+ - iso: SN
+ iso3: SEN
+ name: Senegal
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: DK
+ name: Dakar
+ - abbr: DB
+ name: Diourbel
+ - abbr: FK
+ name: Fatick
+ - abbr: KA
+ name: Kaffrine
+ - abbr: KL
+ name: Kaolack
+ - abbr: KD
+ name: Kolda
+ - abbr: KE
+ name: Kédougou
+ - abbr: LG
+ name: Louga
+ - abbr: MT
+ name: Matam
+ - abbr: SL
+ name: Saint-Louis
+ - abbr: SE
+ name: Sédhiou
+ - abbr: TC
+ name: Tambacounda
+ - abbr: TH
+ name: Thiès
+ - abbr: ZG
+ name: Ziguinchor
+ - iso: RS
+ iso3: SRB
+ name: Serbia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '00'
+ name: Belgrade
+ - abbr: '14'
+ name: Bor
+ - abbr: '11'
+ name: Branicevo
+ - abbr: '23'
+ name: Jablanica
+ - abbr: '06'
+ name: Južna Backa
+ - abbr: '04'
+ name: Južni Banat
+ - abbr: '09'
+ name: Kolubara
+ - abbr: '25'
+ name: Kosovo
+ - abbr: '29'
+ name: Kosovo-Pomoravlje
+ - abbr: '28'
+ name: Kosovska Mitrovica
+ - abbr: '08'
+ name: Macva
+ - abbr: '17'
+ name: Moravica
+ - abbr: '20'
+ name: Nišava
+ - abbr: '24'
+ name: Pcinja
+ - abbr: '26'
+ name: Pec´
+ - abbr: '22'
+ name: Pirot
+ - abbr: '10'
+ name: Podunavlje
+ - abbr: '13'
+ name: Pomoravlje
+ - abbr: '27'
+ name: Prizren
+ - abbr: '19'
+ name: Rasina
+ - abbr: '18'
+ name: Raška
+ - abbr: '01'
+ name: Severna Backa
+ - abbr: '03'
+ name: Severni Banat
+ - abbr: '02'
+ name: Srednji Banat
+ - abbr: '07'
+ name: Srem
+ - abbr: '21'
+ name: Toplica
+ - abbr: '15'
+ name: Zajecar
+ - abbr: '05'
+ name: Zapadna Backa
+ - abbr: '16'
+ name: Zlatibor
+ - abbr: '12'
+ name: Šumadija
+ - abbr: VO
+ name: Војводина
+ - abbr: KM
+ name: Косово и Метохија
+ - iso: SC
+ iso3: SYC
+ name: Seychelles
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '02'
+ name: Anse Boileau
+ - abbr: '04'
+ name: Anse Louis
+ - abbr: '05'
+ name: Anse Royale
+ - abbr: '01'
+ name: Anse aux Pins
+ - abbr: '03'
+ name: Anse Étoile
+ - abbr: '06'
+ name: Baie Lazare
+ - abbr: '07'
+ name: Baie Sainte Anne
+ - abbr: '08'
+ name: Beau Vallon
+ - abbr: '09'
+ name: Bel Air
+ - abbr: '10'
+ name: Bel Ombre
+ - abbr: '11'
+ name: Cascade
+ - abbr: '12'
+ name: Glacis
+ - abbr: '13'
+ name: Grand' Anse (Mahé)
+ - abbr: '14'
+ name: Grand' Anse (Praslin)
+ - abbr: '26'
+ name: Ile Perseverance I
+ - abbr: '27'
+ name: Ile Perseverance II
+ - abbr: '15'
+ name: La Digue
+ - abbr: '16'
+ name: La Rivière Anglaise
+ - abbr: '24'
+ name: Les Mamelles
+ - abbr: '17'
+ name: Mont Buxton
+ - abbr: '18'
+ name: Mont Fleuri
+ - abbr: '19'
+ name: Plaisance
+ - abbr: '20'
+ name: Pointe La Rue
+ - abbr: '21'
+ name: Port Glaud
+ - abbr: '25'
+ name: Roche Caïman
+ - abbr: '22'
+ name: Saint Louis
+ - abbr: '23'
+ name: Takamaka
+ - iso: SL
+ iso3: SLE
+ name: Sierra Leone
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: E
+ name: Eastern
+ - abbr: NW
+ name: North Western
+ - abbr: "N"
+ name: Northern
+ - abbr: S
+ name: Southern
+ - abbr: W
+ name: Western Area (Freetown)
+ - iso: SG
+ iso3: SGP
+ name: Singapore
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Central Singapore
+ - abbr: '02'
+ name: North East
+ - abbr: '03'
+ name: North West
+ - abbr: '04'
+ name: South East
+ - abbr: '05'
+ name: South West
+ - iso: SX
+ iso3: SXM
+ name: Sint Maarten (Dutch part)
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: SK
+ iso3: SVK
+ name: Slovakia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BC
+ name: Banskobystrický kraj
+ - abbr: BL
+ name: Bratislavský kraj
+ - abbr: KI
+ name: Košický kraj
+ - abbr: NI
+ name: Nitriansky kraj
+ - abbr: PV
+ name: Prešovský kraj
+ - abbr: TC
+ name: Trenciansky kraj
+ - abbr: TA
+ name: Trnavský kraj
+ - abbr: ZI
+ name: Žilinský kraj
+ - iso: SI
+ iso3: SVN
+ name: Slovenia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '001'
+ name: Ajdovšcina
+ - abbr: '002'
+ name: Beltinci
+ - abbr: '148'
+ name: Benedikt
+ - abbr: '149'
+ name: Bistrica ob Sotli
+ - abbr: '003'
+ name: Bled
+ - abbr: '150'
+ name: Bloke
+ - abbr: '004'
+ name: Bohinj
+ - abbr: '005'
+ name: Borovnica
+ - abbr: '006'
+ name: Bovec
+ - abbr: '151'
+ name: Braslovce
+ - abbr: '007'
+ name: Brda
+ - abbr: '008'
+ name: Brezovica
+ - abbr: '009'
+ name: Brežice
+ - abbr: '152'
+ name: Cankova
+ - abbr: '011'
+ name: Celje
+ - abbr: '012'
+ name: Cerklje na Gorenjskem
+ - abbr: '013'
+ name: Cerknica
+ - abbr: '014'
+ name: Cerkno
+ - abbr: '153'
+ name: Cerkvenjak
+ - abbr: '015'
+ name: Crenšovci
+ - abbr: '016'
+ name: Crna na Koroškem
+ - abbr: '017'
+ name: Crnomelj
+ - abbr: '018'
+ name: Destrnik
+ - abbr: '019'
+ name: Divaca
+ - abbr: '154'
+ name: Dobje
+ - abbr: '020'
+ name: Dobrepolje
+ - abbr: '155'
+ name: Dobrna
+ - abbr: '021'
+ name: Dobrova-Polhov Gradec
+ - abbr: '156'
+ name: Dobrovnik/Dobronak
+ - abbr: '022'
+ name: Dol pri Ljubljani
+ - abbr: '157'
+ name: Dolenjske Toplice
+ - abbr: '023'
+ name: Domžale
+ - abbr: '024'
+ name: Dornava
+ - abbr: '025'
+ name: Dravograd
+ - abbr: '026'
+ name: Duplek
+ - abbr: '027'
+ name: Gorenja vas-Poljane
+ - abbr: '028'
+ name: Gorišnica
+ - abbr: '029'
+ name: Gornja Radgona
+ - abbr: '030'
+ name: Gornji Grad
+ - abbr: '031'
+ name: Gornji Petrovci
+ - abbr: '158'
+ name: Grad
+ - abbr: '032'
+ name: Grosuplje
+ - abbr: '159'
+ name: Hajdina
+ - abbr: '160'
+ name: Hoce-Slivnica
+ - abbr: '161'
+ name: Hodoš/Hodos
+ - abbr: '162'
+ name: Horjul
+ - abbr: '034'
+ name: Hrastnik
+ - abbr: '035'
+ name: Hrpelje-Kozina
+ - abbr: '036'
+ name: Idrija
+ - abbr: '037'
+ name: Ig
+ - abbr: '038'
+ name: Ilirska Bistrica
+ - abbr: '039'
+ name: Ivancna Gorica
+ - abbr: '040'
+ name: Izola/Isola
+ - abbr: '041'
+ name: Jesenice
+ - abbr: '163'
+ name: Jezersko
+ - abbr: '042'
+ name: Juršinci
+ - abbr: '043'
+ name: Kamnik
+ - abbr: '044'
+ name: Kanal
+ - abbr: '045'
+ name: Kidricevo
+ - abbr: '046'
+ name: Kobarid
+ - abbr: '047'
+ name: Kobilje
+ - abbr: '048'
+ name: Kocevje
+ - abbr: '049'
+ name: Komen
+ - abbr: '164'
+ name: Komenda
+ - abbr: '050'
+ name: Koper/Capodistria
+ - abbr: '165'
+ name: Kostel
+ - abbr: '051'
+ name: Kozje
+ - abbr: '052'
+ name: Kranj
+ - abbr: '053'
+ name: Kranjska Gora
+ - abbr: '166'
+ name: Križevci
+ - abbr: '054'
+ name: Krško
+ - abbr: '055'
+ name: Kungota
+ - abbr: '056'
+ name: Kuzma
+ - abbr: '057'
+ name: Laško
+ - abbr: '058'
+ name: Lenart
+ - abbr: '059'
+ name: Lendava/Lendva
+ - abbr: '060'
+ name: Litija
+ - abbr: '061'
+ name: Ljubljana
+ - abbr: '062'
+ name: Ljubno
+ - abbr: '063'
+ name: Ljutomer
+ - abbr: '064'
+ name: Logatec
+ - abbr: '167'
+ name: Lovrenc na Pohorju
+ - abbr: '065'
+ name: Loška dolina
+ - abbr: '066'
+ name: Loški Potok
+ - abbr: '067'
+ name: Luce
+ - abbr: '068'
+ name: Lukovica
+ - abbr: '069'
+ name: Majšperk
+ - abbr: '070'
+ name: Maribor
+ - abbr: '168'
+ name: Markovci
+ - abbr: '071'
+ name: Medvode
+ - abbr: '072'
+ name: Mengeš
+ - abbr: '073'
+ name: Metlika
+ - abbr: '074'
+ name: Mežica
+ - abbr: '169'
+ name: Miklavž na Dravskem polju
+ - abbr: '075'
+ name: Miren-Kostanjevica
+ - abbr: '212'
+ name: Mirna
+ - abbr: '170'
+ name: Mirna Pec
+ - abbr: '076'
+ name: Mislinja
+ - abbr: '077'
+ name: Moravce
+ - abbr: '078'
+ name: Moravske Toplice
+ - abbr: '079'
+ name: Mozirje
+ - abbr: '080'
+ name: Murska Sobota
+ - abbr: '081'
+ name: Muta
+ - abbr: '082'
+ name: Naklo
+ - abbr: '083'
+ name: Nazarje
+ - abbr: '084'
+ name: Nova Gorica
+ - abbr: '085'
+ name: Novo mesto
+ - abbr: '213'
+ name: Občina Ankaran
+ - abbr: '195'
+ name: Občina Apače
+ - abbr: '196'
+ name: Občina Cirkulane
+ - abbr: '207'
+ name: Občina Gorje
+ - abbr: '197'
+ name: Občina Kostanjevica na Krki
+ - abbr: '208'
+ name: Občina Log - Dragomer
+ - abbr: '198'
+ name: Občina Makole
+ - abbr: '199'
+ name: Občina Mokronog - Trebelno
+ - abbr: '200'
+ name: Občina Poljčane
+ - abbr: '201'
+ name: Občina Renče - Vogrsko
+ - abbr: '209'
+ name: Občina Rečica ob Savinji
+ - abbr: '202'
+ name: Občina Središče ob Dravi
+ - abbr: '203'
+ name: Občina Straža
+ - abbr: '204'
+ name: Občina Sveta Trojica v Slovenskih goricah
+ - abbr: '210'
+ name: Občina Sveti Jurij v Slovenskih goricah
+ - abbr: '205'
+ name: Občina Sveti Tomaž
+ - abbr: '211'
+ name: Občina Šentrupert
+ - abbr: '206'
+ name: Občina Šmarješke Toplice
+ - abbr: '086'
+ name: Odranci
+ - abbr: '171'
+ name: Oplotnica
+ - abbr: '087'
+ name: Ormož
+ - abbr: '088'
+ name: Osilnica
+ - abbr: '089'
+ name: Pesnica
+ - abbr: '090'
+ name: Piran/Pirano
+ - abbr: '091'
+ name: Pivka
+ - abbr: '092'
+ name: Podcetrtek
+ - abbr: '172'
+ name: Podlehnik
+ - abbr: '093'
+ name: Podvelka
+ - abbr: '173'
+ name: Polzela
+ - abbr: '094'
+ name: Postojna
+ - abbr: '174'
+ name: Prebold
+ - abbr: '095'
+ name: Preddvor
+ - abbr: '175'
+ name: Prevalje
+ - abbr: '096'
+ name: Ptuj
+ - abbr: '097'
+ name: Puconci
+ - abbr: '098'
+ name: Race-Fram
+ - abbr: '099'
+ name: Radece
+ - abbr: '100'
+ name: Radenci
+ - abbr: '101'
+ name: Radlje ob Dravi
+ - abbr: '102'
+ name: Radovljica
+ - abbr: '103'
+ name: Ravne na Koroškem
+ - abbr: '176'
+ name: Razkrižje
+ - abbr: '104'
+ name: Ribnica
+ - abbr: '177'
+ name: Ribnica na Pohorju
+ - abbr: '107'
+ name: Rogatec
+ - abbr: '106'
+ name: Rogaška Slatina
+ - abbr: '105'
+ name: Rogašovci
+ - abbr: '108'
+ name: Ruše
+ - abbr: '178'
+ name: Selnica ob Dravi
+ - abbr: '109'
+ name: Semic
+ - abbr: '110'
+ name: Sevnica
+ - abbr: '111'
+ name: Sežana
+ - abbr: '112'
+ name: Slovenj Gradec
+ - abbr: '113'
+ name: Slovenska Bistrica
+ - abbr: '114'
+ name: Slovenske Konjice
+ - abbr: '179'
+ name: Sodražica
+ - abbr: '180'
+ name: Solcava
+ - abbr: '115'
+ name: Starše
+ - abbr: '181'
+ name: Sveta Ana
+ - abbr: '182'
+ name: Sveti Andraž v Slovenskih goricah
+ - abbr: '116'
+ name: Sveti Jurij
+ - abbr: '184'
+ name: Tabor
+ - abbr: '010'
+ name: Tišina
+ - abbr: '128'
+ name: Tolmin
+ - abbr: '129'
+ name: Trbovlje
+ - abbr: '130'
+ name: Trebnje
+ - abbr: '185'
+ name: Trnovska vas
+ - abbr: '186'
+ name: Trzin
+ - abbr: '131'
+ name: Tržic
+ - abbr: '132'
+ name: Turnišce
+ - abbr: '133'
+ name: Velenje
+ - abbr: '187'
+ name: Velika Polana
+ - abbr: '134'
+ name: Velike Lašce
+ - abbr: '188'
+ name: Veržej
+ - abbr: '135'
+ name: Videm
+ - abbr: '136'
+ name: Vipava
+ - abbr: '137'
+ name: Vitanje
+ - abbr: '138'
+ name: Vodice
+ - abbr: '139'
+ name: Vojnik
+ - abbr: '189'
+ name: Vransko
+ - abbr: '140'
+ name: Vrhnika
+ - abbr: '141'
+ name: Vuzenica
+ - abbr: '142'
+ name: Zagorje ob Savi
+ - abbr: '143'
+ name: Zavrc
+ - abbr: '144'
+ name: Zrece
+ - abbr: '033'
+ name: Šalovci
+ - abbr: '183'
+ name: Šempeter-Vrtojba
+ - abbr: '117'
+ name: Šencur
+ - abbr: '118'
+ name: Šentilj
+ - abbr: '119'
+ name: Šentjernej
+ - abbr: '120'
+ name: Šentjur pri Celju
+ - abbr: '121'
+ name: Škocjan
+ - abbr: '122'
+ name: Škofja Loka
+ - abbr: '123'
+ name: Škofljica
+ - abbr: '124'
+ name: Šmarje pri Jelšah
+ - abbr: '125'
+ name: Šmartno ob Paki
+ - abbr: '194'
+ name: Šmartno pri Litiji
+ - abbr: '126'
+ name: Šoštanj
+ - abbr: '127'
+ name: Štore
+ - abbr: '190'
+ name: Žalec
+ - abbr: '146'
+ name: Železniki
+ - abbr: '191'
+ name: Žetale
+ - abbr: '147'
+ name: Žiri
+ - abbr: '192'
+ name: Žirovnica
+ - abbr: '193'
+ name: Žužemberk
+ - iso: SB
+ iso3: SLB
+ name: Solomon Islands
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: CT
+ name: Capital Territory (Honiara)
+ - abbr: CE
+ name: Central
+ - abbr: CH
+ name: Choiseul
+ - abbr: GU
+ name: Guadalcanal
+ - abbr: IS
+ name: Isabel
+ - abbr: MK
+ name: Makira
+ - abbr: ML
+ name: Malaita
+ - abbr: RB
+ name: Rennell and Bellona
+ - abbr: TE
+ name: Temotu
+ - abbr: WE
+ name: Western
+ - iso: SO
+ iso3: SOM
+ name: Somalia
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AW
+ name: Awdal
+ - abbr: BK
+ name: Bakool
+ - abbr: BN
+ name: Banaadir
+ - abbr: BR
+ name: Bari
+ - abbr: BY
+ name: Bay
+ - abbr: GA
+ name: Galguduud
+ - abbr: GE
+ name: Gedo
+ - abbr: HI
+ name: Hiiraan
+ - abbr: JD
+ name: Jubbada Dhexe
+ - abbr: JH
+ name: Jubbada Hoose
+ - abbr: MU
+ name: Mudug
+ - abbr: NU
+ name: Nugaal
+ - abbr: SA
+ name: Sanaag
+ - abbr: SD
+ name: Shabeellaha Dhexe
+ - abbr: SH
+ name: Shabeellaha Hoose
+ - abbr: SO
+ name: Sool
+ - abbr: TO
+ name: Togdheer
+ - abbr: WO
+ name: Woqooyi Galbeed
+ - iso: ZA
+ iso3: ZAF
+ name: South Africa
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: EC
+ name: Eastern Cape
+ - abbr: FS
+ name: Free State
+ - abbr: GP
+ name: Gauteng
+ - abbr: ZN
+ name: KwaZulu-Natal
+ - abbr: LP
+ name: Limpopo
+ - abbr: MP
+ name: Mpumalanga
+ - abbr: NW
+ name: North West
+ - abbr: NC
+ name: Northern Cape
+ - abbr: WC
+ name: Western Cape
+ - iso: KR
+ iso3: KOR
+ name: South Korea
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '26'
+ name: Busan Gwang'yeogsi [Pusan-Kwangyokshi]
+ - abbr: '43'
+ name: Chungcheongbugdo [Ch'ungch'ongbuk-do]
+ - abbr: '44'
+ name: Chungcheongnamdo [Ch'ungch'ongnam-do]
+ - abbr: '27'
+ name: Daegu Gwang'yeogsi [Taegu-Kwangyokshi]
+ - abbr: '30'
+ name: Daejeon Gwang'yeogsi [Taejon-Kwangyokshi]
+ - abbr: '42'
+ name: Gang'weondo [Kang-won-do]
+ - abbr: '29'
+ name: Gwangju Gwang'yeogsi [Kwangju-Kwangyokshi]
+ - abbr: '41'
+ name: Gyeonggido [Kyonggi-do]
+ - abbr: '47'
+ name: Gyeongsangbugdo [Kyongsangbuk-do]
+ - abbr: '48'
+ name: Gyeongsangnamdo [Kyongsangnam-do]
+ - abbr: '28'
+ name: Incheon Gwang'yeogsi [Inch'n-Kwangyokshi]
+ - abbr: '49'
+ name: Jejudo [Cheju-do]
+ - abbr: '45'
+ name: Jeonrabugdo[Chollabuk-do]
+ - abbr: '46'
+ name: Jeonranamdo [Chollanam-do]
+ - abbr: '11'
+ name: Seoul Teugbyeolsi [Seoul-T'ukpyolshi]
+ - abbr: '31'
+ name: Ulsan Gwang'yeogsi [Ulsan-Kwangyokshi]
+ - abbr: '50'
+ name: 세종특별자치시
+ - iso: SS
+ iso3: SSD
+ name: South Sudan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: NU
+ name: أعالي النيل
+ - abbr: LK
+ name: البحيرات
+ - abbr: UY
+ name: الوحدة
+ - abbr: JG
+ name: جونقلي
+ - abbr: EE
+ name: شرق الاستوائية
+ - abbr: BN
+ name: شمال بحر الغزال
+ - abbr: EW
+ name: غرب الاستوائية
+ - abbr: BW
+ name: غرب بحر الغزال
+ - abbr: WR
+ name: واراب
+ - abbr: EC
+ name: وسط الاستوائية
+ - iso: ES
+ iso3: ESP
+ name: Spain
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AB
+ name: Albacete
+ - abbr: A
+ name: Alicante/Alacant
+ - abbr: AL
+ name: Almería
+ - abbr: AN
+ name: Andalucía
+ - abbr: VI
+ name: Araba/Álava
+ - abbr: AR
+ name: Aragón
+ - abbr: O
+ name: Asturias
+ - abbr: BA
+ name: Badajoz
+ - abbr: PM
+ name: Balears, Illes
+ - abbr: B
+ name: Barcelona
+ - abbr: BI
+ name: Bizkaia
+ - abbr: BU
+ name: Burgos
+ - abbr: CN
+ name: Canary Islands
+ - abbr: CB
+ name: Cantabria
+ - abbr: S
+ name: Cantabria
+ - abbr: CS
+ name: Castellón/Castelló
+ - abbr: CL
+ name: Castilla y León
+ - abbr: CM
+ name: Castilla-La Mancha
+ - abbr: CT
+ name: Cataluña
+ - abbr: CE
+ name: Ceuta
+ - abbr: CR
+ name: Ciudad Real
+ - abbr: VC
+ name: Comunidad Valenciana
+ - abbr: MD
+ name: Comunidad de Madrid
+ - abbr: C
+ name: Coruña, A
+ - abbr: CU
+ name: Cuenca
+ - abbr: CC
+ name: Cáceres
+ - abbr: CA
+ name: Cádiz
+ - abbr: CO
+ name: Córdoba
+ - abbr: EX
+ name: Extremadura
+ - abbr: GA
+ name: Galicia
+ - abbr: SS
+ name: Gipuzkoa
+ - abbr: GI
+ name: Girona
+ - abbr: GR
+ name: Granada
+ - abbr: GU
+ name: Guadalajara
+ - abbr: H
+ name: Huelva
+ - abbr: HU
+ name: Huesca
+ - abbr: IB
+ name: Islas Baleares
+ - abbr: J
+ name: Jaén
+ - abbr: RI
+ name: La Rioja
+ - abbr: LE
+ name: León
+ - abbr: L
+ name: Lleida
+ - abbr: LU
+ name: Lugo
+ - abbr: M
+ name: Madrid
+ - abbr: ML
+ name: Melilla
+ - abbr: MU
+ name: Murcia
+ - abbr: MA
+ name: Málaga
+ - abbr: NC
+ name: Navarra
+ - abbr: NA
+ name: Navarra
+ - abbr: OR
+ name: Ourense
+ - abbr: P
+ name: Palencia
+ - abbr: GC
+ name: Palmas, Las
+ - abbr: PV
+ name: País Vasco
+ - abbr: PO
+ name: Pontevedra
+ - abbr: AS
+ name: Principado de Asturias
+ - abbr: MC
+ name: Región de Murcia
+ - abbr: LO
+ name: Rioja, La
+ - abbr: SA
+ name: Salamanca
+ - abbr: TF
+ name: Santa Cruz de Tenerife
+ - abbr: SG
+ name: Segovia
+ - abbr: SE
+ name: Sevilla
+ - abbr: SO
+ name: Soria
+ - abbr: T
+ name: Tarragona
+ - abbr: TE
+ name: Teruel
+ - abbr: TO
+ name: Toledo
+ - abbr: V
+ name: Valencia/València
+ - abbr: VA
+ name: Valladolid
+ - abbr: ZA
+ name: Zamora
+ - abbr: Z
+ name: Zaragoza
+ - abbr: AV
+ name: Ávila
+ - iso: LK
+ iso3: LKA
+ name: Sri Lanka
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '52'
+ name: Ampara
+ - abbr: '71'
+ name: Anuradhapura
+ - abbr: '81'
+ name: Badulla
+ - abbr: '51'
+ name: Batticaloa
+ - abbr: '11'
+ name: Colombo
+ - abbr: '31'
+ name: Galle
+ - abbr: '12'
+ name: Gampaha
+ - abbr: '33'
+ name: Hambantota
+ - abbr: '41'
+ name: Jaffna
+ - abbr: '13'
+ name: Kalutara
+ - abbr: '21'
+ name: Kandy
+ - abbr: '92'
+ name: Kegalla
+ - abbr: '42'
+ name: Kilinochchi
+ - abbr: '61'
+ name: Kurunegala
+ - abbr: '43'
+ name: Mannar
+ - abbr: '22'
+ name: Matale
+ - abbr: '32'
+ name: Matara
+ - abbr: '82'
+ name: Monaragala
+ - abbr: '45'
+ name: Mullaittivu
+ - abbr: '23'
+ name: Nuwara Eliya
+ - abbr: '72'
+ name: Polonnaruwa
+ - abbr: '62'
+ name: Puttalam
+ - abbr: '91'
+ name: Ratnapura
+ - abbr: '53'
+ name: Trincomalee
+ - abbr: '44'
+ name: Vavuniya
+ - abbr: '4'
+ name: උතුරු පළාත
+ - abbr: '7'
+ name: උතුරු මැද පළාත
+ - abbr: '8'
+ name: ඌව පළාත
+ - abbr: '3'
+ name: දකුණු පළාත
+ - abbr: '5'
+ name: නැගෙනහිර පළාත, ශ් රී ලංකාව
+ - abbr: '1'
+ name: බස්නාහිර පළාත, ශ් රී ලංකාව
+ - abbr: '2'
+ name: මධ්‍යම පළාත, ශ්‍රී ලංකාව
+ - abbr: '6'
+ name: වයඹ පළාත, ශ්‍රී ලංකාව
+ - abbr: '9'
+ name: සබරගමුව පළාත
+ - iso: SD
+ iso3: SDN
+ name: Sudan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: RS
+ name: Al Baḩr al Aḩmar
+ - abbr: GZ
+ name: Al Jazīrah
+ - abbr: KH
+ name: Al Kharţūm
+ - abbr: GD
+ name: Al Qaḑārif
+ - abbr: NW
+ name: An Nīl al Abyaḑ
+ - abbr: NB
+ name: An Nīl al Azraq
+ - abbr: 'NO'
+ name: Ash Shamālīyah
+ - abbr: DW
+ name: Gharb Dārfūr
+ - abbr: GK
+ name: Gharb Kurdufān
+ - abbr: DS
+ name: Janūb Dārfūr
+ - abbr: KS
+ name: Janūb Kurdufān
+ - abbr: KA
+ name: Kassalā
+ - abbr: NR
+ name: Nahr an Nīl
+ - abbr: DN
+ name: Shamāl Dārfūr
+ - abbr: DE
+ name: Sharq Dārfūr
+ - abbr: KN
+ name: Shiamāl Kurdufān
+ - abbr: SI
+ name: Sinnār
+ - abbr: DC
+ name: Wasaţ Dārfūr Zālinjay
+ - iso: SR
+ iso3: SUR
+ name: Suriname
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BR
+ name: Brokopondo
+ - abbr: CM
+ name: Commewijne
+ - abbr: CR
+ name: Coronie
+ - abbr: MA
+ name: Marowijne
+ - abbr: NI
+ name: Nickerie
+ - abbr: PR
+ name: Para
+ - abbr: PM
+ name: Paramaribo
+ - abbr: SA
+ name: Saramacca
+ - abbr: SI
+ name: Sipaliwini
+ - abbr: WA
+ name: Wanica
+ - iso: SJ
+ iso3: SJM
+ name: Svalbard and Jan Mayen
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: SE
+ iso3: SWE
+ name: Sweden
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: K
+ name: Blekinge län
+ - abbr: W
+ name: Dalarnas län
+ - abbr: I
+ name: Gotlands län
+ - abbr: X
+ name: Gävleborgs län
+ - abbr: "N"
+ name: Hallands län
+ - abbr: Z
+ name: Jämtlands län
+ - abbr: F
+ name: Jönköpings län
+ - abbr: H
+ name: Kalmar län
+ - abbr: G
+ name: Kronobergs län
+ - abbr: BD
+ name: Norrbottens län
+ - abbr: M
+ name: Skåne län
+ - abbr: AB
+ name: Stockholms län
+ - abbr: D
+ name: Södermanlands län
+ - abbr: C
+ name: Uppsala län
+ - abbr: S
+ name: Värmlands län
+ - abbr: AC
+ name: Västerbottens län
+ - abbr: "Y"
+ name: Västernorrlands län
+ - abbr: U
+ name: Västmanlands län
+ - abbr: O
+ name: Västra Götalands län
+ - abbr: T
+ name: Örebro län
+ - abbr: E
+ name: Östergötlands län
+ - iso: CH
+ iso3: CHE
+ name: Switzerland
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AG
+ name: Aargau (de)
+ - abbr: AR
+ name: Appenzell Ausserrhoden (de)
+ - abbr: AI
+ name: Appenzell Innerrhoden (de)
+ - abbr: BL
+ name: Basel-Landschaft (de)
+ - abbr: BS
+ name: Basel-Stadt (de)
+ - abbr: BE
+ name: Bern (de)
+ - abbr: FR
+ name: Fribourg (fr)
+ - abbr: GE
+ name: Genève (fr)
+ - abbr: GL
+ name: Glarus (de)
+ - abbr: GR
+ name: Graubünden (de)
+ - abbr: JU
+ name: Jura (fr)
+ - abbr: LU
+ name: Luzern (de)
+ - abbr: NE
+ name: Neuchâtel (fr)
+ - abbr: NW
+ name: Nidwalden (de)
+ - abbr: OW
+ name: Obwalden (de)
+ - abbr: SG
+ name: Sankt Gallen (de)
+ - abbr: SH
+ name: Schaffhausen (de)
+ - abbr: SZ
+ name: Schwyz (de)
+ - abbr: SO
+ name: Solothurn (de)
+ - abbr: TG
+ name: Thurgau (de)
+ - abbr: TI
+ name: Ticino (it)
+ - abbr: UR
+ name: Uri (de)
+ - abbr: VS
+ name: Valais (fr)
+ - abbr: VD
+ name: Vaud (fr)
+ - abbr: ZG
+ name: Zug (de)
+ - abbr: ZH
+ name: Zürich (de)
+ - iso: SY
+ iso3: SYR
+ name: Syrian Arab Republic
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: LA
+ name: Al Ladhiqiyah
+ - abbr: QU
+ name: Al Qunaytirah
+ - abbr: HA
+ name: Al Ḩasakah
+ - abbr: RA
+ name: Ar Raqqah
+ - abbr: SU
+ name: As Suwayda'
+ - abbr: DR
+ name: Dar'ā
+ - abbr: DY
+ name: Dayr az Zawr
+ - abbr: DI
+ name: Dimashq
+ - abbr: ID
+ name: Idlib
+ - abbr: RD
+ name: Rif Dimashq
+ - abbr: TA
+ name: Tartus
+ - abbr: HL
+ name: Ḩalab
+ - abbr: HM
+ name: Ḩamāh
+ - abbr: HI
+ name: Ḩimş
+ - iso: TW
+ iso3: TWN
+ name: Taiwan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: CHA
+ name: Changhua
+ - abbr: CYQ
+ name: Chiayi
+ - abbr: CYI
+ name: Chiayi Municipality
+ - abbr: HSQ
+ name: Hsinchu
+ - abbr: HSZ
+ name: Hsinchu Municipality
+ - abbr: HUA
+ name: Hualien
+ - abbr: ILA
+ name: Ilan
+ - abbr: KHH
+ name: Kaohsiung Special Municipality
+ - abbr: KEE
+ name: Keelung Municipality
+ - abbr: MIA
+ name: Miaoli
+ - abbr: NAN
+ name: Nantou
+ - abbr: NWT
+ name: New Taipei
+ - abbr: PEN
+ name: Penghu
+ - abbr: PIF
+ name: Pingtung
+ - abbr: TXG
+ name: Taichung Municipality
+ - abbr: TNN
+ name: Tainan Municipality
+ - abbr: TPE
+ name: Taipei Special Municipality
+ - abbr: TTT
+ name: Taitung
+ - abbr: TAO
+ name: Taoyuan
+ - abbr: YUN
+ name: Yunlin
+ - abbr: LIE
+ name: 連江縣
+ - abbr: KIN
+ name: 金門縣
+ - iso: TJ
+ iso3: TJK
+ name: Tajikistan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: DU
+ name: Dushanbe
+ - abbr: GB
+ name: Gorno-Badakhshan
+ - abbr: KT
+ name: Khatlon
+ - abbr: RA
+ name: Nohiyahoi Tobei Jumhurí
+ - abbr: SU
+ name: Sughd
+ - iso: TZ
+ iso3: TZA
+ name: Tanzania
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '01'
+ name: Arusha
+ - abbr: '02'
+ name: Dar es Salaam
+ - abbr: '03'
+ name: Dodoma
+ - abbr: '04'
+ name: Iringa
+ - abbr: '05'
+ name: Kagera
+ - abbr: '06'
+ name: Kaskazini Pemba
+ - abbr: '07'
+ name: Kaskazini Unguja
+ - abbr: '08'
+ name: Kigoma
+ - abbr: '09'
+ name: Kilimanjaro
+ - abbr: '10'
+ name: Kusini Pemba
+ - abbr: '11'
+ name: Kusini Unguja
+ - abbr: '12'
+ name: Lindi
+ - abbr: '26'
+ name: Manyara
+ - abbr: '13'
+ name: Mara
+ - abbr: '14'
+ name: Mbeya
+ - abbr: '15'
+ name: Mjini Magharibi
+ - abbr: '27'
+ name: Mkoa wa Geita
+ - abbr: '28'
+ name: Mkoa wa Katavi
+ - abbr: '29'
+ name: Mkoa wa Njombe
+ - abbr: '30'
+ name: Mkoa wa Simiyu
+ - abbr: '16'
+ name: Morogoro
+ - abbr: '17'
+ name: Mtwara
+ - abbr: '18'
+ name: Mwanza
+ - abbr: '19'
+ name: Pwani
+ - abbr: '20'
+ name: Rukwa
+ - abbr: '21'
+ name: Ruvuma
+ - abbr: '22'
+ name: Shinyanga
+ - abbr: '23'
+ name: Singida
+ - abbr: '31'
+ name: Songwe
+ - abbr: '24'
+ name: Tabora
+ - abbr: '25'
+ name: Tanga
+ - iso: TH
+ iso3: THA
+ name: Thailand
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: '37'
+ name: Amnat Charoen
+ - abbr: '15'
+ name: Ang Thong
+ - abbr: '31'
+ name: Buri Ram
+ - abbr: '24'
+ name: Chachoengsao
+ - abbr: '18'
+ name: Chai Nat
+ - abbr: '36'
+ name: Chaiyaphum
+ - abbr: '22'
+ name: Chanthaburi
+ - abbr: '50'
+ name: Chiang Mai
+ - abbr: '57'
+ name: Chiang Rai
+ - abbr: '20'
+ name: Chon Buri
+ - abbr: '86'
+ name: Chumphon
+ - abbr: '46'
+ name: Kalasin
+ - abbr: '62'
+ name: Kamphaeng Phet
+ - abbr: '71'
+ name: Kanchanaburi
+ - abbr: '40'
+ name: Khon Kaen
+ - abbr: '81'
+ name: Krabi
+ - abbr: '10'
+ name: Krung Thep Maha Nakhon [Bangkok]
+ - abbr: '52'
+ name: Lampang
+ - abbr: '51'
+ name: Lamphun
+ - abbr: '42'
+ name: Loei
+ - abbr: '16'
+ name: Lop Buri
+ - abbr: '58'
+ name: Mae Hong Son
+ - abbr: '44'
+ name: Maha Sarakham
+ - abbr: '49'
+ name: Mukdahan
+ - abbr: '26'
+ name: Nakhon Nayok
+ - abbr: '73'
+ name: Nakhon Pathom
+ - abbr: '48'
+ name: Nakhon Phanom
+ - abbr: '30'
+ name: Nakhon Ratchasima
+ - abbr: '60'
+ name: Nakhon Sawan
+ - abbr: '80'
+ name: Nakhon Si Thammarat
+ - abbr: '55'
+ name: Nan
+ - abbr: '96'
+ name: Narathiwat
+ - abbr: '39'
+ name: Nong Bua Lam Phu
+ - abbr: '43'
+ name: Nong Khai
+ - abbr: '12'
+ name: Nonthaburi
+ - abbr: '13'
+ name: Pathum Thani
+ - abbr: '94'
+ name: Pattani
+ - abbr: '82'
+ name: Phangnga
+ - abbr: '93'
+ name: Phatthalung
+ - abbr: S
+ name: Phatthaya
+ - abbr: '56'
+ name: Phayao
+ - abbr: '67'
+ name: Phetchabun
+ - abbr: '76'
+ name: Phetchaburi
+ - abbr: '66'
+ name: Phichit
+ - abbr: '65'
+ name: Phitsanulok
+ - abbr: '14'
+ name: Phra Nakhon Si Ayutthaya
+ - abbr: '54'
+ name: Phrae
+ - abbr: '83'
+ name: Phuket
+ - abbr: '25'
+ name: Prachin Buri
+ - abbr: '77'
+ name: Prachuap Khiri Khan
+ - abbr: '85'
+ name: Ranong
+ - abbr: '70'
+ name: Ratchaburi
+ - abbr: '21'
+ name: Rayong
+ - abbr: '45'
+ name: Roi Et
+ - abbr: '27'
+ name: Sa Kaeo
+ - abbr: '47'
+ name: Sakon Nakhon
+ - abbr: '11'
+ name: Samut Prakan
+ - abbr: '74'
+ name: Samut Sakhon
+ - abbr: '75'
+ name: Samut Songkhram
+ - abbr: '19'
+ name: Saraburi
+ - abbr: '91'
+ name: Satun
+ - abbr: '33'
+ name: Si Sa Ket
+ - abbr: '17'
+ name: Sing Buri
+ - abbr: '90'
+ name: Songkhla
+ - abbr: '64'
+ name: Sukhothai
+ - abbr: '72'
+ name: Suphan Buri
+ - abbr: '84'
+ name: Surat Thani
+ - abbr: '32'
+ name: Surin
+ - abbr: '63'
+ name: Tak
+ - abbr: '92'
+ name: Trang
+ - abbr: '23'
+ name: Trat
+ - abbr: '34'
+ name: Ubon Ratchathani
+ - abbr: '41'
+ name: Udon Thani
+ - abbr: '61'
+ name: Uthai Thani
+ - abbr: '53'
+ name: Uttaradit
+ - abbr: '95'
+ name: Yala
+ - abbr: '35'
+ name: Yasothon
+ - abbr: '38'
+ name: จังหวัดบึงกาฬ
+ - iso: TL
+ iso3: TLS
+ name: Timor-Leste
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AL
+ name: Aileu
+ - abbr: AN
+ name: Ainaro
+ - abbr: BA
+ name: Baucau
+ - abbr: BO
+ name: Bobonaro
+ - abbr: CO
+ name: Cova Lima
+ - abbr: DI
+ name: Dili
+ - abbr: ER
+ name: Ermera
+ - abbr: LA
+ name: Lautem
+ - abbr: LI
+ name: Liquiça
+ - abbr: MT
+ name: Manatuto
+ - abbr: MF
+ name: Manufahi
+ - abbr: OE
+ name: Oecussi
+ - abbr: VI
+ name: Viqueque
+ - iso: TG
+ iso3: TGO
+ name: Togo
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: C
+ name: Centre
+ - abbr: K
+ name: Kara
+ - abbr: M
+ name: Maritime (Région)
+ - abbr: P
+ name: Plateaux
+ - abbr: S
+ name: Savannes
+ - iso: TK
+ iso3: TKL
+ name: Tokelau
+ states_required: false
+ zipcode_required: false
+ states: []
+ - iso: TO
+ iso3: TON
+ name: Tonga
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '01'
+ name: "'Eua"
+ - abbr: '02'
+ name: Ha'apai
+ - abbr: '03'
+ name: Niuas
+ - abbr: '04'
+ name: Tongatapu
+ - abbr: '05'
+ name: Vava'u
+ - iso: TT
+ iso3: TTO
+ name: Trinidad and Tobago
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: ARI
+ name: Arima
+ - abbr: CHA
+ name: Chaguanas
+ - abbr: CTT
+ name: Couva-Tabaquite-Talparo
+ - abbr: DMN
+ name: Diego Martin
+ - abbr: MRC
+ name: Mayaro-Rio Claro
+ - abbr: PED
+ name: Penal-Debe
+ - abbr: PTF
+ name: Point Fortin
+ - abbr: POS
+ name: Port of Spain
+ - abbr: PRT
+ name: Princes Town
+ - abbr: SFO
+ name: San Fernando
+ - abbr: SJL
+ name: San Juan-Laventille
+ - abbr: SGE
+ name: Sangre Grande
+ - abbr: SIP
+ name: Siparia
+ - abbr: TOB
+ name: Tobago
+ - abbr: TUP
+ name: Tunapuna-Piarco
+ - iso: TN
+ iso3: TUN
+ name: Tunisia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '13'
+ name: Ben Arous
+ - abbr: '23'
+ name: Bizerte
+ - abbr: '31'
+ name: Béja
+ - abbr: '81'
+ name: Gabès
+ - abbr: '71'
+ name: Gafsa
+ - abbr: '32'
+ name: Jendouba
+ - abbr: '41'
+ name: Kairouan
+ - abbr: '42'
+ name: Kasserine
+ - abbr: '73'
+ name: Kebili
+ - abbr: '12'
+ name: L'Ariana
+ - abbr: '14'
+ name: La Manouba
+ - abbr: '33'
+ name: Le Kef
+ - abbr: '53'
+ name: Mahdia
+ - abbr: '82'
+ name: Medenine
+ - abbr: '52'
+ name: Monastir
+ - abbr: '21'
+ name: Nabeul
+ - abbr: '61'
+ name: Sfax
+ - abbr: '43'
+ name: Sidi Bouzid
+ - abbr: '34'
+ name: Siliana
+ - abbr: '51'
+ name: Sousse
+ - abbr: '83'
+ name: Tataouine
+ - abbr: '72'
+ name: Tozeur
+ - abbr: '11'
+ name: Tunis
+ - abbr: '22'
+ name: Zaghouan
+ - iso: TM
+ iso3: TKM
+ name: Turkmenistan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: A
+ name: Ahal
+ - abbr: S
+ name: Aşgabat
+ - abbr: B
+ name: Balkan
+ - abbr: D
+ name: Dasoguz
+ - abbr: L
+ name: Lebap
+ - abbr: M
+ name: Mary
+ - iso: TC
+ iso3: TCA
+ name: Turks and Caicos Islands
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: TV
+ iso3: TUV
+ name: Tuvalu
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: FUN
+ name: Funafuti
+ - abbr: NMG
+ name: Nanumanga
+ - abbr: NMA
+ name: Nanumea
+ - abbr: NIT
+ name: Niutao
+ - abbr: NUI
+ name: Nui
+ - abbr: NKF
+ name: Nukufetau
+ - abbr: NKL
+ name: Nukulaelae
+ - abbr: VAI
+ name: Vaitupu
+ - iso: TR
+ iso3: TUR
+ name: Türkiye
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '01'
+ name: Adana
+ - abbr: '02'
+ name: Adıyaman
+ - abbr: '03'
+ name: Afyon
+ - abbr: '68'
+ name: Aksaray
+ - abbr: '05'
+ name: Amasya
+ - abbr: '06'
+ name: Ankara
+ - abbr: '07'
+ name: Antalya
+ - abbr: '75'
+ name: Ardahan
+ - abbr: '08'
+ name: Artvin
+ - abbr: '09'
+ name: Aydın
+ - abbr: '04'
+ name: Ağrı
+ - abbr: '10'
+ name: Balıkesir
+ - abbr: '74'
+ name: Bartın
+ - abbr: '72'
+ name: Batman
+ - abbr: '69'
+ name: Bayburt
+ - abbr: '11'
+ name: Bilecik
+ - abbr: '12'
+ name: Bingöl
+ - abbr: '13'
+ name: Bitlis
+ - abbr: '14'
+ name: Bolu
+ - abbr: '15'
+ name: Burdur
+ - abbr: '16'
+ name: Bursa
+ - abbr: '20'
+ name: Denizli
+ - abbr: '21'
+ name: Diyarbakır
+ - abbr: '81'
+ name: Düzce
+ - abbr: '22'
+ name: Edirne
+ - abbr: '23'
+ name: Elazığ
+ - abbr: '24'
+ name: Erzincan
+ - abbr: '25'
+ name: Erzurum
+ - abbr: '26'
+ name: Eskişehir
+ - abbr: '27'
+ name: Gaziantep
+ - abbr: '28'
+ name: Giresun
+ - abbr: '29'
+ name: Gümüşhane
+ - abbr: '30'
+ name: Hakkâri
+ - abbr: '31'
+ name: Hatay
+ - abbr: '32'
+ name: Isparta
+ - abbr: '76'
+ name: Iğdır
+ - abbr: '46'
+ name: Kahramanmaraş
+ - abbr: '78'
+ name: Karabük
+ - abbr: '70'
+ name: Karaman
+ - abbr: '36'
+ name: Kars
+ - abbr: '37'
+ name: Kastamonu
+ - abbr: '38'
+ name: Kayseri
+ - abbr: '79'
+ name: Kilis
+ - abbr: '41'
+ name: Kocaeli
+ - abbr: '42'
+ name: Konya
+ - abbr: '43'
+ name: Kütahya
+ - abbr: '39'
+ name: Kırklareli
+ - abbr: '71'
+ name: Kırıkkale
+ - abbr: '40'
+ name: Kırşehir
+ - abbr: '44'
+ name: Malatya
+ - abbr: '45'
+ name: Manisa
+ - abbr: '47'
+ name: Mardin
+ - abbr: '48'
+ name: Muğla
+ - abbr: '49'
+ name: Muş
+ - abbr: '50'
+ name: Nevşehir
+ - abbr: '51'
+ name: Niğde
+ - abbr: '52'
+ name: Ordu
+ - abbr: '80'
+ name: Osmaniye
+ - abbr: '53'
+ name: Rize
+ - abbr: '54'
+ name: Sakarya
+ - abbr: '55'
+ name: Samsun
+ - abbr: '56'
+ name: Siirt
+ - abbr: '57'
+ name: Sinop
+ - abbr: '58'
+ name: Sivas
+ - abbr: '59'
+ name: Tekirdağ
+ - abbr: '60'
+ name: Tokat
+ - abbr: '61'
+ name: Trabzon
+ - abbr: '62'
+ name: Tunceli
+ - abbr: '64'
+ name: Uşak
+ - abbr: '65'
+ name: Van
+ - abbr: '77'
+ name: Yalova
+ - abbr: '66'
+ name: Yozgat
+ - abbr: '67'
+ name: Zonguldak
+ - abbr: '17'
+ name: Çanakkale
+ - abbr: '18'
+ name: Çankırı
+ - abbr: '19'
+ name: Çorum
+ - abbr: '34'
+ name: İstanbul
+ - abbr: '35'
+ name: İzmir
+ - abbr: '33'
+ name: İçel
+ - abbr: '63'
+ name: Şanlıurfa
+ - abbr: '73'
+ name: Şırnak
+ - iso: UG
+ iso3: UGA
+ name: Uganda
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: '317'
+ name: Abim
+ - abbr: '301'
+ name: Adjumani
+ - abbr: '322'
+ name: Agago
+ - abbr: '323'
+ name: Alebtong
+ - abbr: '314'
+ name: Amolatar
+ - abbr: '324'
+ name: Amudat
+ - abbr: '216'
+ name: Amuria
+ - abbr: '319'
+ name: Amuru
+ - abbr: '302'
+ name: Apac
+ - abbr: '303'
+ name: Arua
+ - abbr: '217'
+ name: Budaka
+ - abbr: '223'
+ name: Bududa
+ - abbr: '201'
+ name: Bugiri
+ - abbr: '235'
+ name: Bugweri
+ - abbr: '420'
+ name: Buhweju
+ - abbr: '117'
+ name: Buikwe
+ - abbr: '224'
+ name: Bukedea
+ - abbr: '118'
+ name: Bukomansibi
+ - abbr: '218'
+ name: Bukwa
+ - abbr: '225'
+ name: Bulambuli
+ - abbr: '419'
+ name: Buliisa
+ - abbr: '401'
+ name: Bundibugyo
+ - abbr: '430'
+ name: Bunyangabu
+ - abbr: '402'
+ name: Bushenyi
+ - abbr: '202'
+ name: Busia
+ - abbr: '219'
+ name: Butaleja
+ - abbr: '119'
+ name: Butambala
+ - abbr: '233'
+ name: Butebo
+ - abbr: '120'
+ name: Buvuma
+ - abbr: '226'
+ name: Buyende
+ - abbr: C
+ name: Central
+ - abbr: '318'
+ name: Dokolo
+ - abbr: E
+ name: Eastern
+ - abbr: '121'
+ name: Gomba
+ - abbr: '304'
+ name: Gulu
+ - abbr: '403'
+ name: Hoima
+ - abbr: '416'
+ name: Ibanda
+ - abbr: '203'
+ name: Iganga
+ - abbr: '417'
+ name: Isingiro
+ - abbr: '204'
+ name: Jinja
+ - abbr: '315'
+ name: Kaabong
+ - abbr: '404'
+ name: Kabale
+ - abbr: '405'
+ name: Kabarole
+ - abbr: '213'
+ name: Kaberamaido
+ - abbr: '427'
+ name: Kagadi
+ - abbr: '428'
+ name: Kakumiro
+ - abbr: '237'
+ name: Kalaki
+ - abbr: '101'
+ name: Kalangala
+ - abbr: '220'
+ name: Kaliro
+ - abbr: '122'
+ name: Kalungu
+ - abbr: '102'
+ name: Kampala
+ - abbr: '205'
+ name: Kamuli
+ - abbr: '413'
+ name: Kamwenge
+ - abbr: '414'
+ name: Kanungu
+ - abbr: '206'
+ name: Kapchorwa
+ - abbr: '236'
+ name: Kapelebyong
+ - abbr: '335'
+ name: Karenga
+ - abbr: '126'
+ name: Kasanda
+ - abbr: '406'
+ name: Kasese
+ - abbr: '207'
+ name: Katakwi
+ - abbr: '112'
+ name: Kayunga
+ - abbr: '433'
+ name: Kazo
+ - abbr: '407'
+ name: Kibaale
+ - abbr: '103'
+ name: Kiboga
+ - abbr: '227'
+ name: Kibuku
+ - abbr: '432'
+ name: Kikuube
+ - abbr: '418'
+ name: Kiruhura
+ - abbr: '421'
+ name: Kiryandongo
+ - abbr: '408'
+ name: Kisoro
+ - abbr: '434'
+ name: Kitagwenda
+ - abbr: '305'
+ name: Kitgum
+ - abbr: '316'
+ name: Koboko
+ - abbr: '325'
+ name: Kole
+ - abbr: '306'
+ name: Kotido
+ - abbr: '208'
+ name: Kumi
+ - abbr: '333'
+ name: Kwania
+ - abbr: '228'
+ name: Kween
+ - abbr: '123'
+ name: Kyankwanzi
+ - abbr: '422'
+ name: Kyegegwa
+ - abbr: '415'
+ name: Kyenjojo
+ - abbr: '125'
+ name: Kyotera
+ - abbr: '326'
+ name: Lamwo
+ - abbr: '307'
+ name: Lira
+ - abbr: '229'
+ name: Luuka
+ - abbr: '104'
+ name: Luwero
+ - abbr: '124'
+ name: Lwengo
+ - abbr: '116'
+ name: Lyantonde
+ - abbr: '336'
+ name: Madi-Okollo
+ - abbr: '221'
+ name: Manafwa
+ - abbr: '320'
+ name: Maracha
+ - abbr: '105'
+ name: Masaka
+ - abbr: '409'
+ name: Masindi
+ - abbr: '214'
+ name: Mayuge
+ - abbr: '209'
+ name: Mbale
+ - abbr: '410'
+ name: Mbarara
+ - abbr: '423'
+ name: Mitooma
+ - abbr: '114'
+ name: Mityana
+ - abbr: '308'
+ name: Moroto
+ - abbr: '309'
+ name: Moyo
+ - abbr: '106'
+ name: Mpigi
+ - abbr: '107'
+ name: Mubende
+ - abbr: '108'
+ name: Mukono
+ - abbr: '334'
+ name: Nabilatuk
+ - abbr: '311'
+ name: Nakapiripirit
+ - abbr: '115'
+ name: Nakaseke
+ - abbr: '109'
+ name: Nakasongola
+ - abbr: '230'
+ name: Namayingo
+ - abbr: '234'
+ name: Namisindwa
+ - abbr: '222'
+ name: Namutumba
+ - abbr: '327'
+ name: Napak
+ - abbr: '310'
+ name: Nebbi
+ - abbr: '231'
+ name: Ngora
+ - abbr: "N"
+ name: Northern
+ - abbr: '424'
+ name: Ntoroko
+ - abbr: '411'
+ name: Ntungamo
+ - abbr: '328'
+ name: Nwoya
+ - abbr: '337'
+ name: Obongi
+ - abbr: '329'
+ name: Otuke
+ - abbr: '321'
+ name: Oyam
+ - abbr: '312'
+ name: Pader
+ - abbr: '332'
+ name: Pakwach
+ - abbr: '210'
+ name: Pallisa
+ - abbr: '110'
+ name: Rakai
+ - abbr: '429'
+ name: Rubanda
+ - abbr: '425'
+ name: Rubirizi
+ - abbr: '431'
+ name: Rukiga
+ - abbr: '412'
+ name: Rukungiri
+ - abbr: '435'
+ name: Rwampara
+ - abbr: '111'
+ name: Sembabule
+ - abbr: '232'
+ name: Serere
+ - abbr: '426'
+ name: Sheema
+ - abbr: '215'
+ name: Sironko
+ - abbr: '211'
+ name: Soroti
+ - abbr: '212'
+ name: Tororo
+ - abbr: '113'
+ name: Wakiso
+ - abbr: W
+ name: Western
+ - abbr: '313'
+ name: Yumbe
+ - abbr: '331'
+ name: Zombo
+ - abbr: '330'
+ name: Zombo²
+ - iso: UA
+ iso3: UKR
+ name: Ukraine
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '71'
+ name: Cherkas'ka Oblast'
+ - abbr: '74'
+ name: Chernihivs'ka Oblast'
+ - abbr: '77'
+ name: Chernivets'ka Oblast'
+ - abbr: '12'
+ name: Dnipropetrovs'ka Oblast'
+ - abbr: '14'
+ name: Donets'ka Oblast'
+ - abbr: '26'
+ name: Ivano-Frankivs'ka Oblast'
+ - abbr: '63'
+ name: Kharkivs'ka Oblast'
+ - abbr: '65'
+ name: Khersons'ka Oblast'
+ - abbr: '68'
+ name: Khmel'nyts'ka Oblast'
+ - abbr: '35'
+ name: Kirovohrads'ka Oblast'
+ - abbr: '30'
+ name: Kyïv
+ - abbr: '32'
+ name: Kyïvs'ka Oblast'
+ - abbr: '46'
+ name: L'vivs'ka Oblast'
+ - abbr: '09'
+ name: Luhans'ka Oblast'
+ - abbr: '48'
+ name: Mykolaïvs'ka Oblast'
+ - abbr: '51'
+ name: Odes'ka Oblast'
+ - abbr: '53'
+ name: Poltavs'ka Oblast'
+ - abbr: '43'
+ name: Respublika Krym
+ - abbr: '56'
+ name: Rivnens'ka Oblast'
+ - abbr: '40'
+ name: Sevastopol'
+ - abbr: '59'
+ name: Sums'ka Oblast'
+ - abbr: '61'
+ name: Ternopil's'ka Oblast'
+ - abbr: '05'
+ name: Vinnyts'ka Oblast'
+ - abbr: '07'
+ name: Volyns'ka Oblast'
+ - abbr: '21'
+ name: Zakarpats'ka Oblast'
+ - abbr: '23'
+ name: Zaporiz'ka Oblast'
+ - abbr: '18'
+ name: Zhytomyrs'ka Oblast'
+ - iso: AE
+ iso3: ARE
+ name: United Arab Emirates
+ states_required: true
+ zipcode_required: false
+ states:
+ - abbr: AJ
+ name: "'Ajmān"
+ - abbr: AZ
+ name: Abū Z̧aby [Abu Dhabi]
+ - abbr: FU
+ name: Al Fujayrah
+ - abbr: SH
+ name: Ash Shariqah [Sharjah]
+ - abbr: DU
+ name: Dubayy
+ - abbr: RK
+ name: Ra's al Khaymah
+ - abbr: UQ
+ name: Umm al Qaywayn
+ - iso: GB
+ iso3: GBR
+ name: United Kingdom
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: ABE
+ name: Aberdeen City
+ - abbr: ABD
+ name: Aberdeenshire
+ - abbr: ANS
+ name: Angus
+ - abbr: ANN
+ name: Antrim and Newtownabbey
+ - abbr: AND
+ name: Ards and North Down
+ - abbr: AGB
+ name: Argyll and Bute
+ - abbr: ABC
+ name: Armagh City, Banbridge and Craigavon
+ - abbr: BDG
+ name: Barking and Dagenham
+ - abbr: BNE
+ name: Barnet
+ - abbr: BNS
+ name: Barnsley
+ - abbr: BAS
+ name: Bath and North East Somerset
+ - abbr: BDF
+ name: Bedfordshire
+ - abbr: BFS
+ name: Belfast
+ - abbr: BEX
+ name: Bexley
+ - abbr: BIR
+ name: Birmingham
+ - abbr: BBD
+ name: Blackburn with Darwen
+ - abbr: BPL
+ name: Blackpool
+ - abbr: BGW
+ name: Blaenau Gwent
+ - abbr: BOL
+ name: Bolton
+ - abbr: BCP
+ name: Bournemouth, Christchurch and Poole
+ - abbr: BRC
+ name: Bracknell Forest
+ - abbr: BRD
+ name: Bradford
+ - abbr: BEN
+ name: Brent
+ - abbr: BGE
+ name: Bridgend [Pen-y-bont ar Ogwr GB-POG]
+ - abbr: BNH
+ name: Brighton and Hove
+ - abbr: BST
+ name: Bristol, City of
+ - abbr: BRY
+ name: Bromley
+ - abbr: BKM
+ name: Buckinghamshire
+ - abbr: BUR
+ name: Bury
+ - abbr: CAY
+ name: Caerphilly [Caerffili GB-CAF]
+ - abbr: CLD
+ name: Calderdale
+ - abbr: CAM
+ name: Cambridgeshire
+ - abbr: CMD
+ name: Camden
+ - abbr: CRF
+ name: Cardiff [Caerdydd GB-CRD]
+ - abbr: CMN
+ name: Carmarthenshire [Sir Gaerfyrddin GB-GFY]
+ - abbr: CCG
+ name: Causeway Coast and Glens
+ - abbr: CBF
+ name: Central Bedfordshire
+ - abbr: CGN
+ name: Ceredigion [Sir Ceredigion]
+ - abbr: CHE
+ name: Cheshire East
+ - abbr: CHW
+ name: Cheshire West and Chester
+ - abbr: CLK
+ name: Clackmannanshire
+ - abbr: CWY
+ name: Conwy
+ - abbr: CON
+ name: Cornwall
+ - abbr: COV
+ name: Coventry
+ - abbr: CRY
+ name: Croydon
+ - abbr: CMA
+ name: Cumbria
+ - abbr: DAL
+ name: Darlington
+ - abbr: DEN
+ name: Denbighshire [Sir Ddinbych GB-DDB]
+ - abbr: DER
+ name: Derby
+ - abbr: DBY
+ name: Derbyshire
+ - abbr: DRS
+ name: Derry and Strabane
+ - abbr: DEV
+ name: Devon
+ - abbr: DNC
+ name: Doncaster
+ - abbr: DOR
+ name: Dorset
+ - abbr: DUD
+ name: Dudley
+ - abbr: DGY
+ name: Dumfries and Galloway
+ - abbr: DND
+ name: Dundee City
+ - abbr: DUR
+ name: Durham
+ - abbr: EAL
+ name: Ealing
+ - abbr: EAY
+ name: East Ayrshire
+ - abbr: EDU
+ name: East Dunbartonshire
+ - abbr: ELN
+ name: East Lothian
+ - abbr: ERW
+ name: East Renfrewshire
+ - abbr: ERY
+ name: East Riding of Yorkshire
+ - abbr: ESX
+ name: East Sussex
+ - abbr: EDH
+ name: Edinburgh, City of
+ - abbr: ELS
+ name: Eilean Siar
+ - abbr: ENF
+ name: Enfield
+ - abbr: ENG
+ name: England
+ - abbr: ESS
+ name: Essex
+ - abbr: FAL
+ name: Falkirk
+ - abbr: FMO
+ name: Fermanagh and Omagh
+ - abbr: FIF
+ name: Fife
+ - abbr: FLN
+ name: Flintshire [Sir y Fflint GB-FFL]
+ - abbr: GAT
+ name: Gateshead
+ - abbr: GLG
+ name: Glasgow City
+ - abbr: GLS
+ name: Gloucestershire
+ - abbr: GRE
+ name: Greenwich
+ - abbr: GWN
+ name: Gwynedd
+ - abbr: HCK
+ name: Hackney
+ - abbr: HAL
+ name: Halton
+ - abbr: HMF
+ name: Hammersmith and Fulham
+ - abbr: HAM
+ name: Hampshire
+ - abbr: HRY
+ name: Haringey
+ - abbr: HRW
+ name: Harrow
+ - abbr: HPL
+ name: Hartlepool
+ - abbr: HAV
+ name: Havering
+ - abbr: HEF
+ name: Herefordshire, County of
+ - abbr: HRT
+ name: Hertfordshire
+ - abbr: HLD
+ name: Highland
+ - abbr: HIL
+ name: Hillingdon
+ - abbr: HNS
+ name: Hounslow
+ - abbr: IVC
+ name: Inverclyde
+ - abbr: AGY
+ name: Isle of Anglesey [Sir Ynys Môn GB-YNM]
+ - abbr: IOW
+ name: Isle of Wight
+ - abbr: IOS
+ name: Isles of Scilly
+ - abbr: ISL
+ name: Islington
+ - abbr: KEC
+ name: Kensington and Chelsea
+ - abbr: KEN
+ name: Kent
+ - abbr: KHL
+ name: Kingston upon Hull, City of
+ - abbr: KTT
+ name: Kingston upon Thames
+ - abbr: KIR
+ name: Kirklees
+ - abbr: KWL
+ name: Knowsley
+ - abbr: LBH
+ name: Lambeth
+ - abbr: LAN
+ name: Lancashire
+ - abbr: LDS
+ name: Leeds
+ - abbr: LCE
+ name: Leicester
+ - abbr: LEC
+ name: Leicestershire
+ - abbr: LEW
+ name: Lewisham
+ - abbr: LIN
+ name: Lincolnshire
+ - abbr: LBC
+ name: Lisburn and Castlereagh
+ - abbr: LIV
+ name: Liverpool
+ - abbr: LND
+ name: London, City of
+ - abbr: LUT
+ name: Luton
+ - abbr: MAN
+ name: Manchester
+ - abbr: MDW
+ name: Medway
+ - abbr: MTY
+ name: Merthyr Tydfil [Merthyr Tudful GB-MTU]
+ - abbr: MRT
+ name: Merton
+ - abbr: MUL
+ name: Mid Ulster
+ - abbr: MEA
+ name: Mid and East Antrim
+ - abbr: MDB
+ name: Middlesbrough
+ - abbr: MLN
+ name: Midlothian
+ - abbr: MIK
+ name: Milton Keynes
+ - abbr: MON
+ name: Monmouthshire [Sir Fynwy GB-FYN]
+ - abbr: MRY
+ name: Moray
+ - abbr: NTL
+ name: Neath Port Talbot [Castell-nedd Port Talbot GB-CTL]
+ - abbr: NET
+ name: Newcastle upon Tyne
+ - abbr: NWM
+ name: Newham
+ - abbr: NWP
+ name: Newport [Casnewydd GB-CNW]
+ - abbr: NMD
+ name: Newry, Mourne and Down
+ - abbr: NFK
+ name: Norfolk
+ - abbr: NAY
+ name: North Ayrshire
+ - abbr: NEL
+ name: North East Lincolnshire
+ - abbr: NLK
+ name: North Lanarkshire
+ - abbr: NLN
+ name: North Lincolnshire
+ - abbr: NSM
+ name: North Somerset
+ - abbr: NTY
+ name: North Tyneside
+ - abbr: NYK
+ name: North Yorkshire
+ - abbr: NTH
+ name: Northamptonshire
+ - abbr: NIR
+ name: Northern Ireland
+ - abbr: NBL
+ name: Northumberland
+ - abbr: NGM
+ name: Nottingham
+ - abbr: NTT
+ name: Nottinghamshire
+ - abbr: OLD
+ name: Oldham
+ - abbr: ORK
+ name: Orkney Islands
+ - abbr: OXF
+ name: Oxfordshire
+ - abbr: PEM
+ name: Pembrokeshire [Sir Benfro GB-BNF]
+ - abbr: PKN
+ name: Perth and Kinross
+ - abbr: PTE
+ name: Peterborough
+ - abbr: PLY
+ name: Plymouth
+ - abbr: POR
+ name: Portsmouth
+ - abbr: POW
+ name: Powys
+ - abbr: RDG
+ name: Reading
+ - abbr: RDB
+ name: Redbridge
+ - abbr: RCC
+ name: Redcar and Cleveland
+ - abbr: RFW
+ name: Renfrewshire
+ - abbr: RCT
+ name: Rhondda, Cynon, Taff [Rhondda, Cynon,Taf]
+ - abbr: RIC
+ name: Richmond upon Thames
+ - abbr: RCH
+ name: Rochdale
+ - abbr: ROT
+ name: Rotherham
+ - abbr: RUT
+ name: Rutland
+ - abbr: SLF
+ name: Salford
+ - abbr: SAW
+ name: Sandwell
+ - abbr: SCT
+ name: Scotland
+ - abbr: SCB
+ name: Scottish Borders, The
+ - abbr: SFT
+ name: Sefton
+ - abbr: SHF
+ name: Sheffield
+ - abbr: ZET
+ name: Shetland Islands
+ - abbr: SHR
+ name: Shropshire
+ - abbr: SLG
+ name: Slough
+ - abbr: SOL
+ name: Solihull
+ - abbr: SOM
+ name: Somerset
+ - abbr: SAY
+ name: South Ayrshire
+ - abbr: SGC
+ name: South Gloucestershire
+ - abbr: SLK
+ name: South Lanarkshire
+ - abbr: STY
+ name: South Tyneside
+ - abbr: STH
+ name: Southampton
+ - abbr: SOS
+ name: Southend-on-Sea
+ - abbr: SWK
+ name: Southwark
+ - abbr: SHN
+ name: St. Helens
+ - abbr: STS
+ name: Staffordshire
+ - abbr: STG
+ name: Stirling
+ - abbr: SKP
+ name: Stockport
+ - abbr: STT
+ name: Stockton-on-Tees
+ - abbr: STE
+ name: Stoke-on-Trent
+ - abbr: SFK
+ name: Suffolk
+ - abbr: SND
+ name: Sunderland
+ - abbr: SRY
+ name: Surrey
+ - abbr: STN
+ name: Sutton
+ - abbr: SWA
+ name: Swansea [Abertawe GB-ATA]
+ - abbr: SWD
+ name: Swindon
+ - abbr: TAM
+ name: Tameside
+ - abbr: TFW
+ name: Telford and Wrekin
+ - abbr: THR
+ name: Thurrock
+ - abbr: TOB
+ name: Torbay
+ - abbr: TOF
+ name: Torfaen [Tor-faen]
+ - abbr: TWH
+ name: Tower Hamlets
+ - abbr: TRF
+ name: Trafford
+ - abbr: VGL
+ name: Vale of Glamorgan, The [Bro Morgannwg GB-BMG]
+ - abbr: WKF
+ name: Wakefield
+ - abbr: WLS
+ name: Wales
+ - abbr: WLL
+ name: Walsall
+ - abbr: WFT
+ name: Waltham Forest
+ - abbr: WND
+ name: Wandsworth
+ - abbr: WRT
+ name: Warrington
+ - abbr: WAR
+ name: Warwickshire
+ - abbr: WBK
+ name: West Berkshire
+ - abbr: WDU
+ name: West Dunbartonshire
+ - abbr: WLN
+ name: West Lothian
+ - abbr: WSX
+ name: West Sussex
+ - abbr: WSM
+ name: Westminster
+ - abbr: WGN
+ name: Wigan
+ - abbr: WIL
+ name: Wiltshire
+ - abbr: WNM
+ name: Windsor and Maidenhead
+ - abbr: WRL
+ name: Wirral
+ - abbr: WOK
+ name: Wokingham
+ - abbr: WLV
+ name: Wolverhampton
+ - abbr: WOR
+ name: Worcestershire
+ - abbr: WRX
+ name: Wrexham [Wrecsam GB-WRC]
+ - abbr: YOR
+ name: York
+ - iso: US
+ iso3: USA
+ name: United States
+ states_required: true
+ zipcode_required: true
+ states:
+ - abbr: AL
+ name: Alabama
+ - abbr: AK
+ name: Alaska
+ - abbr: AZ
+ name: Arizona
+ - abbr: AR
+ name: Arkansas
+ - abbr: AA
+ name: Armed Forces Americas
+ - abbr: AE
+ name: Armed Forces Europe
+ - abbr: AP
+ name: Armed Forces Pacific
+ - abbr: CA
+ name: California
+ - abbr: CO
+ name: Colorado
+ - abbr: CT
+ name: Connecticut
+ - abbr: DE
+ name: Delaware
+ - abbr: DC
+ name: District of Columbia
+ - abbr: FL
+ name: Florida
+ - abbr: GA
+ name: Georgia
+ - abbr: HI
+ name: Hawaii
+ - abbr: ID
+ name: Idaho
+ - abbr: IL
+ name: Illinois
+ - abbr: IN
+ name: Indiana
+ - abbr: IA
+ name: Iowa
+ - abbr: KS
+ name: Kansas
+ - abbr: KY
+ name: Kentucky
+ - abbr: LA
+ name: Louisiana
+ - abbr: ME
+ name: Maine
+ - abbr: MD
+ name: Maryland
+ - abbr: MA
+ name: Massachusetts
+ - abbr: MI
+ name: Michigan
+ - abbr: MN
+ name: Minnesota
+ - abbr: MS
+ name: Mississippi
+ - abbr: MO
+ name: Missouri
+ - abbr: MT
+ name: Montana
+ - abbr: NE
+ name: Nebraska
+ - abbr: NV
+ name: Nevada
+ - abbr: NH
+ name: New Hampshire
+ - abbr: NJ
+ name: New Jersey
+ - abbr: NM
+ name: New Mexico
+ - abbr: NY
+ name: New York
+ - abbr: NC
+ name: North Carolina
+ - abbr: ND
+ name: North Dakota
+ - abbr: OH
+ name: Ohio
+ - abbr: OK
+ name: Oklahoma
+ - abbr: OR
+ name: Oregon
+ - abbr: PA
+ name: Pennsylvania
+ - abbr: RI
+ name: Rhode Island
+ - abbr: SC
+ name: South Carolina
+ - abbr: SD
+ name: South Dakota
+ - abbr: TN
+ name: Tennessee
+ - abbr: TX
+ name: Texas
+ - abbr: UT
+ name: Utah
+ - abbr: VT
+ name: Vermont
+ - abbr: VA
+ name: Virginia
+ - abbr: WA
+ name: Washington
+ - abbr: WV
+ name: West Virginia
+ - abbr: WI
+ name: Wisconsin
+ - abbr: WY
+ name: Wyoming
+ - iso: UY
+ iso3: URY
+ name: Uruguay
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AR
+ name: Artigas
+ - abbr: CA
+ name: Canelones
+ - abbr: CL
+ name: Cerro Lago
+ - abbr: CO
+ name: Colonia
+ - abbr: DU
+ name: Durazno
+ - abbr: FS
+ name: Flores
+ - abbr: FD
+ name: Florida
+ - abbr: LA
+ name: Lavalleja
+ - abbr: MA
+ name: Maldonado
+ - abbr: MO
+ name: Montevideo
+ - abbr: PA
+ name: Paysandú
+ - abbr: RV
+ name: Rivera
+ - abbr: RO
+ name: Rocha
+ - abbr: RN
+ name: Río Negro
+ - abbr: SA
+ name: Salto
+ - abbr: SJ
+ name: San José
+ - abbr: SO
+ name: Soriano
+ - abbr: TA
+ name: Tacuarembó
+ - abbr: TT
+ name: Treinta y Tres
+ - iso: UZ
+ iso3: UZB
+ name: Uzbekistan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AN
+ name: Andijon
+ - abbr: BU
+ name: Buxoro
+ - abbr: FA
+ name: Farg‘ona
+ - abbr: JI
+ name: Jizzax
+ - abbr: NG
+ name: Namangan
+ - abbr: NW
+ name: Navoiy
+ - abbr: QA
+ name: Qashqadaryo
+ - abbr: QR
+ name: Qoraqalpog‘iston Respublikasi
+ - abbr: SA
+ name: Samarqand
+ - abbr: SI
+ name: Sirdaryo
+ - abbr: SU
+ name: Surxondaryo
+ - abbr: TO
+ name: Toshkent
+ - abbr: TK
+ name: Toshkent City
+ - abbr: XO
+ name: Xorazm
+ - iso: VU
+ iso3: VUT
+ name: Vanuatu
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: MAP
+ name: Malampa
+ - abbr: PAM
+ name: Pénama
+ - abbr: SAM
+ name: Sanma
+ - abbr: SEE
+ name: Shéfa
+ - abbr: TAE
+ name: Taféa
+ - abbr: TOB
+ name: Torba
+ - iso: VE
+ iso3: VEN
+ name: Venezuela
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: Z
+ name: Amazonas
+ - abbr: B
+ name: Anzoátegui
+ - abbr: C
+ name: Apure
+ - abbr: D
+ name: Aragua
+ - abbr: E
+ name: Barinas
+ - abbr: F
+ name: Bolívar
+ - abbr: G
+ name: Carabobo
+ - abbr: H
+ name: Cojedes
+ - abbr: "Y"
+ name: Delta Amacuro
+ - abbr: W
+ name: Dependencias Federales
+ - abbr: A
+ name: Distrito Federal
+ - abbr: I
+ name: Falcón
+ - abbr: J
+ name: Guárico
+ - abbr: K
+ name: Lara
+ - abbr: M
+ name: Miranda
+ - abbr: "N"
+ name: Monagas
+ - abbr: L
+ name: Mérida
+ - abbr: O
+ name: Nueva Esparta
+ - abbr: P
+ name: Portuguesa
+ - abbr: R
+ name: Sucre
+ - abbr: T
+ name: Trujillo
+ - abbr: S
+ name: Táchira
+ - abbr: X
+ name: Vargas
+ - abbr: U
+ name: Yaracuy
+ - abbr: V
+ name: Zulia
+ - iso: VN
+ iso3: VNM
+ name: Vietnam
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '44'
+ name: An Giang
+ - abbr: '43'
+ name: Ba Ria - Vung Tau
+ - abbr: '53'
+ name: Bac Can
+ - abbr: '54'
+ name: Bac Giang
+ - abbr: '55'
+ name: Bac Lieu
+ - abbr: '56'
+ name: Bac Ninh
+ - abbr: '50'
+ name: Ben Tre
+ - abbr: '31'
+ name: Binh Dinh
+ - abbr: '57'
+ name: Binh Duong
+ - abbr: '58'
+ name: Binh Phuoc
+ - abbr: '40'
+ name: Binh Thuan
+ - abbr: '59'
+ name: Ca Mau
+ - abbr: CT
+ name: Can Tho
+ - abbr: '04'
+ name: Cao Bang
+ - abbr: DN
+ name: Da Nang
+ - abbr: '33'
+ name: Dac Lac
+ - abbr: '72'
+ name: Dak Nong
+ - abbr: '71'
+ name: Dien Bien
+ - abbr: '39'
+ name: Dong Nai
+ - abbr: '45'
+ name: Dong Thap
+ - abbr: '30'
+ name: Gia Lai
+ - abbr: '03'
+ name: Ha Giang
+ - abbr: '63'
+ name: Ha Nam
+ - abbr: HN
+ name: Ha Noi
+ - abbr: '23'
+ name: Ha Tinh
+ - abbr: '61'
+ name: Hai Duong
+ - abbr: HP
+ name: Hai Phong
+ - abbr: '73'
+ name: Hau Giang
+ - abbr: SG
+ name: Ho Chi Minh
+ - abbr: '14'
+ name: Hoa Binh
+ - abbr: '66'
+ name: Hung Yen
+ - abbr: '34'
+ name: Khanh Hoa
+ - abbr: '47'
+ name: Kien Giang
+ - abbr: '28'
+ name: Kon Tum
+ - abbr: '01'
+ name: Lai Chau
+ - abbr: '35'
+ name: Lam Dong
+ - abbr: '09'
+ name: Lang Son
+ - abbr: '02'
+ name: Lao Cai
+ - abbr: '41'
+ name: Long An
+ - abbr: '67'
+ name: Nam Dinh
+ - abbr: '22'
+ name: Nghe An
+ - abbr: '18'
+ name: Ninh Binh
+ - abbr: '36'
+ name: Ninh Thuan
+ - abbr: '68'
+ name: Phu Tho
+ - abbr: '32'
+ name: Phu Yen
+ - abbr: '24'
+ name: Quang Binh
+ - abbr: '27'
+ name: Quang Nam
+ - abbr: '29'
+ name: Quang Ngai
+ - abbr: '13'
+ name: Quang Ninh
+ - abbr: '25'
+ name: Quang Tri
+ - abbr: '52'
+ name: Soc Trang
+ - abbr: '05'
+ name: Son La
+ - abbr: '37'
+ name: Tay Ninh
+ - abbr: '20'
+ name: Thai Binh
+ - abbr: '69'
+ name: Thai Nguyen
+ - abbr: '21'
+ name: Thanh Hoa
+ - abbr: '26'
+ name: Thua Thien-Hue
+ - abbr: '46'
+ name: Tien Giang
+ - abbr: '51'
+ name: Tra Vinh
+ - abbr: '07'
+ name: Tuyen Quang
+ - abbr: '49'
+ name: Vinh Long
+ - abbr: '70'
+ name: Vinh Phuc
+ - abbr: '06'
+ name: Yen Bai
+ - iso: VG
+ iso3: VGB
+ name: Virgin Islands, British
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: VI
+ iso3: VIR
+ name: Virgin Islands, U.S.
+ states_required: false
+ zipcode_required: true
+ states: []
+ - iso: WF
+ iso3: WLF
+ name: Wallis and Futuna
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: AL
+ name: Alo
+ - abbr: SG
+ name: Sigave
+ - abbr: UV
+ name: Uvea
+ - iso: YE
+ iso3: YEM
+ name: Yemen
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: AM
+ name: "'Amran"
+ - abbr: AB
+ name: Abyan
+ - abbr: DA
+ name: Ad¸ D¸ali'
+ - abbr: BA
+ name: Al Bayḑā’
+ - abbr: JA
+ name: Al Jawf
+ - abbr: MR
+ name: Al Mahrah
+ - abbr: MW
+ name: Al Mahwit
+ - abbr: HU
+ name: Al Ḩudaydah
+ - abbr: DH
+ name: Dhamar
+ - abbr: HD
+ name: Hadramawt
+ - abbr: HJ
+ name: Hajjah
+ - abbr: IB
+ name: Ibb
+ - abbr: LA
+ name: Laḩij
+ - abbr: MA
+ name: Ma'rib
+ - abbr: SD
+ name: Sa`dah
+ - abbr: SN
+ name: Sanʿā
+ - abbr: SH
+ name: Shabwah
+ - abbr: TA
+ name: Taʿizz
+ - abbr: AD
+ name: ʿAdan
+ - abbr: SA
+ name: صنعاء
+ - abbr: SU
+ name: محافظة أرخبيل سقطرى
+ - abbr: RA
+ name: محافظة ريمة
+ - iso: ZM
+ iso3: ZMB
+ name: Zambia
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: '02'
+ name: Central
+ - abbr: '08'
+ name: Copperbelt
+ - abbr: '03'
+ name: Eastern
+ - abbr: '04'
+ name: Luapula
+ - abbr: '09'
+ name: Lusaka
+ - abbr: '10'
+ name: Muchinga
+ - abbr: '06'
+ name: North-Western
+ - abbr: '05'
+ name: Northern
+ - abbr: '07'
+ name: Southern
+ - abbr: '01'
+ name: Western
+ - iso: ZW
+ iso3: ZWE
+ name: Zimbabwe
+ states_required: false
+ zipcode_required: false
+ states:
+ - abbr: BU
+ name: Bulawayo
+ - abbr: HA
+ name: Harare
+ - abbr: MA
+ name: Manicaland
+ - abbr: MC
+ name: Mashonaland Central
+ - abbr: ME
+ name: Mashonaland East
+ - abbr: MW
+ name: Mashonaland West
+ - abbr: MV
+ name: Masvingo
+ - abbr: MN
+ name: Matabeleland North
+ - abbr: MS
+ name: Matabeleland South
+ - abbr: MI
+ name: Midlands
+ meta:
+ count: 240
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/SellerCountry"
+ meta:
+ type: object
+ properties:
+ count:
+ type: integer
+ example: 250
+ required:
+ - count
+ required:
+ - data
+ - meta
+ "/api/v3/seller/delivery_methods":
+ get:
+ summary: List delivery methods
+ tags:
+ - Delivery Methods
+ security:
+ - bearer_auth: []
+ description: |
+ How this seller's goods can ship: the methods they created themselves,
+ plus any the marketplace shares with its sellers.
+
+ A shared marketplace method comes back with `editable: false` — it is
+ listed so the seller can see what already ships their goods, and every
+ write against it is a 404.
+ 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
+ responses:
+ '200':
+ description: delivery methods listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: dm_UkLWZg9DAJ
+ name: My courier
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ admin_name:
+ storefront_visible: true
+ tracking_url:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ rules: []
+ editable: true
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_zone_id:
+ calculator_type: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ amount: '10.0'
+ currency: USD
+ amounts: {}
+ - id: dm_gbHJdmfrXB
+ name: Marketplace post
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ admin_name:
+ storefront_visible: true
+ tracking_url:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ rules: []
+ editable: false
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_zone_id:
+ calculator_type: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ amount: '10.0'
+ currency: USD
+ amounts: {}
+ 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/DeliveryMethod"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ post:
+ summary: Create a delivery method
+ tags:
+ - Delivery Methods
+ security:
+ - bearer_auth: []
+ description: |
+ Adds a way for this seller to ship. The method is always the seller's
+ own, whatever the payload says.
+
+ Neither the rate provider nor the fulfillment provider is settable: a
+ seller prices their own rates and enters tracking numbers by hand,
+ because carrier accounts belong to the marketplace.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: delivery method created
+ content:
+ application/json:
+ example:
+ id: dm_EfhxLZ9ck8
+ name: Next day
+ 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:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ rules: []
+ editable: true
+ delivery_profile_id: fp_gbHJdmfrXB
+ delivery_zone_id:
+ calculator_type: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ amount: '9.99'
+ currency: USD
+ amounts: {}
+ schema:
+ "$ref": "#/components/schemas/DeliveryMethod"
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ admin_name:
+ type: string
+ nullable: true
+ code:
+ type: string
+ nullable: true
+ delivery_profile_id:
+ type: string
+ description: One of the marketplace's delivery profiles
+ delivery_zone_id:
+ type: string
+ nullable: true
+ description: Narrows where the method ships
storefront_visible:
type: boolean
tracking_url:
@@ -359,6 +12532,29 @@ paths:
description: delivery method found
content:
application/json:
+ example:
+ id: dm_UkLWZg9DAJ
+ name: My courier
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ admin_name:
+ storefront_visible: true
+ tracking_url:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ rules: []
+ editable: true
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_zone_id:
+ calculator_type: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ amount: '10.0'
+ currency: USD
+ amounts: {}
schema:
"$ref": "#/components/schemas/DeliveryMethod"
patch:
@@ -375,6 +12571,29 @@ paths:
description: delivery method updated
content:
application/json:
+ example:
+ id: dm_UkLWZg9DAJ
+ name: My express courier
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ admin_name:
+ storefront_visible: true
+ tracking_url:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ rules: []
+ editable: true
+ delivery_profile_id: fp_UkLWZg9DAJ
+ delivery_zone_id:
+ calculator_type: Spree::Calculator::Shipping::FlatRate
+ calculator_preferences:
+ amount: '10.0'
+ currency: USD
+ amounts: {}
schema:
"$ref": "#/components/schemas/DeliveryMethod"
requestBody:
@@ -455,6 +12674,30 @@ paths:
description: rule types listed
content:
application/json:
+ example:
+ data:
+ - type: item_total_rule
+ name: Item total
+ description: Limits the delivery method to carts within an item
+ total range
+ preference_schema:
+ - key: minimum_amount
+ type: decimal
+ default:
+ - key: maximum_amount
+ type: decimal
+ default:
+ - type: weight_rule
+ name: Weight
+ description: Limits the delivery method to packages within a weight
+ range
+ preference_schema:
+ - key: maximum_weight
+ type: decimal
+ default:
+ - key: minimum_weight
+ type: decimal
+ default:
schema:
type: object
properties:
@@ -493,6 +12736,80 @@ paths:
description: calculators listed
content:
application/json:
+ example:
+ data:
+ - type: Spree::Calculator::Shipping::FlatPercentItemTotal
+ name: Flat Percent
+ preference_schema:
+ - key: flat_percent
+ type: decimal
+ default: 0
+ - type: Spree::Calculator::Shipping::FlatRate
+ name: Flat rate
+ preference_schema:
+ - key: amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - key: amounts
+ type: hash
+ default: {}
+ - type: Spree::Calculator::Shipping::FlexiRate
+ name: Flexible Rate per package item
+ preference_schema:
+ - key: currency
+ type: string
+ default: USD
+ - key: first_item
+ type: decimal
+ default: 0.0
+ - key: additional_item
+ type: decimal
+ default: 0.0
+ - key: max_items
+ type: integer
+ default: 0
+ - type: Spree::Calculator::Shipping::PerItem
+ name: Flat rate per package item
+ preference_schema:
+ - key: amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - key: amounts
+ type: hash
+ default: {}
+ - type: Spree::Calculator::Shipping::PriceSack
+ name: Price sack
+ preference_schema:
+ - key: minimal_amount
+ type: decimal
+ default: 0
+ - key: normal_amount
+ type: decimal
+ default: 0
+ - key: discount_amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - type: Spree::Calculator::Shipping::DigitalDelivery
+ name: Digital Delivery
+ preference_schema:
+ - key: amount
+ type: decimal
+ default: 0
+ - key: currency
+ type: string
+ default: USD
+ - key: amounts
+ type: hash
+ default: {}
schema:
type: object
properties:
@@ -549,6 +12866,26 @@ paths:
description: delivery profiles listed
content:
application/json:
+ example:
+ data:
+ - id: fp_UkLWZg9DAJ
+ name: General
+ default: true
+ digital: false
+ - id: fp_gbHJdmfrXB
+ name: Oversized
+ default: false
+ digital: false
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
schema:
type: object
properties:
@@ -604,6 +12941,23 @@ paths:
description: delivery zones listed
content:
application/json:
+ example:
+ data:
+ - id: dz_UkLWZg9DAJ
+ name: Domestic
+ description: Maxime illum debitis veritatis porro accusantium laudantium
+ omnis.
+ delivery_profile_id: fp_gbHJdmfrXB
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
type: object
properties:
@@ -616,27 +12970,27 @@ paths:
required:
- data
- meta
- "/api/v3/seller/direct_uploads":
- post:
- summary: Create a direct upload
+ "/api/v3/seller/onboarding":
+ get:
+ summary: Get onboarding checklist
tags:
- - Uploads
+ - Onboarding
security:
- bearer_auth: []
description: |
- Presigns an upload target for a file the seller is about to send.
+ What this marketplace asks of the seller before it will admit them.
- Three steps: post the file's metadata here, `PUT` the bytes to the
- returned `direct_upload.url` with the headers it names, then send the
- returned `signed_id` wherever the file belongs — as a requirement
- submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the
- profile.
+ Singular: the checklist is always the acting seller's. Every answer is
+ computed server-side by the same evaluator the operator's own view uses,
+ so the panel and the operator can never show different progress.
- The blob is attached to nothing at this point. The endpoint that consumes
- the `signed_id` is the one that checks ownership.
+ `progress` counts optional requirements too — it is how far along the
+ checklist is, not how close to approval. Read `blocking` on each
+ requirement for that.
- `checksum` is the file's MD5 digest, base64-encoded — the storage service
- verifies the upload against it.
+ Each requirement's `id` is what a submission is posted against. A
+ marketplace that asks for nothing returns an empty list, which is a
+ complete answer rather than a missing one.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -644,58 +12998,43 @@ paths:
schema:
type: string
responses:
- '201':
- description: upload target created
+ '200':
+ description: checklist returned
content:
application/json:
+ example:
+ status: approved
+ progress:
+ done: 0
+ total: 0
+ requirements: []
schema:
- "$ref": "#/components/schemas/DirectUploadResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- blob:
- type: object
- properties:
- filename:
- type: string
- example: registration.pdf
- byte_size:
- type: integer
- example: 51234
- checksum:
- type: string
- description: Base64-encoded MD5 digest of the file
- example: rL0Y20zC+Fzt72VPzMSk2A==
- content_type:
- type: string
- example: application/pdf
- required:
- - filename
- - byte_size
- - checksum
- - content_type
- required:
- - blob
- "/api/v3/seller/exports":
+ "$ref": "#/components/schemas/SellerOnboardingResponse"
+ '403':
+ description: no seller named, or not a member of it
+ content:
+ application/json:
+ example:
+ error:
+ code: access_denied
+ message: You do not have access to this seller.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/onboarding/submit_for_review":
post:
- summary: Create an export
+ summary: Submit for review
tags:
- - Exports
+ - Onboarding
security:
- bearer_auth: []
description: |
- Queues a CSV of this seller's own records.
-
- Only datasets that can be narrowed to a single seller are offered, so
- an export can never contain another seller's rows however it is
- filtered. The seller and the store come from the request context
- whatever the payload says.
+ Says the seller is ready, moving them from `onboarding` to
+ `ready_for_review`.
- Generation runs in the background: poll `GET /api/v3/seller/exports/{id}`
- until `done` is true, then fetch `download_url`.
+ Refused with `422` when something required is still outstanding — the
+ message names the blocking requirements, and the seller's status is
+ unchanged. Returns the same payload as the checklist so the panel can
+ re-render from one response.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -703,65 +13042,56 @@ paths:
schema:
type: string
responses:
- '201':
- description: export queued
+ '200':
+ description: submitted for review
content:
application/json:
+ example:
+ status: ready_for_review
+ progress:
+ done: 0
+ total: 0
+ requirements: []
schema:
- "$ref": "#/components/schemas/Export"
+ "$ref": "#/components/schemas/SellerOnboardingResponse"
'422':
- description: type cannot be scoped to one seller
+ description: something required is still outstanding
content:
application/json:
+ example:
+ error:
+ code: processing_error
+ message: Requirements Accept terms is not complete
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- type:
- type: string
- enum:
- - orders
- - products
- description: Which dataset to export.
- record_selection:
- type: string
- enum:
- - filtered
- - all
- description: "`filtered` (default) honours `search_params`; `all`
- exports everything this seller owns."
- search_params:
- type: object
- description: Ransack predicates, the same shape the list endpoints
- take. Ignored when `record_selection` is `all`.
- additionalProperties: true
- results_url:
- type: string
- description: Panel URL the export-done email links back to. Honoured
- only when it matches one of the store's allowed origins.
- required:
- - type
- "/api/v3/seller/exports/{id}":
+ "/api/v3/seller/requirements/{requirement_id}/submissions":
parameters:
- - name: id
+ - name: requirement_id
in: path
- description: Export ID
+ description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`
required: true
schema:
type: string
- get:
- summary: Get an export
+ post:
+ summary: Submit against a requirement
tags:
- - Exports
+ - Onboarding
security:
- bearer_auth: []
description: |
- Reads one of this seller's exports. Poll this until `done` is true,
- then fetch `download_url`.
+ What the seller says about one requirement: an attestation they tick, a
+ document they upload, a reference they paste.
+
+ Create only. A submission records what was said and when, so a seller who
+ needs to correct something submits again rather than editing, and the
+ latest one counts.
+
+ `file` is **not** a multipart upload — it is the `signed_id` returned by
+ `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage
+ by the time this runs.
+
+ An attestation is accepted on the spot; a requirement the operator
+ reviews comes back `pending`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -769,37 +13099,70 @@ paths:
schema:
type: string
responses:
- '200':
- description: export found
+ '201':
+ description: submission recorded
content:
application/json:
+ example:
+ id: selsub_UkLWZg9DAJ
+ status: accepted
+ note: Confirmed.
+ review_note:
+ reference:
+ reviewed_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ file_url:
+ file_name:
schema:
- "$ref": "#/components/schemas/Export"
+ "$ref": "#/components/schemas/RequirementSubmission"
'404':
- description: another seller's export
+ description: a requirement belonging to another marketplace
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Seller requirement not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/exports/{id}/download":
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ note:
+ type: string
+ description: Anything the seller wants to say alongside the submission
+ reference:
+ type: string
+ description: A reference number or external identifier, for requirements
+ that ask for one
+ file:
+ type: string
+ description: A direct-upload `signed_id`, for requirements that
+ ask for a document
+ "/api/v3/seller/requirement_submissions/{id}/download":
parameters:
- name: id
in: path
- description: Export ID
+ description: Submission ID
required: true
schema:
type: string
get:
- summary: Download an export
+ summary: Download a submitted document
tags:
- - Exports
+ - Onboarding
security:
- bearer_auth: []
description: |
- Streams the finished CSV.
+ Streams the file attached to one of this seller's submissions.
- The bytes are served by this endpoint rather than through a redirect,
- so the seller's own session authorizes every download.
+ Served through the API rather than from a storage URL on purpose: these
+ are identity and registration documents, so every read is authorized
+ against the acting seller. Another seller's submission answers `404`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -807,87 +13170,97 @@ paths:
schema:
type: string
responses:
- '422':
- description: export is still being written
- content:
- text/csv:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
'404':
- description: another seller's export
+ description: another seller's submission
content:
- text/csv:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Seller requirement submission not found
+ application/octet-stream:
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/orders/{order_id}/fulfillments":
- parameters:
- - name: order_id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
+ "/api/v3/seller/policies":
get:
- summary: List fulfillments
+ summary: List policies
tags:
- - Fulfillments
+ - Policies
security:
- bearer_auth: []
description: |
- The parcels this seller owes on one order.
+ This seller's own policy documents.
- Reached through the order, which is itself fetched through the acting
- seller — so a fulfillment on somebody else's order is unreachable
- whatever ids are sent.
+ Rooted in the acting seller, so the marketplace operator's store
+ policies and every other seller's are invisible here. A seller starts
+ with none: what they are expected to publish is decided by the
+ marketplace's onboarding checklist.
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
responses:
'200':
- description: fulfillments listed
+ description: policies listed
content:
application/json:
+ example:
+ data:
+ - id: pol_uw2YK1rnl0
+ name: Returns Policy
+ slug: returns-policy
+ body: Send anything back within 30 days.
+ body_html: "<p>Send anything back within 30 days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_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/Fulfillment"
+ "$ref": "#/components/schemas/Policy"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
required:
- data
- "/api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill":
- parameters:
- - name: order_id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
- - name: id
- in: path
- description: Prefixed fulfillment ID
- required: true
- schema:
- type: string
- patch:
- summary: Fulfill (ship) a parcel
+ - meta
+ post:
+ summary: Create a policy
tags:
- - Fulfillments
+ - Policies
security:
- bearer_auth: []
description: |
- Marks the parcel shipped.
-
- This is the same workflow the marketplace operator runs, so the
- customer's dispatch email, the label purchase and any extension hooks
- happen exactly as they would had the operator shipped it.
+ Publishes one of this seller's policies. `body` accepts HTML and is
+ sanitized before it is stored.
- `items` narrows the dispatch to part of what the fulfillment holds; the
- remainder splits onto a new one. Omit it to ship the lot.
+ When the marketplace requires a named policy, use that exact name —
+ the onboarding check matches on it.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -895,309 +13268,509 @@ paths:
schema:
type: string
responses:
- '200':
- description: parcel shipped
+ '201':
+ description: policy created
content:
application/json:
+ example:
+ id: pol_OIJLhNcSbf
+ name: Shipping Policy
+ slug: shipping-policy
+ body: Orders leave the workshop within two working days.
+ body_html: "<p>Orders leave the workshop within two working days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/Fulfillment"
+ "$ref": "#/components/schemas/Policy"
requestBody:
content:
application/json:
schema:
type: object
properties:
- tracking:
+ name:
type: string
- description: Carrier tracking number
- tracking_carrier:
+ example: Shipping Policy
+ slug:
type: string
- description: Carrier name
- notify_customer:
- type: boolean
- description: Send the dispatch email (default true)
- items:
- type: array
- description: Ship only these lines; the rest split onto a new fulfillment
- items:
- type: object
- properties:
- item_id:
- type: string
- description: Prefixed line item ID
- quantity:
- type: integer
- required:
- - item_id
- - quantity
- "/api/v3/seller/auth/invitations/{id}/lookup":
+ example: shipping-policy
+ body:
+ type: string
+ example: "<p>Orders leave the workshop within two working days.</p>"
+ required:
+ - name
+ "/api/v3/seller/policies/{id}":
parameters:
- name: id
in: path
- description: Invitation ID from the emailed link
required: true
+ description: Policy prefixed ID or slug
schema:
type: string
get:
- summary: Look up an invitation
+ summary: Get a policy
tags:
- - Authentication
- description: |
- Reads an invitation from the emailed link, before anyone signs in.
-
- The acceptance page needs the invited address to decide whether it is
- asking someone to set a new password or to confirm one they already have.
-
- Unauthenticated — the ID and token in the emailed link are the
- credential. A wrong token is indistinguishable from an unknown
- invitation: both answer `404`, so the endpoint cannot be used to
- enumerate. An invitation onto the store's own staff rather than a seller
- answers `404` here too.
+ - Policies
+ security:
+ - bearer_auth: []
+ description: Returns one of this seller's policies, by prefixed ID or slug.
parameters:
- - name: token
- in: query
+ - name: X-Spree-Seller-Id
+ in: header
required: true
- description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: invitation found
+ description: policy found
content:
application/json:
+ example:
+ id: pol_uw2YK1rnl0
+ name: Returns Policy
+ slug: returns-policy
+ body: Send anything back within 30 days.
+ body_html: "<p>Send anything back within 30 days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/Invitation"
+ "$ref": "#/components/schemas/Policy"
'404':
- description: wrong token, or an invitation that can no longer be accepted
+ description: policy not found
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Policy not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/auth/invitations/{id}/accept":
- parameters:
- - name: id
- in: path
- description: Invitation ID from the emailed link
- required: true
- schema:
- type: string
- post:
- summary: Accept an invitation
+ patch:
+ summary: Update a policy
tags:
- - Authentication
- description: |
- Accepts the invitation and returns a signed-in seller session, so the new
- member lands in the panel rather than on a login form.
-
- The email is never taken from the request — it always comes from the
- invitation, which is what stops the link being redirected to another
- address.
-
- `password` is required when no account exists for the invited address, in
- which case it sets one. When an account already exists, the same field is
- how the person proves the account is theirs.
+ - Policies
+ security:
+ - bearer_auth: []
+ description: Rewrites one of this seller's policies.
parameters:
- - name: token
- in: query
+ - name: X-Spree-Seller-Id
+ in: header
required: true
- description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: invitation accepted, session issued
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/AuthResponse"
- '404':
- description: wrong token, or an invitation that can no longer be accepted
+ description: policy updated
content:
application/json:
+ example:
+ id: pol_uw2YK1rnl0
+ name: Returns Policy
+ slug: returns-policy
+ body: Send anything back within 60 days.
+ body_html: "<p>Send anything back within 60 days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/Policy"
requestBody:
content:
application/json:
schema:
type: object
properties:
- password:
- type: string
- example: password123
- password_confirmation:
+ name:
type: string
- example: password123
- first_name:
+ slug:
type: string
- example: Robin
- last_name:
+ body:
type: string
- example: Ellis
- "/api/v3/seller/invitations":
+ delete:
+ summary: Delete a policy
+ tags:
+ - Policies
+ security:
+ - bearer_auth: []
+ description: Withdraws one of this seller's policies.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: policy deleted
+ "/api/v3/seller/product_types":
get:
- summary: List pending invitations
+ summary: List product types
tags:
- - Team
+ - Product Types
security:
- bearer_auth: []
description: |
- Offers nobody has accepted yet, newest first.
-
- Pending only — an accepted invitation is a team member, and shows up on
- `GET /api/v3/seller/team` instead.
+ The product types a seller may list a product against.
- Sending an invitation lives on `team`, because that is hiring. Chasing or
- withdrawing one is bookkeeping on the offer itself, so it lives here.
+ Read only. A type is the template that hands a product its option types
+ and its delivery profile, so a seller picks one when listing; defining
+ types is the marketplace's. Send the chosen `id` as `product_type_id`
+ on the product.
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
responses:
'200':
- description: invitations listed
+ description: product types listed
content:
application/json:
+ example:
+ data:
+ - id: pt_UkLWZg9DAJ
+ name: Apparel
+ option_type_labels: []
+ 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/Invitation"
+ "$ref": "#/components/schemas/ProductType"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
required:
- data
- "/api/v3/seller/invitations/{id}/resend":
- parameters:
- - name: id
- in: path
- description: Invitation ID
- required: true
- schema:
- type: string
- patch:
- summary: Resend an invitation
+ - meta
+ "/api/v3/seller/product_types/{id}":
+ get:
+ summary: Get a product type
tags:
- - Team
+ - Product Types
security:
- bearer_auth: []
- description: |
- Sends the invitation email again, for a colleague who never got the first
- one. An invitation whose window has closed is refused rather than
- re-sent.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Product type ID
+ schema:
+ type: string
responses:
'200':
- description: invitation resent
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Invitation"
- '404':
- description: another seller's invitation
+ description: product type found
content:
application/json:
+ example:
+ id: pt_UkLWZg9DAJ
+ name: Apparel
+ option_type_labels: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/invitations/{id}":
- parameters:
- - name: id
- in: path
- description: Invitation ID
- required: true
- schema:
- type: string
- delete:
- summary: Revoke an invitation
+ "$ref": "#/components/schemas/ProductType"
+ "/api/v3/seller/products":
+ get:
+ summary: List products
tags:
- - Team
+ - Products
security:
- bearer_auth: []
- description: Withdraws an offer that has not been accepted.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
+ description: |
+ The seller's own catalog — the products they own outright.
+
+ Every call is rooted in the acting seller server-side, so this can never
+ return another seller's product or one the marketplace operator sells
+ first-party.
+ 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: sort
+ in: query
+ required: false
+ description: Sort field; prefix with `-` for descending
+ schema:
+ type: string
responses:
- '204':
- description: invitation revoked
- '404':
- description: another seller's invitation
+ '200':
+ description: products listed
content:
application/json:
+ example:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 1523250
+ slug: product-1523250
+ 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: Maiores ut qui dolores ab autem. Architecto quos sequi
+ minus debitis tempora molestiae. Quasi officiis minus voluptatum
+ eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati
+ ducimus. Provident quo amet nostrum sed assumenda cum odio. Distinctio
+ perferendis quasi nisi exercitationem veritatis minima esse. In
+ velit at corporis nobis. Voluptate mollitia nam pariatur enim.
+ Recusandae necessitatibus earum deserunt sapiente eveniet quidem
+ unde. Consectetur ab perspiciatis veniam dolor tempora. Omnis
+ odit autem quae repellat. Delectus corrupti ea nisi reiciendis
+ atque iure a molestias. Repellendus laboriosam sint molestias
+ debitis in. Minima omnis accusantium modi accusamus doloribus
+ fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.
+ description_html: |-
+ Maiores ut qui dolores ab autem. Architecto quos sequi minus debitis tempora molestiae. Quasi officiis minus voluptatum eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati ducimus. Provident quo amet nostrum sed assumenda cum odio.
+ Distinctio perferendis quasi nisi exercitationem veritatis minima esse. In velit at corporis nobis. Voluptate mollitia nam pariatur enim. Recusandae necessitatibus earum deserunt sapiente eveniet quidem unde.
+ Consectetur ab perspiciatis veniam dolor tempora. Omnis odit autem quae repellat. Delectus corrupti ea nisi reiciendis atque iure a molestias.
+ Repellendus laboriosam sint molestias debitis in. Minima omnis accusantium modi accusamus doloribus fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: active
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/me":
- get:
- summary: Current user
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ post:
+ summary: Create a product
tags:
- - Account
+ - Products
security:
- bearer_auth: []
description: |
- The signed-in user, the sellers they may act for, and what they may do on
- the selected one.
+ Creates a product owned by the acting seller.
- This is the one authenticated endpoint that answers without
- `X-Spree-Seller-Id` — it is what tells the panel which seller to name.
- Sending the header narrows `permission_keys` and `permissions` to that
- seller; without it both are empty, because capability is per seller and
- there is no answer spanning all of them.
+ The seller and the store are taken from the request context whatever the
+ payload says, so a product cannot be created against another seller.
+
+ The operator's own settings — tax category, delivery profile and whether
+ the product is promotionable — are not writable here; they belong to the
+ marketplace, not the seller.
parameters:
- name: X-Spree-Seller-Id
in: header
- required: false
- description: The seller to report capability for. Omit to list sellers without
- narrowing permissions.
+ required: true
schema:
type: string
responses:
- '200':
- description: current user returned
+ '201':
+ description: product created
content:
application/json:
+ example:
+ id: prod_gbHJdmfrXB
+ name: Hand-thrown mug
+ slug: hand-thrown-mug
+ 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:
+ id: price_gbHJdmfrXB
+ amount: '24.0'
+ amount_in_cents: 2400
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$24.00"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: draft
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/SellerMeResponse"
- '401':
- description: missing or invalid token
+ "$ref": "#/components/schemas/Product"
+ '422':
+ description: validation failed
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/onboarding":
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Hand-thrown mug
+ description:
+ type: string
+ slug:
+ type: string
+ example: hand-thrown-mug
+ status:
+ type: string
+ example: draft
+ meta_title:
+ type: string
+ meta_description:
+ type: string
+ meta_keywords:
+ type: string
+ product_type_id:
+ type: string
+ example: ptype_abc123
+ tags:
+ type: array
+ items:
+ type: string
+ example:
+ - ceramics
+ - handmade
+ category_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - cat_abc123
+ metadata:
+ type: object
+ additionalProperties: true
+ prices:
+ type: array
+ items:
+ type: object
+ properties:
+ amount:
+ type: string
+ example: '24.00'
+ compare_at_amount:
+ type: string
+ example: '30.00'
+ currency:
+ type: string
+ example: USD
+ required:
+ - name
+ "/api/v3/seller/products/{id}":
+ parameters:
+ - name: id
+ in: path
+ description: Product ID
+ required: true
+ schema:
+ type: string
get:
- summary: Get onboarding checklist
+ summary: Get a product
tags:
- - Onboarding
+ - Products
security:
- bearer_auth: []
description: |
- What this marketplace asks of the seller before it will admit them.
-
- Singular: the checklist is always the acting seller's. Every answer is
- computed server-side by the same evaluator the operator's own view uses,
- so the panel and the operator can never show different progress.
-
- `progress` counts optional requirements too — it is how far along the
- checklist is, not how close to approval. Read `blocking` on each
- requirement for that.
+ A product the acting seller owns.
- Each requirement's `id` is what a submission is posted against. A
- marketplace that asks for nothing returns an empty list, which is a
- complete answer rather than a missing one.
+ An id belonging to another seller answers `404`, not `403` — the seller
+ is not told the record exists.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1206,32 +13779,77 @@ paths:
type: string
responses:
'200':
- description: checklist returned
+ description: product returned
content:
application/json:
+ example:
+ id: prod_UkLWZg9DAJ
+ name: Product 1556710
+ slug: product-1556710
+ 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: Aliquid voluptate laudantium necessitatibus quidem eaque.
+ Sapiente at autem eveniet exercitationem odio in dolores. Laborum
+ accusantium nulla autem tempora qui inventore assumenda molestiae.
+ Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi
+ eius provident unde neque in. Earum pariatur enim odit delectus
+ accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam
+ ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident
+ at itaque temporibus. Adipisci iste beatae quibusdam perferendis
+ ea blanditiis saepe facilis.
+ description_html: |-
+ Aliquid voluptate laudantium necessitatibus quidem eaque. Sapiente at autem eveniet exercitationem odio in dolores. Laborum accusantium nulla autem tempora qui inventore assumenda molestiae. Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi eius provident unde neque in.
+ Earum pariatur enim odit delectus accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident at itaque temporibus. Adipisci iste beatae quibusdam perferendis ea blanditiis saepe facilis.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: active
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/SellerOnboardingResponse"
- '403':
- description: no seller named, or not a member of it
+ "$ref": "#/components/schemas/Product"
+ '404':
+ description: another seller's product
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Product not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/onboarding/submit_for_review":
- post:
- summary: Submit for review
+ patch:
+ summary: Update a product
tags:
- - Onboarding
+ - Products
security:
- bearer_auth: []
- description: |
- Says the seller is ready, moving them from `onboarding` to
- `ready_for_review`.
-
- Refused with `422` when something required is still outstanding — the
- message names the blocking requirements, and the seller's status is
- unchanged. Returns the same payload as the checklist so the panel can
- re-render from one response.
+ description: Edits a product the acting seller owns.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1240,95 +13858,112 @@ paths:
type: string
responses:
'200':
- description: submitted for review
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/SellerOnboardingResponse"
- '422':
- description: something required is still outstanding
+ description: product updated
content:
application/json:
+ example:
+ id: prod_UkLWZg9DAJ
+ name: Hand-thrown mug, large
+ slug: product-1588212
+ 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: Vel minima recusandae iure deserunt non. Corrupti soluta
+ pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto
+ animi. Eum facilis veniam a consequatur minus. Dolor iure facilis
+ repellendus tenetur. Nobis harum perferendis ab maiores labore eius
+ eum quo.
+ description_html: |-
+ Vel minima recusandae iure deserunt non. Corrupti soluta pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto animi.
+ Eum facilis veniam a consequatur minus. Dolor iure facilis repellendus tenetur. Nobis harum perferendis ab maiores labore eius eum quo.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: active
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/orders":
- get:
- summary: List orders
+ "$ref": "#/components/schemas/Product"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Hand-thrown mug, large
+ description:
+ type: string
+ slug:
+ type: string
+ status:
+ type: string
+ example: active
+ tags:
+ type: array
+ items:
+ type: string
+ category_ids:
+ type: array
+ items:
+ type: string
+ metadata:
+ type: object
+ additionalProperties: true
+ delete:
+ summary: Delete a product
tags:
- - Orders
+ - Products
security:
- bearer_auth: []
- description: |
- What this seller has sold.
-
- On a marketplace a basket spanning several sellers is split into one
- order each, so these are the seller's own orders rather than a filtered
- view of somebody else's — another seller's order is never reachable,
- whatever id is sent.
-
- Checkouts still in flight are left out: until one completes it is
- nobody's order.
+ description: Deletes a product the acting seller owns.
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: sort
- in: query
- required: false
- description: Sort field; prefix with `-` for descending
- schema:
- type: string
responses:
- '200':
- description: orders listed
- content:
- application/json:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Order"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- "/api/v3/seller/orders/{id}":
- parameters:
- - name: id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
+ '204':
+ description: product deleted
+ "/api/v3/seller/profile":
get:
- summary: Get an order
+ summary: Get profile
tags:
- - Orders
+ - Profile
security:
- bearer_auth: []
description: |
- One order, as the seller needs it to pack and post the parcel: the
- lines with their SKUs, where it ships to, and a fulfillment per parcel.
+ The seller's own record.
- How the customer paid the marketplace is deliberately absent — that is
- between the buyer and the operator.
+ Singular by nature: the seller in play is always the one named by
+ `X-Spree-Seller-Id`, never an id in the path — so a seller cannot address
+ another seller here even by guessing one.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1337,135 +13972,122 @@ paths:
type: string
responses:
'200':
- description: order found
+ description: profile returned
content:
application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Seller 69
+ slug: seller-69
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: approved
+ legal_name:
+ registration_number:
+ contact_email:
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ holiday_mode_until:
+ terms_accepted_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: true
+ default_currency: USD
+ supported_currencies:
+ - USD
+ - EUR
+ - GBP
+ products_count: 0
schema:
- "$ref": "#/components/schemas/Order"
- '404':
- description: another seller's order
+ "$ref": "#/components/schemas/Profile"
+ '403':
+ description: no seller named, or not a member of it
content:
application/json:
+ example:
+ error:
+ code: access_denied
+ message: You do not have access to this seller.
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/orders/{id}/cancel":
- parameters:
- - name: id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
patch:
- summary: Cancel an order
+ summary: Update profile
tags:
- - Orders
+ - Profile
security:
- bearer_auth: []
description: |
- Withdraws from an order this seller cannot fulfil.
-
- Restocking and any refund are the cancellation's own concern, so a
- seller cannot cancel without the money and the stock following.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: order canceled
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Order"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- notify_customer:
- type: boolean
- description: Email the customer about the cancellation
- "/api/v3/seller/auth/password_resets":
- post:
- summary: Request password reset
- tags:
- - Authentication
- description: |
- Requests a password reset email for a seller.
+ Edits presentation, contact details and addresses.
- Unauthenticated. Always answers `202`, whether or not the address
- belongs to a seller, so this cannot be used to discover which accounts
- exist. A store staff member who runs no seller is treated as no match:
- they have no seller panel to be sent to.
+ Readable but **not** writable, by design: `status` — the lifecycle belongs
+ to the marketplace operator's workflows — the settlement terms, and
+ `slug`, since a seller renaming their own storefront address would break
+ every link pointing at it.
- `redirect_url` is where the emailed link should point, with the reset
- token appended as a `token` query param. It is honoured only when it
- matches one of the store's allowed origins; otherwise it is silently
- ignored and the server resolves the seller panel origin itself. The
- email is delivered by Spree via the
- `seller_user.password_reset_requested` event, which is never forwarded
- to webhook endpoints.
- parameters: []
- responses:
- '202':
- description: reset requested
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- redirect_url:
- type: string
- example: https://sellers.your-store.com/reset-password
- description: Must match an allowed origin of the store; ignored
- otherwise.
- required:
- - email
- "/api/v3/seller/auth/password_resets/{id}":
- patch:
- summary: Reset password
- tags:
- - Authentication
- description: |
- Spends a password reset token (the `token` query param from the emailed
- link), sets the new password and signs the seller in: the response
- carries a seller JWT and the rotatable refresh token is set in an
- HttpOnly cookie, so they land in the panel rather than on a login form.
+ `accept_terms: true` stamps the moment the seller accepted the
+ marketplace's terms, which is what the matching onboarding requirement
+ reads. One-way — sending `false` does not unmake the stamp.
- The token is single-use, and resetting revokes every other session the
- account holds. A token whose seller membership has since been revoked is
- refused exactly as an expired one.
+ `custom_fields` is narrowed server-side to the definitions this
+ marketplace's onboarding actually asks this seller for; a field nothing
+ asked for is ignored rather than written.
parameters:
- - name: id
- in: path
- description: The reset token from the emailed link
+ - name: X-Spree-Seller-Id
+ in: header
required: true
schema:
type: string
responses:
'200':
- description: password reset
+ description: profile updated
content:
application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Acme Supplies
+ slug: seller-71
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ status: approved
+ legal_name:
+ registration_number:
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ holiday_mode_until:
+ terms_accepted_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: true
+ default_currency: USD
+ supported_currencies:
+ - USD
+ - EUR
+ - GBP
+ products_count: 0
schema:
- "$ref": "#/components/schemas/AuthResponse"
+ "$ref": "#/components/schemas/Profile"
'422':
- description: invalid or expired token
+ description: validation failed
content:
application/json:
example:
error:
- code: password_reset_token_invalid
- message: Password reset token is invalid or has expired.
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -1474,29 +14096,68 @@ paths:
schema:
type: object
properties:
- password:
+ name:
type: string
- example: new-password-123
- password_confirmation:
+ example: Acme Supplies
+ contact_email:
type: string
- example: new-password-123
- required:
- - password
- - password_confirmation
- "/api/v3/seller/policies":
+ format: email
+ nullable: true
+ billing_email:
+ type: string
+ format: email
+ nullable: true
+ about:
+ type: string
+ nullable: true
+ description: Sanitized HTML — the seller's public description
+ legal_name:
+ type: string
+ nullable: true
+ description: The business a commission invoice is made out to
+ registration_number:
+ type: string
+ nullable: true
+ logo:
+ type: string
+ nullable: true
+ description: ActiveStorage signed id; `null` removes the attachment
+ square_logo:
+ type: string
+ nullable: true
+ cover_photo:
+ type: string
+ nullable: true
+ accept_terms:
+ type: boolean
+ description: Stamps acceptance of the marketplace terms
+ billing_address:
+ type: object
+ additionalProperties: true
+ custom_fields:
+ type: array
+ items:
+ type: object
+ properties:
+ custom_field_definition_id:
+ type: string
+ example: cfd_abc123
+ value:
+ description: Any JSON value the definition accepts
+ "/api/v3/seller/stock_locations":
get:
- summary: List policies
+ summary: List stock locations
tags:
- - Policies
+ - Stock Locations
security:
- bearer_auth: []
description: |
- This seller's own policy documents.
+ Where this seller keeps stock, and so where their returns are sent.
- Rooted in the acting seller, so the marketplace operator's store
- policies and every other seller's are invisible here. A seller starts
- with none: what they are expected to publish is decided by the
- marketplace's onboarding checklist.
+ Rooted in the acting seller, so the marketplace operator's own warehouses
+ never appear here.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1515,35 +14176,72 @@ paths:
description: Records per page (max 100)
schema:
type: integer
+ - name: sort
+ in: query
+ required: false
+ description: Sort field; prefix with `-` for descending
+ schema:
+ type: string
responses:
'200':
- description: policies listed
+ description: stock locations listed
content:
application/json:
+ example:
+ data:
+ - id: sloc_UkLWZg9DAJ
+ name: Lesha Stroman
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ 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/Policy"
+ "$ref": "#/components/schemas/StockLocation"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
- summary: Create a policy
+ summary: Create a stock location
tags:
- - Policies
+ - Stock Locations
security:
- bearer_auth: []
description: |
- Publishes one of this seller's policies. `body` accepts HTML and is
- sanitized before it is stored.
+ Adds a place this seller ships from.
- When the marketplace requires a named policy, use that exact name —
- the onboarding check matches on it.
+ The seller and the store come from the request context whatever the
+ payload says.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1552,11 +14250,45 @@ paths:
type: string
responses:
'201':
- description: policy created
+ description: stock location created
content:
application/json:
+ example:
+ id: sloc_gbHJdmfrXB
+ name: Main warehouse
+ address1:
+ city: Portland
+ zipcode:
+ country_code: US
+ country_name: United States
+ state_code:
+ state_text:
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone:
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/Policy"
+ "$ref": "#/components/schemas/StockLocation"
+ '422':
+ description: validation failed
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
@@ -1565,30 +14297,66 @@ paths:
properties:
name:
type: string
- example: Shipping Policy
- slug:
+ example: Main warehouse
+ company:
type: string
- example: shipping-policy
- body:
+ nullable: true
+ address1:
type: string
- example: "<p>Orders leave the workshop within two working days.</p>"
+ nullable: true
+ example: 1 Kiln Lane
+ address2:
+ type: string
+ nullable: true
+ city:
+ type: string
+ nullable: true
+ example: Portland
+ zipcode:
+ type: string
+ nullable: true
+ example: '97205'
+ country_code:
+ type: string
+ nullable: true
+ example: US
+ state_code:
+ type: string
+ nullable: true
+ example: OR
+ state_name:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ active:
+ type: boolean
+ description: Set `false` to retire a location — there is no delete
+ default:
+ type: boolean
+ kind:
+ type: string
+ example: warehouse
required:
- name
- "/api/v3/seller/policies/{id}":
+ "/api/v3/seller/stock_locations/{id}":
parameters:
- name: id
in: path
+ description: Stock location ID
required: true
- description: Policy prefixed ID or slug
schema:
type: string
get:
- summary: Get a policy
+ summary: Get a stock location
tags:
- - Policies
+ - Stock Locations
security:
- bearer_auth: []
- description: Returns one of this seller's policies, by prefixed ID or slug.
+ description: |
+ A stock location the acting seller owns. An id belonging to another
+ seller — or to the marketplace operator — answers `404`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1597,24 +14365,54 @@ paths:
type: string
responses:
'200':
- description: policy found
+ description: stock location returned
content:
application/json:
+ example:
+ id: sloc_UkLWZg9DAJ
+ name: Marsha Turner
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/Policy"
+ "$ref": "#/components/schemas/StockLocation"
'404':
- description: policy not found
+ description: another seller's stock location
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Stock location not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update a policy
+ summary: Update a stock location
tags:
- - Policies
+ - Stock Locations
security:
- bearer_auth: []
- description: Rewrites one of this seller's policies.
+ description: |
+ Edits a stock location the acting seller owns.
+
+ There is no delete: a location holds stock levels and is named on
+ historical fulfillments, so a seller retires one by setting `active` to
+ `false`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1623,11 +14421,32 @@ paths:
type: string
responses:
'200':
- description: policy updated
+ description: stock location updated
content:
application/json:
+ example:
+ id: sloc_UkLWZg9DAJ
+ name: Kiln Lane warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/Policy"
+ "$ref": "#/components/schemas/StockLocation"
requestBody:
content:
application/json:
@@ -1636,170 +14455,91 @@ paths:
properties:
name:
type: string
- slug:
- type: string
- body:
+ example: Main warehouse
+ address1:
type: string
- delete:
- summary: Delete a policy
- tags:
- - Policies
- security:
- - bearer_auth: []
- description: Withdraws one of this seller's policies.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '204':
- description: policy deleted
- "/api/v3/seller/product_types":
- get:
- summary: List product types
- tags:
- - Product Types
- security:
- - bearer_auth: []
- description: |
- The product types a seller may list a product against.
-
- Read only. A type is the template that hands a product its option types
- and its delivery profile, so a seller picks one when listing; defining
- types is the marketplace's. Send the chosen `id` as `product_type_id`
- on the product.
- 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
- responses:
- '200':
- description: product types listed
- content:
- application/json:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/ProductType"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- "/api/v3/seller/product_types/{id}":
- get:
- summary: Get a product type
- tags:
- - Product Types
- security:
- - bearer_auth: []
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Product type ID
- schema:
- type: string
- responses:
- '200':
- description: product type found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ProductType"
- "/api/v3/seller/products":
+ nullable: true
+ city:
+ type: string
+ nullable: true
+ zipcode:
+ type: string
+ nullable: true
+ country_code:
+ type: string
+ nullable: true
+ state_code:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ active:
+ type: boolean
+ default:
+ type: boolean
+ "/api/v3/seller/invitations":
get:
- summary: List products
+ summary: List pending invitations
tags:
- - Products
+ - Team
security:
- bearer_auth: []
description: |
- The seller's own catalog — the products they own outright.
+ Offers nobody has accepted yet, newest first.
- Every call is rooted in the acting seller server-side, so this can never
- return another seller's product or one the marketplace operator sells
- first-party.
+ Pending only — an accepted invitation is a team member, and shows up on
+ `GET /api/v3/seller/team` instead.
+
+ Sending an invitation lives on `team`, because that is hiring. Chasing or
+ withdrawing one is bookkeeping on the offer itself, so it lives here.
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: sort
- in: query
- required: false
- description: Sort field; prefix with `-` for descending
- schema:
- type: string
responses:
'200':
- description: products listed
+ description: invitations listed
content:
application/json:
+ example:
+ data:
+ - id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=gybGAXxVP79yKWNTZLAC94ui"
schema:
type: object
properties:
data:
type: array
items:
- "$ref": "#/components/schemas/Product"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
+ "$ref": "#/components/schemas/Invitation"
required:
- data
- - meta
- post:
- summary: Create a product
+ "/api/v3/seller/invitations/{id}/resend":
+ parameters:
+ - name: id
+ in: path
+ description: Invitation ID
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Resend an invitation
tags:
- - Products
+ - Team
security:
- bearer_auth: []
description: |
- Creates a product owned by the acting seller.
-
- The seller and the store are taken from the request context whatever the
- payload says, so a product cannot be created against another seller.
-
- The operator's own settings — tax category, delivery profile and whether
- the product is promotionable — are not writable here; they belong to the
- marketplace, not the seller.
+ Sends the invitation email again, for a colleague who never got the first
+ one. An invitation whose window has closed is refused rather than
+ re-sent.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1807,95 +14547,76 @@ paths:
schema:
type: string
responses:
- '201':
- description: product created
+ '200':
+ description: invitation resent
content:
application/json:
+ example:
+ id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3uJFfKUSiHtnc9TGAXMJUXsB"
schema:
- "$ref": "#/components/schemas/Product"
- '422':
- description: validation failed
+ "$ref": "#/components/schemas/Invitation"
+ '404':
+ description: another seller's invitation
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Invitation not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Hand-thrown mug
- description:
- type: string
- slug:
- type: string
- example: hand-thrown-mug
- status:
- type: string
- example: draft
- meta_title:
- type: string
- meta_description:
- type: string
- meta_keywords:
- type: string
- product_type_id:
- type: string
- example: ptype_abc123
- tags:
- type: array
- items:
- type: string
- example:
- - ceramics
- - handmade
- category_ids:
- type: array
- items:
- type: string
- example:
- - cat_abc123
- metadata:
- type: object
- additionalProperties: true
- prices:
- type: array
- items:
- type: object
- properties:
- amount:
- type: string
- example: '24.00'
- compare_at_amount:
- type: string
- example: '30.00'
- currency:
- type: string
- example: USD
- required:
- - name
- "/api/v3/seller/products/{id}":
+ "/api/v3/seller/invitations/{id}":
parameters:
- name: id
in: path
- description: Product ID
+ description: Invitation ID
required: true
schema:
type: string
+ delete:
+ summary: Revoke an invitation
+ tags:
+ - Team
+ security:
+ - bearer_auth: []
+ description: Withdraws an offer that has not been accepted.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: invitation revoked
+ '404':
+ description: another seller's invitation
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Invitation not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/team":
get:
- summary: Get a product
+ summary: List team members
tags:
- - Products
+ - Team
security:
- bearer_auth: []
description: |
- A product the acting seller owns.
+ The people who run this seller.
- An id belonging to another seller answers `404`, not `403` — the seller
- is not told the record exists.
+ Rooted at the acting seller throughout, so a seller only ever sees their
+ own team. Unpaginated — a seller's team is small by nature.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1904,24 +14625,43 @@ paths:
type: string
responses:
'200':
- description: product returned
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Product"
- '404':
- description: another seller's product
+ description: team members listed
content:
application/json:
+ example:
+ data:
+ - id: adm_UkLWZg9DAJ
+ first_name: Bill
+ last_name: Towne
+ full_name: Bill Towne
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a product
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/TeamMember"
+ required:
+ - data
+ post:
+ summary: Invite a team member
tags:
- - Products
+ - Team
security:
- bearer_auth: []
- description: Edits a product the acting seller owns.
+ description: |
+ Invites a colleague onto this seller's team. They join when they accept,
+ on the same invitation rail — and the same email — the marketplace
+ operator's own invitations use.
+
+ Hiring is not a lifecycle transition: a trading seller's status is
+ untouched by taking someone on.
+
+ The role is not a parameter. Every member holds the seller's own seeded
+ role, which already carries the whole seller vocabulary.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1929,46 +14669,66 @@ paths:
schema:
type: string
responses:
- '200':
- description: product updated
+ '201':
+ description: invitation sent
content:
application/json:
+ example:
+ id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3K6BfBtHGFeQgToPE45qUDWE"
schema:
- "$ref": "#/components/schemas/Product"
+ "$ref": "#/components/schemas/Invitation"
+ '422':
+ description: validation failed
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Email is invalid and Email can't be blank
+ details:
+ email:
+ - is invalid
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
- properties:
- name:
- type: string
- example: Hand-thrown mug, large
- description:
- type: string
- slug:
- type: string
- status:
+ properties:
+ email:
type: string
- example: active
- tags:
- type: array
- items:
- type: string
- category_ids:
- type: array
- items:
- type: string
- metadata:
- type: object
- additionalProperties: true
+ format: email
+ required:
+ - email
+ "/api/v3/seller/team/{id}":
+ parameters:
+ - name: id
+ in: path
+ description: Team member (user) ID
+ required: true
+ schema:
+ type: string
delete:
- summary: Delete a product
+ summary: Remove a team member
tags:
- - Products
+ - Team
security:
- bearer_auth: []
- description: Deletes a product the acting seller owns.
+ description: |
+ Revokes a member's access, removing every role they hold on this seller.
+
+ The team can never reach zero: emptying it would leave a seller nobody
+ can sign in to, and only the marketplace operator could put someone back.
+ The last remaining member is refused with `422`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1977,20 +14737,49 @@ paths:
type: string
responses:
'204':
- description: product deleted
- "/api/v3/seller/profile":
- get:
- summary: Get profile
+ description: member removed
+ '422':
+ description: cannot remove the last remaining member
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: A seller needs at least one team member. Invite someone
+ else before removing this one.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '404':
+ description: not a member of this seller
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Admin user not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/direct_uploads":
+ post:
+ summary: Create a direct upload
tags:
- - Profile
+ - Uploads
security:
- bearer_auth: []
description: |
- The seller's own record.
+ Presigns an upload target for a file the seller is about to send.
- Singular by nature: the seller in play is always the one named by
- `X-Spree-Seller-Id`, never an id in the path — so a seller cannot address
- another seller here even by guessing one.
+ Three steps: post the file's metadata here, `PUT` the bytes to the
+ returned `direct_upload.url` with the headers it names, then send the
+ returned `signed_id` wherever the file belongs — as a requirement
+ submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the
+ profile.
+
+ The blob is attached to nothing at this point. The endpoint that consumes
+ the `signed_id` is the one that checks ownership.
+
+ `checksum` is the file's MD5 digest, base64-encoded — the storage service
+ verifies the upload against it.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -1998,39 +14787,64 @@ paths:
schema:
type: string
responses:
- '200':
- description: profile returned
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Profile"
- '403':
- description: no seller named, or not a member of it
+ '201':
+ description: upload target created
content:
application/json:
+ example:
+ direct_upload:
+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--e33ffe2f2fc04d65ca4ba6c757dd23060ca71420
+ headers:
+ Content-Type: application/pdf
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update profile
+ "$ref": "#/components/schemas/DirectUploadResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ blob:
+ type: object
+ properties:
+ filename:
+ type: string
+ example: registration.pdf
+ byte_size:
+ type: integer
+ example: 51234
+ checksum:
+ type: string
+ description: Base64-encoded MD5 digest of the file
+ example: rL0Y20zC+Fzt72VPzMSk2A==
+ content_type:
+ type: string
+ example: application/pdf
+ required:
+ - filename
+ - byte_size
+ - checksum
+ - content_type
+ required:
+ - blob
+ "/api/v3/seller/exports":
+ post:
+ summary: Create an export
tags:
- - Profile
+ - Exports
security:
- bearer_auth: []
description: |
- Edits presentation, contact details and addresses.
-
- Readable but **not** writable, by design: `status` — the lifecycle belongs
- to the marketplace operator's workflows — the settlement terms, and
- `slug`, since a seller renaming their own storefront address would break
- every link pointing at it.
+ Queues a CSV of this seller's own records.
- `accept_terms: true` stamps the moment the seller accepted the
- marketplace's terms, which is what the matching onboarding requirement
- reads. One-way — sending `false` does not unmake the stamp.
+ Only datasets that can be narrowed to a single seller are offered, so
+ an export can never contain another seller's rows however it is
+ filtered. The seller and the store come from the request context
+ whatever the payload says.
- `custom_fields` is narrowed server-side to the definitions this
- marketplace's onboarding actually asks this seller for; a field nothing
- asked for is ignored rather than written.
+ Generation runs in the background: poll `GET /api/v3/seller/exports/{id}`
+ until `done` is true, then fetch `download_url`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -2038,16 +14852,32 @@ paths:
schema:
type: string
responses:
- '200':
- description: profile updated
+ '201':
+ description: export queued
content:
application/json:
+ example:
+ id: exp_UkLWZg9DAJ
+ number: EF1001
+ format: csv
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: orders
+ user_id: adm_UkLWZg9DAJ
+ done: false
+ filename:
+ byte_size:
+ download_url:
schema:
- "$ref": "#/components/schemas/Profile"
+ "$ref": "#/components/schemas/Export"
'422':
- description: validation failed
+ description: type cannot be scoped to one seller
content:
application/json:
+ example:
+ error:
+ code: validation_error
+ message: 'Unsupported export type. Supported types: orders, products'
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -2056,140 +14886,101 @@ paths:
schema:
type: object
properties:
- name:
- type: string
- example: Acme Supplies
- contact_email:
- type: string
- format: email
- nullable: true
- billing_email:
- type: string
- format: email
- nullable: true
- about:
- type: string
- nullable: true
- description: Sanitized HTML — the seller's public description
- legal_name:
- type: string
- nullable: true
- description: The business a commission invoice is made out to
- registration_number:
- type: string
- nullable: true
- logo:
- type: string
- nullable: true
- description: ActiveStorage signed id; `null` removes the attachment
- square_logo:
+ type:
type: string
- nullable: true
- cover_photo:
+ enum:
+ - orders
+ - products
+ description: Which dataset to export.
+ record_selection:
type: string
- nullable: true
- accept_terms:
- type: boolean
- description: Stamps acceptance of the marketplace terms
- billing_address:
+ enum:
+ - filtered
+ - all
+ description: "`filtered` (default) honours `search_params`; `all`
+ exports everything this seller owns."
+ search_params:
type: object
+ description: Ransack predicates, the same shape the list endpoints
+ take. Ignored when `record_selection` is `all`.
additionalProperties: true
- custom_fields:
- type: array
- items:
- type: object
- properties:
- custom_field_definition_id:
- type: string
- example: cfd_abc123
- value:
- description: Any JSON value the definition accepts
- "/api/v3/seller/requirements/{requirement_id}/submissions":
+ results_url:
+ type: string
+ description: Panel URL the export-done email links back to. Honoured
+ only when it matches one of the store's allowed origins.
+ required:
+ - type
+ "/api/v3/seller/exports/{id}":
parameters:
- - name: requirement_id
+ - name: id
in: path
- description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`
+ description: Export ID
required: true
schema:
type: string
- post:
- summary: Submit against a requirement
+ get:
+ summary: Get an export
tags:
- - Onboarding
+ - Exports
security:
- bearer_auth: []
description: |
- What the seller says about one requirement: an attestation they tick, a
- document they upload, a reference they paste.
-
- Create only. A submission records what was said and when, so a seller who
- needs to correct something submits again rather than editing, and the
- latest one counts.
-
- `file` is **not** a multipart upload — it is the `signed_id` returned by
- `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage
- by the time this runs.
-
- An attestation is accepted on the spot; a requirement the operator
- reviews comes back `pending`.
+ Reads one of this seller's exports. Poll this until `done` is true,
+ then fetch `download_url`.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
schema:
type: string
- responses:
- '201':
- description: submission recorded
+ responses:
+ '200':
+ description: export found
content:
application/json:
+ example:
+ id: exp_UkLWZg9DAJ
+ number: EF1001
+ format: csv
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: orders
+ user_id: adm_UkLWZg9DAJ
+ done: false
+ filename:
+ byte_size:
+ download_url:
schema:
- "$ref": "#/components/schemas/RequirementSubmission"
+ "$ref": "#/components/schemas/Export"
'404':
- description: a requirement belonging to another marketplace
+ description: another seller's export
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Export not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- note:
- type: string
- description: Anything the seller wants to say alongside the submission
- reference:
- type: string
- description: A reference number or external identifier, for requirements
- that ask for one
- file:
- type: string
- description: A direct-upload `signed_id`, for requirements that
- ask for a document
- "/api/v3/seller/requirement_submissions/{id}/download":
+ "/api/v3/seller/exports/{id}/download":
parameters:
- name: id
in: path
- description: Submission ID
+ description: Export ID
required: true
schema:
type: string
get:
- summary: Download a submitted document
+ summary: Download an export
tags:
- - Onboarding
+ - Exports
security:
- bearer_auth: []
description: |
- Streams the file attached to one of this seller's submissions.
+ Streams the finished CSV.
- Served through the API rather than from a storage URL on purpose: these
- are identity and registration documents, so every read is authorized
- against the acting seller. Another seller's submission answers `404`.
+ The bytes are served by this endpoint rather than through a redirect,
+ so the seller's own session authorizes every download.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -2197,76 +14988,132 @@ paths:
schema:
type: string
responses:
+ '422':
+ description: export is still being written
+ content:
+ application/json:
+ example:
+ error:
+ code: export_not_ready
+ message: Export is not ready yet
+ text/csv:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
'404':
- description: another seller's submission
+ description: another seller's export
content:
- application/octet-stream:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Export not found
+ text/csv:
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/stock_locations":
+ "/api/v3/seller/orders/{order_id}/fulfillments":
+ parameters:
+ - name: order_id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
get:
- summary: List stock locations
+ summary: List fulfillments
tags:
- - Stock Locations
+ - Fulfillments
security:
- bearer_auth: []
description: |
- Where this seller keeps stock, and so where their returns are sent.
+ The parcels this seller owes on one order.
- Rooted in the acting seller, so the marketplace operator's own warehouses
- never appear here.
+ Reached through the order, which is itself fetched through the acting
+ seller — so a fulfillment on somebody else's order is unreachable
+ whatever ids are sent.
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: sort
- in: query
- required: false
- description: Sort field; prefix with `-` for descending
- schema:
- type: string
responses:
'200':
- description: stock locations listed
+ description: fulfillments listed
content:
application/json:
+ example:
+ data:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground
+ stock_location_name: Vernie Lehner
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ name: Product 1459315
+ sku: SKU-184
+ options_text: ''
+ deliveries:
+ - 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:
+ labels: []
schema:
type: object
properties:
data:
type: array
items:
- "$ref": "#/components/schemas/StockLocation"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
+ "$ref": "#/components/schemas/Fulfillment"
required:
- data
- - meta
- post:
- summary: Create a stock location
+ "/api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill":
+ parameters:
+ - name: order_id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ description: Prefixed fulfillment ID
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Fulfill (ship) a parcel
tags:
- - Stock Locations
+ - Fulfillments
security:
- bearer_auth: []
description: |
- Adds a place this seller ships from.
+ Marks the parcel shipped.
- The seller and the store come from the request context whatever the
- payload says.
+ This is the same workflow the marketplace operator runs, so the
+ customer's dispatch email, the label purchase and any extension hooks
+ happen exactly as they would had the operator shipped it.
+
+ `items` narrows the dispatch to part of what the fulfillment holds; the
+ remainder splits onto a new one. Omit it to ship the lot.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -2274,86 +15121,273 @@ paths:
schema:
type: string
responses:
- '201':
- description: stock location created
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/StockLocation"
- '422':
- description: validation failed
+ '200':
+ description: parcel shipped
content:
application/json:
+ example:
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: fulfilled
+ tracking: TRACK-1
+ tracking_url:
+ fulfilled_at: '2026-01-15T12:00:00.000Z'
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground
+ stock_location_name: Mirta Herman
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ name: Product 146961
+ sku: SKU-185
+ options_text: ''
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: TRACK-1
+ 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:
+ labels: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/Fulfillment"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Main warehouse
- company:
- type: string
- nullable: true
- address1:
- type: string
- nullable: true
- example: 1 Kiln Lane
- address2:
- type: string
- nullable: true
- city:
- type: string
- nullable: true
- example: Portland
- zipcode:
- type: string
- nullable: true
- example: '97205'
- country_code:
- type: string
- nullable: true
- example: US
- state_code:
- type: string
- nullable: true
- example: OR
- state_name:
+ tracking:
type: string
- nullable: true
- phone:
+ description: Carrier tracking number
+ tracking_carrier:
type: string
- nullable: true
- active:
- type: boolean
- description: Set `false` to retire a location — there is no delete
- default:
+ description: Carrier name
+ notify_customer:
type: boolean
- kind:
- type: string
- example: warehouse
- required:
- - name
- "/api/v3/seller/stock_locations/{id}":
+ description: Send the dispatch email (default true)
+ items:
+ type: array
+ description: Ship only these lines; the rest split onto a new fulfillment
+ items:
+ type: object
+ properties:
+ item_id:
+ type: string
+ description: Prefixed line item ID
+ quantity:
+ type: integer
+ required:
+ - item_id
+ - quantity
+ "/api/v3/seller/orders":
+ get:
+ summary: List orders
+ tags:
+ - Orders
+ security:
+ - bearer_auth: []
+ description: |
+ What this seller has sold.
+
+ On a marketplace a basket spanning several sellers is split into one
+ order each, so these are the seller's own orders rather than a filtered
+ view of somebody else's — another seller's order is never reachable,
+ whatever id is sent.
+
+ Checkouts still in flight are left out: until one completes it is
+ nobody's order.
+ 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: sort
+ in: query
+ required: false
+ description: Sort field; prefix with `-` for descending
+ schema:
+ type: string
+ responses:
+ '200':
+ description: orders listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: placed
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 14795
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-186
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground
+ stock_location_name: Roseline Roberts
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ name: Product 14795
+ sku: SKU-186
+ options_text: ''
+ deliveries:
+ - 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:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 135 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
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 134 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
+ 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/Order"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ "/api/v3/seller/orders/{id}":
parameters:
- name: id
in: path
- description: Stock location ID
+ description: Prefixed order ID
required: true
schema:
type: string
get:
- summary: Get a stock location
+ summary: Get an order
tags:
- - Stock Locations
+ - Orders
security:
- bearer_auth: []
description: |
- A stock location the acting seller owns. An id belonging to another
- seller — or to the marketplace operator — answers `404`.
+ One order, as the seller needs it to pack and post the parcel: the
+ lines with their SKUs, where it ships to, and a fulfillment per parcel.
+
+ How the customer paid the marketplace is deliberately absent — that is
+ between the buyer and the operator.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -2362,50 +15396,149 @@ paths:
type: string
responses:
'200':
- description: stock location returned
+ description: order found
content:
application/json:
example:
- id: sloc_UkLWZg9DAJ
- name: Marsha Turner
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- address2:
- state_name:
- phone: "(202) 456-1111"
- company:
- active: true
- default: false
- kind: warehouse
+ id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: placed
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 1489755
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-187
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground
+ stock_location_name: Woodrow Hand
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ name: Product 1489755
+ sku: SKU-187
+ options_text: ''
+ deliveries:
+ - 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:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 137 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
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 136 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
schema:
- "$ref": "#/components/schemas/StockLocation"
+ "$ref": "#/components/schemas/Order"
'404':
- description: another seller's stock location
+ description: another seller's order
content:
application/json:
+ example:
+ error:
+ code: order_not_found
+ message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/orders/{id}/cancel":
+ parameters:
+ - name: id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
patch:
- summary: Update a stock location
+ summary: Cancel an order
tags:
- - Stock Locations
+ - Orders
security:
- bearer_auth: []
description: |
- Edits a stock location the acting seller owns.
+ Withdraws from an order this seller cannot fulfil.
- There is no delete: a location holds stock levels and is named on
- historical fulfillments, so a seller retires one by setting `active` to
- `false`.
+ Restocking and any refund are the cancellation's own concern, so a
+ seller cannot cancel without the money and the stock following.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -2414,42 +15547,129 @@ paths:
type: string
responses:
'200':
- description: stock location updated
+ description: order canceled
content:
application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: canceled
+ fulfillment_status: canceled
+ payment_status: none
+ completed_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 1516554
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-190
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: canceled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground
+ stock_location_name: Ricky Kutch
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ name: Product 1516554
+ sku: SKU-190
+ options_text: ''
+ deliveries:
+ - 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:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 143 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
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 142 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
schema:
- "$ref": "#/components/schemas/StockLocation"
+ "$ref": "#/components/schemas/Order"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Main warehouse
- address1:
- type: string
- nullable: true
- city:
- type: string
- nullable: true
- zipcode:
- type: string
- nullable: true
- country_code:
- type: string
- nullable: true
- state_code:
- type: string
- nullable: true
- phone:
- type: string
- nullable: true
- active:
- type: boolean
- default:
+ notify_customer:
type: boolean
+ description: Email the customer about the cancellation
"/api/v3/seller/tax_identifiers":
get:
summary: List tax registrations
@@ -2474,6 +15694,25 @@ paths:
responses:
'200':
description: registrations returned
+ content:
+ application/json:
+ example:
+ data:
+ - id: txi_UkLWZg9DAJ
+ kind: eu_vat
+ value: DE100000008
+ validation_status:
+ validated_at:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
post:
summary: Add a tax registration
tags:
@@ -2497,8 +15736,25 @@ paths:
responses:
'201':
description: registration recorded
+ content:
+ application/json:
+ example:
+ id: txi_UkLWZg9DAJ
+ kind: eu_vat
+ value: DE100000008
+ validation_status:
+ validated_at:
'422':
description: the number is not valid for its regime
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Number does not look like a valid EU VAT registration
+ details:
+ value:
+ - does not look like a valid EU VAT registration
requestBody:
content:
application/json:
@@ -2539,6 +15795,14 @@ paths:
responses:
'200':
description: registration corrected
+ content:
+ application/json:
+ example:
+ id: txi_UkLWZg9DAJ
+ kind: eu_vat
+ value: DE100000016
+ validation_status:
+ validated_at:
requestBody:
content:
application/json:
@@ -2594,126 +15858,13 @@ paths:
responses:
'422':
description: no registry validator is installed for this kind
- "/api/v3/seller/team":
- get:
- summary: List team members
- tags:
- - Team
- security:
- - bearer_auth: []
- description: |
- The people who run this seller.
-
- Rooted at the acting seller throughout, so a seller only ever sees their
- own team. Unpaginated — a seller's team is small by nature.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: team members listed
- content:
- application/json:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/TeamMember"
- required:
- - data
- post:
- summary: Invite a team member
- tags:
- - Team
- security:
- - bearer_auth: []
- description: |
- Invites a colleague onto this seller's team. They join when they accept,
- on the same invitation rail — and the same email — the marketplace
- operator's own invitations use.
-
- Hiring is not a lifecycle transition: a trading seller's status is
- untouched by taking someone on.
-
- The role is not a parameter. Every member holds the seller's own seeded
- role, which already carries the whole seller vocabulary.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '201':
- description: invitation sent
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Invitation"
- '422':
- description: validation failed
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- required:
- - email
- "/api/v3/seller/team/{id}":
- parameters:
- - name: id
- in: path
- description: Team member (user) ID
- required: true
- schema:
- type: string
- delete:
- summary: Remove a team member
- tags:
- - Team
- security:
- - bearer_auth: []
- description: |
- Revokes a member's access, removing every role they hold on this seller.
-
- The team can never reach zero: emptying it would leave a seller nobody
- can sign in to, and only the marketplace operator could put someone back.
- The last remaining member is refused with `422`.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '204':
- description: member removed
- '422':
- description: cannot remove the last remaining member
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: not a member of this seller
content:
application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ example:
+ error:
+ code: tax_id_not_validatable
+ message: No registry validator is installed for tax identifier kind
+ 'eu_vat'
servers:
- url: http://{defaultHost}
variables:
@@ -4724,6 +17875,9 @@ components:
carrier:
type: string
nullable: true
+ carrier_name:
+ type: string
+ nullable: true
service:
type: string
nullable: true
@@ -4752,9 +17906,6 @@ components:
type: string
owner_type:
type: string
- carrier_name:
- type: string
- nullable: true
cost:
type: string
display_cost:
@@ -4772,6 +17923,7 @@ components:
- source
- status
- carrier
+ - carrier_name
- service
- tracking_number
- currency
@@ -4783,7 +17935,6 @@ components:
- updated_at
- owner_id
- owner_type
- - carrier_name
- cost
- display_cost
- integration_id
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 49e1b2edf2..875d691dc8 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -40,15 +40,26 @@ info:
```
version: v3
paths:
- "/api/v3/store/customers/me/addresses":
- get:
- summary: List customer addresses
+ "/api/v3/store/auth/login":
+ post:
+ summary: Login
tags:
- - Customers
+ - Authentication
security:
- api_key: []
- bearer_auth: []
- description: Returns all addresses in the customer address book
+ description: |
+ Authenticates a customer and returns a JWT access token + refresh token.
+
+ The `provider` field selects the authentication method. When omitted it
+ defaults to `email`, the built-in email/password login.
+
+ To authenticate against a third-party identity provider (Auth0, Okta,
+ Firebase, a custom JWT issuer, SAML, etc.), send
+ `{ "provider": "<your_key>", ... }` with the fields that provider
+ requires. The endpoint returns the same JWT + refresh token regardless of
+ which provider authenticated the request. See
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
+ for the list of configured providers and their required fields.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -60,68 +71,103 @@ paths:
publishableKey: '<api-key>',
})
- const addresses = await client.customer.addresses.list(
- {},
- {
- token: '<token>',
- },
- )
+ const auth = await client.auth.login({
+ email: '[email protected]',
+ password: 'password123',
+ })
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
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
responses:
'200':
- description: addresses found
+ description: login successful
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImRlZmM5YWZhLTUzOTYtNDEwYy1hZDY4LTE4YTBiN2M5MmMwMyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.ha-8UOgpGEgYAVWjEqzhLZ9LPtI6uTlsDB3We7qbrdU
+ refresh_token: CxKP3VYWQzkXqrfxTmPLB446
+ user:
+ id: cust_UkLWZg9DAJ
+ first_name: Lenny
+ last_name: Kuhlman
+ phone:
+ accepts_email_marketing: false
+ full_name: Lenny Kuhlman
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses: []
+ default_billing_address:
+ default_shipping_address:
+ newsletter_subscriber:
+ customer_groups: []
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Address"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
+ "$ref": "#/components/schemas/AuthResponse"
'401':
- description: unauthorized
+ description: missing API key
content:
application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
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
+ example: password123
+ required:
+ - email
+ - password
+ - title: ProviderLogin
+ description: |
+ Provider-dispatched login. The `provider` key selects a configured
+ authentication provider; the remaining fields are forwarded to it.
+ Required fields depend on the provider — see
+ [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
+ type: object
+ properties:
+ provider:
+ type: string
+ example: auth0
+ description: Registered provider key (anything other than `email`).
+ not:
+ enum:
+ - email
+ required:
+ - provider
+ additionalProperties: true
+ "/api/v3/store/auth/refresh":
post:
- summary: Create an address
+ summary: Refresh token
tags:
- - Customers
+ - Authentication
security:
- api_key: []
- bearer_auth: []
- description: Adds a new address to the customer address book
+ description: Exchanges a refresh token for a new access JWT and rotated refresh
+ token. No Authorization header needed.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -133,43 +179,48 @@ paths:
publishableKey: '<api-key>',
})
- const address = await client.customer.addresses.create(
- {
- first_name: 'John',
- last_name: 'Doe',
- address1: '123 Main St',
- city: 'New York',
- postal_code: '10001',
- country_code: 'US',
- state_abbr: 'NY',
- phone: '+1 555 123 4567',
- },
- {
- token: '<token>',
- },
- )
+ const auth = await client.auth.refresh({
+ refresh_token: 'rt_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: address created
+ '200':
+ description: token refreshed
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFmMzM5OGY2LTczZDgtNDdjNi1hNDk4LTUxNDc3MGUxYTUyNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Zpvl-ISrctLW34O3zJFteOf3wMDNvlymVKsbkCIfeew
+ refresh_token: mWbQ77onTSsXQta8Z4SAVaTU
+ user:
+ id: cust_UkLWZg9DAJ
+ first_name: Tijuana
+ last_name: Konopelski
+ phone:
+ accepts_email_marketing: false
+ full_name: Tijuana Konopelski
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses: []
+ default_billing_address:
+ default_shipping_address:
+ newsletter_subscriber:
+ customer_groups: []
schema:
- "$ref": "#/components/schemas/Address"
- '422':
- description: validation error
+ "$ref": "#/components/schemas/AuthResponse"
+ '401':
+ description: missing or invalid refresh token
content:
application/json:
+ example:
+ error:
+ code: invalid_refresh_token
+ message: Invalid or expired refresh token
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -178,66 +229,21 @@ paths:
schema:
type: object
properties:
- first_name:
- type: string
- example: John
- last_name:
- type: string
- example: Doe
- address1:
- type: string
- example: 123 Main St
- address2:
- type: string
- example: Apt 4B
- city:
- type: string
- example: New York
- postal_code:
- type: string
- example: '10001'
- phone:
- type: string
- example: "+1 555 123 4567"
- company:
- type: string
- example: Acme Inc
- country_code:
- type: string
- example: US
- description: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")
- state_code:
- type: string
- example: NY
- description: ISO 3166-2 subdivision code without country prefix
- (e.g., "CA", "NY")
- state_name:
+ refresh_token:
type: string
- example: New York
- description: State name - for countries without predefined states
- is_default_billing:
- type: boolean
- example: true
- description: Set as default billing address
- is_default_shipping:
- type: boolean
- example: true
- description: Set as default shipping address
+ description: Refresh token from login response
required:
- - first_name
- - last_name
- - address1
- - city
- - postal_code
- - country_code
- "/api/v3/store/customers/me/addresses/{id}":
- get:
- summary: Get an address
+ - refresh_token
+ "/api/v3/store/auth/logout":
+ post:
+ summary: Logout
tags:
- - Customers
+ - Authentication
security:
- api_key: []
- bearer_auth: []
+ description: Revokes the submitted refresh token. The refresh token itself is
+ the credential — no Authorization header is required, so a client with an
+ expired access JWT can still log out.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -249,8 +255,8 @@ paths:
publishableKey: '<api-key>',
})
- const address = await client.customer.addresses.get('addr_abc123', {
- token: '<token>',
+ await client.auth.logout({
+ refresh_token: 'rt_xxx',
})
parameters:
- name: x-spree-api-key
@@ -258,43 +264,27 @@ paths:
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
responses:
- '200':
- description: address found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Address"
- '404':
- description: address not found
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update an address
+ '204':
+ description: logout without refresh token (no-op)
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ refresh_token:
+ type: string
+ description: Refresh token to revoke
+ "/api/v3/store/password_resets":
+ post:
+ summary: Request a password reset
tags:
- - Customers
+ - Authentication
security:
- api_key: []
- bearer_auth: []
+ description: Sends a password reset email if an account exists for the given
+ email address. Always returns 202 Accepted to prevent email enumeration.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -306,71 +296,67 @@ paths:
publishableKey: '<api-key>',
})
- const address = await client.customer.addresses.update(
- 'addr_abc123',
- {
- city: 'Los Angeles',
- },
- {
- token: '<token>',
- },
- )
+ await client.passwordResets.create({
+ email: '[email protected]',
+ redirect_url: 'https://myshop.com/reset-password',
+ })
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: address updated
+ '202':
+ description: email not found (same response to prevent enumeration)
content:
application/json:
+ example:
+ message: If an account exists for that email, password reset instructions
+ have been sent.
schema:
- "$ref": "#/components/schemas/Address"
+ type: object
+ properties:
+ message:
+ type: string
+ '401':
+ description: missing API key
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- first_name:
- type: string
- example: John
- last_name:
- type: string
- example: Doe
- address1:
+ email:
type: string
- example: 456 Oak Ave
- city:
+ format: email
+ description: Email address of the account to reset
+ redirect_url:
type: string
- example: Los Angeles
- is_default_billing:
- type: boolean
- example: true
- description: Set as default billing address
- is_default_shipping:
- type: boolean
- example: true
- description: Set as default shipping address
- delete:
- summary: Delete an address
+ format: uri
+ example: https://myshop.com/reset-password
+ description: URL to redirect the user to after clicking the reset
+ link. Validated against the store's allowed origins.
+ required:
+ - email
+ "/api/v3/store/password_resets/{token}":
+ patch:
+ summary: Reset password with token
tags:
- - Customers
+ - Authentication
security:
- api_key: []
- bearer_auth: []
+ description: Resets the password using a token received via email. Returns a
+ JWT token on success (auto-login).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -382,8 +368,9 @@ paths:
publishableKey: '<api-key>',
})
- await client.customer.addresses.delete('addr_abc123', {
- token: '<token>',
+ const auth = await client.passwordResets.update('reset-token-from-email', {
+ password: 'newsecurepassword',
+ password_confirmation: 'newsecurepassword',
})
parameters:
- name: x-spree-api-key
@@ -391,45 +378,84 @@ paths:
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- - name: id
+ - name: token
in: path
required: true
+ description: Password reset token from the email
schema:
type: string
responses:
- '204':
- description: address deleted
- '404':
- description: address not found
+ '200':
+ description: password reset successful
+ content:
+ application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjdlOGI2Njc5LTBjNzYtNDQ1Mi1hMWMyLWJhY2U0MWNhN2IyMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.grC4diUECUp8b3p6jJBHAZp_MyiSUQwA4rdQLel_zuM
+ refresh_token: JNJKeT5cELhdSfb2tWHj3ctp
+ user:
+ id: cust_UkLWZg9DAJ
+ first_name: Lucas
+ last_name: Stiedemann
+ phone:
+ accepts_email_marketing: false
+ full_name: Lucas Stiedemann
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses: []
+ default_billing_address:
+ default_shipping_address:
+ newsletter_subscriber:
+ customer_groups: []
+ schema:
+ "$ref": "#/components/schemas/AuthResponse"
+ '422':
+ description: password confirmation mismatch
content:
application/json:
+ example:
+ error:
+ code: validation_error
+ message: Password confirmation doesn't match Password
+ details:
+ password_confirmation:
+ - doesn't match Password
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/auth/login":
- post:
- summary: Login
+ '401':
+ description: missing API key
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ password:
+ type: string
+ minLength: 6
+ example: newsecurepassword
+ password_confirmation:
+ type: string
+ example: newsecurepassword
+ required:
+ - password
+ - password_confirmation
+ "/api/v3/store/categories":
+ get:
+ summary: List categories
tags:
- - Authentication
+ - Product Catalog
security:
- api_key: []
- description: |
- Authenticates a customer and returns a JWT access token + refresh token.
-
- The `provider` field selects the authentication method. When omitted it
- defaults to `email`, the built-in email/password login.
-
- To authenticate against a third-party identity provider (Auth0, Okta,
- Firebase, a custom JWT issuer, SAML, etc.), send
- `{ "provider": "<your_key>", ... }` with the fields that provider
- requires. The endpoint returns the same JWT + refresh token regardless of
- which provider authenticated the request. See
- [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)
- for the list of configured providers and their required fields.
+ description: Returns a paginated list of categories for the current store
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -441,9 +467,9 @@ paths:
publishableKey: '<api-key>',
})
- const auth = await client.auth.login({
- email: '[email protected]',
- password: 'password123',
+ const categories = await client.categories.list({
+ page: 1,
+ limit: 25,
})
parameters:
- name: x-spree-api-key
@@ -451,125 +477,124 @@ paths:
required: true
schema:
type: string
- responses:
- '200':
- description: login successful
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/AuthResponse"
- '401':
- description: missing API key
- 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
- example: password123
- required:
- - email
- - password
- - title: ProviderLogin
- description: |
- Provider-dispatched login. The `provider` key selects a configured
- authentication provider; the remaining fields are forwarded to it.
- Required fields depend on the provider — see
- [Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).
- type: object
- properties:
- provider:
- type: string
- example: auth0
- description: Registered provider key (anything other than `email`).
- not:
- enum:
- - email
- required:
- - provider
- additionalProperties: true
- "/api/v3/store/auth/refresh":
- post:
- summary: Refresh token
- tags:
- - Authentication
- security:
- - api_key: []
- description: Exchanges a refresh token for a new access JWT and rotated refresh
- token. No Authorization header needed.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const auth = await client.auth.refresh({
- refresh_token: 'rt_xxx',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ description: Filter by name
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: token refreshed
+ description: categories found
content:
application/json:
+ example:
+ data:
+ - id: ctg_UkLWZg9DAJ
+ name: Catalog
+ permalink: catalog
+ position: 0
+ depth: 0
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ parent_id:
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: true
+ is_child: false
+ is_leaf: false
+ - id: ctg_gbHJdmfrXB
+ name: category_3
+ permalink: catalog/category-3
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: false
+ - id: ctg_EfhxLZ9ck8
+ name: category_4
+ permalink: catalog/category-3/category-4
+ position: 0
+ depth: 2
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 0
+ parent_id: ctg_gbHJdmfrXB
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: true
+ meta:
+ page: 1
+ limit: 25
+ count: 3
+ pages: 1
+ from: 1
+ to: 3
+ in: 3
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/AuthResponse"
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Category"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
'401':
- description: missing or invalid refresh token
+ description: unauthorized
content:
application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- refresh_token:
- type: string
- description: Refresh token from login response
- required:
- - refresh_token
- "/api/v3/store/auth/logout":
- post:
- summary: Logout
+ "/api/v3/store/categories/{id}":
+ get:
+ summary: Get a category
tags:
- - Authentication
+ - Product Catalog
security:
- api_key: []
- description: Revokes the submitted refresh token. The refresh token itself is
- the credential — no Authorization header is required, so a client with an
- expired access JWT can still log out.
+ description: Returns a single category by permalink or prefix ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -581,8 +606,8 @@ paths:
publishableKey: '<api-key>',
})
- await client.auth.logout({
- refresh_token: 'rt_xxx',
+ const category = await client.categories.get('categories/clothing/shirts', {
+ expand: ['children'],
})
parameters:
- name: x-spree-api-key
@@ -590,370 +615,329 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ description: Category permalink (e.g., clothing/shirts) or prefix ID (e.g.,
+ ctg_abc123)
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Expand associations (children, parent, ancestors, custom_fields)
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
+ schema:
+ type: string
responses:
- '204':
- description: logout without refresh token (no-op)
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- refresh_token:
- type: string
- description: Refresh token to revoke
- "/api/v3/store/carts":
+ '200':
+ description: category found by prefix ID
+ content:
+ application/json:
+ example:
+ id: ctg_gbHJdmfrXB
+ name: category_12
+ permalink: catalog/category-12
+ position: 0
+ depth: 1
+ meta_title:
+ meta_description:
+ meta_keywords:
+ children_count: 1
+ parent_id: ctg_UkLWZg9DAJ
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ is_root: false
+ is_child: true
+ is_leaf: false
+ schema:
+ "$ref": "#/components/schemas/Category"
+ '404':
+ description: category from other store not accessible
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Category not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/collections":
get:
- summary: List active carts
+ summary: List collections
tags:
- - Carts
+ - Product Catalog
security:
- api_key: []
- bearer_auth: []
- description: Returns all active (incomplete) carts for the authenticated user.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const carts = await client.carts.list({
- token: '<token>',
- })
+ description: Returns a paginated list of collections for the current store.
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 (default: 1)'
schema:
type: integer
- name: limit
in: query
required: false
- description: 'Number of results per page (default: 25, max: 100)'
schema:
type: integer
- - name: sort
- in: query
- required: false
- description: 'Sort order. Prefix with - for descending. Values: created_at,
- -created_at, updated_at, -updated_at'
- schema:
- type: string
- - name: q[created_at_gt]
+ - name: q[name_cont]
in: query
required: false
- description: Filter by created after date (ISO 8601)
+ description: Filter by name
schema:
type: string
- - name: q[updated_at_gt]
+ - name: fields
in: query
required: false
- description: Filter by updated after date (ISO 8601)
+ description: Comma-separated list of fields to include (e.g., name,permalink).
+ id is always included.
schema:
type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (items, fulfillments,
- payments, discounts, billing_address, shipping_address, gift_card, payment_methods).
- Use "none" to skip associations.
+ responses:
+ '200':
+ 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: 1
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_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/Collection"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/collections/{id}":
+ get:
+ summary: Get a collection
+ tags:
+ - Product Catalog
+ security:
+ - api_key: []
+ description: Returns a single collection by permalink or prefix ID.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Collection permalink (e.g., summer-sale) or prefix ID (e.g.,
+ coll_abc123)
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Expand associations (custom_fields)
schema:
type: string
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
- id is always included.
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
- description: carts listed
+ description: collection found by prefix ID
+ 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: 1
+ description: ''
+ description_html: ''
+ image_url:
+ square_image_url:
+ schema:
+ "$ref": "#/components/schemas/Collection"
+ '404':
+ description: collection from other store not accessible
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Collection not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/collections/{collection_id}/products":
+ get:
+ summary: List collection products
+ tags:
+ - Product Catalog
+ security:
+ - api_key: []
+ description: Products in the collection. Defaults to the collection's own sort
+ order and accepts the same filters, sort, and pagination as the products endpoint.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: collection_id
+ in: path
+ required: true
+ description: Collection permalink or prefix ID
+ schema:
+ type: string
+ - name: sort
+ in: query
+ required: false
+ description: Sort order (e.g., price, -price). Defaults to the collection's
+ sort_order.
+ schema:
+ type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: products found
content:
application/json:
example:
data:
- - id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: ckMf2iQ6r5adLceTPfKVH9BP
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '10.0'
- display_amount_due: "$10.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: ship_address_required
- step: address
- field: ship_address
- message: Shipping address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 68715
- slug: product-68715
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
+ - id: prod_UkLWZg9DAJ
+ name: Product 1866979
+ slug: product-1866979
+ 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: Accusantium ex dicta error nemo ipsa vel eaque porro.
+ Laborum ipsam molestias iure aspernatur quos dolorem. Quia libero
+ odio nesciunt debitis eaque.
+ description_html: Accusantium ex dicta error nemo ipsa vel eaque
+ porro. Laborum ipsam molestias iure aspernatur quos dolorem. Quia
+ libero odio nesciunt debitis eaque.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
+ compare_at_amount_in_cents:
currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- - id: cart_gbHJdmfrXB
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_gbHJdmfrXB
- token: pvLw1ZWLLQNxh1uvSPUCdSmt
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '10.0'
- display_amount_due: "$10.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: ship_address_required
- step: address
- field: ship_address
- message: Shipping address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 692171
- slug: product-692171
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
meta:
page: 1
limit: 25
- count: 2
+ count: 1
pages: 1
from: 1
- to: 2
- in: 2
+ 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 new cart
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ "/api/v3/store/products":
+ get:
+ summary: List products
tags:
- - Carts
+ - Product Catalog
security:
- api_key: []
- description: |
- Creates a new shopping cart. Can be created by guests or authenticated customers.
- Returns a `token` that must be used for guest access to the cart.
+ description: Returns a paginated list of active products for the current store
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -965,77 +949,220 @@ paths:
publishableKey: '<api-key>',
})
- // Create an empty cart
- const cart = await client.carts.create()
-
- // Create a cart with items
- const cartWithItems = await client.carts.create({
- items: [{ variant_id: 'variant_abc123', quantity: 2 }],
+ const products = await client.products.list({
+ page: 1,
+ limit: 25,
+ sort: 'price',
+ name_cont: 'shirt',
+ price_gte: 20,
+ price_lte: 100,
+ with_option_value_ids: ['optval_abc', 'optval_def'],
+ expand: ['variants', 'media'],
})
parameters:
- name: x-spree-api-key
in: header
required: true
+ description: Publishable API key
schema:
type: string
- - name: Authorization
- in: header
+ - name: page
+ in: query
required: false
- description: Bearer JWT token (optional - for authenticated customers)
+ description: 'Page number (default: 1)'
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: 'Number of items per page (default: 25, max: 100)'
+ schema:
+ type: integer
+ - name: sort
+ in: query
+ required: false
+ description: 'Sort order. Prefix with - for descending. Values: price, -price,
+ best_selling, name, -name, -available_on, available_on'
schema:
type: string
- - name: Idempotency-Key
- in: header
+ - name: q[name_cont]
+ in: query
required: false
- description: Unique key for request idempotency.
+ description: Filter by name containing string
+ schema:
+ type: string
+ - name: q[in_category]
+ in: query
+ required: false
+ description: Filter by category prefixed ID (includes descendants)
+ schema:
+ type: string
+ - name: q[in_categories][]
+ in: query
+ required: false
+ description: Filter by multiple category prefixed IDs (OR logic, includes
+ descendants)
+ schema:
+ type: string
+ - name: q[price_gte]
+ in: query
+ required: false
+ description: Filter by minimum price
+ schema:
+ type: number
+ - name: q[price_lte]
+ in: query
+ required: false
+ description: Filter by maximum price
+ schema:
+ type: number
+ - name: q[with_option_value_ids][]
+ in: query
+ required: false
+ description: Filter by option value prefix IDs (e.g., optval_abc). Pass multiple
+ values for OR logic.
+ schema:
+ type: string
+ - name: q[in_stock]
+ in: query
+ required: false
+ description: Filter to only in-stock products
+ schema:
+ type: boolean
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (variants, media, categories,
+ option_types, seller, seller.policies)
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
- '201':
- description: cart created
+ '200':
+ description: products found
content:
application/json:
+ example:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 2329085
+ slug: product-2329085
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 2
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: A comfortable cotton t-shirt.
+ description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ - id: prod_gbHJdmfrXB
+ name: Product 2338209
+ slug: product-2338209
+ 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: Quasi nostrum error iste autem recusandae consequuntur
+ consectetur. Dolorem ea officia rerum a. Asperiores et occaecati
+ laudantium deserunt modi reiciendis rem. Iste soluta tempora odit
+ voluptate cupiditate. Architecto nostrum aliquid est odit minima
+ repudiandae. Doloribus quos est in illum. Occaecati vero soluta
+ asperiores aliquam odio accusamus incidunt. Officia magnam fugiat
+ sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati
+ rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.
+ description_html: |-
+ Quasi nostrum error iste autem recusandae consequuntur consectetur. Dolorem ea officia rerum a. Asperiores et occaecati laudantium deserunt modi reiciendis rem. Iste soluta tempora odit voluptate cupiditate. Architecto nostrum aliquid est odit minima repudiandae.
+ Doloribus quos est in illum. Occaecati vero soluta asperiores aliquam odio accusamus incidunt. Officia magnam fugiat sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.
+ default_variant_id: variant_EfhxLZ9ck8
+ buy_box_variant_id: variant_EfhxLZ9ck8
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_EfhxLZ9ck8
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Cart"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- metadata:
- type: object
- description: Write-only key-value metadata (Stripe-style).
- items:
- type: array
- description: Items to add to the cart on creation
- items:
- type: object
- properties:
- variant_id:
- type: string
- example: variant_abc123
- description: Prefixed variant ID
- quantity:
- type: integer
- example: 2
- description: Quantity (defaults to 1)
- metadata:
- type: object
- additionalProperties: true
- required:
- - variant_id
- "/api/v3/store/carts/{id}":
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ '401':
+ description: unauthorized - invalid or missing API key
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/products/{id}":
get:
- summary: Get a cart
+ summary: Get a product
tags:
- - Carts
+ - Product Catalog
security:
- api_key: []
- bearer_auth: []
- description: |
- Returns a shopping cart by prefixed ID.
- Authorize via x-spree-token header (guest) or JWT Bearer token (authenticated user).
+ description: Returns a single product by slug or prefix ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1047,68 +1174,108 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.get('cart_abc123', {
- token: '<token>',
+ const product = await client.products.get('spree-tote', {
+ expand: ['variants', 'media'],
})
parameters:
- name: x-spree-api-key
in: header
required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: false
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
+ description: Publishable API key
schema:
type: string
- name: id
in: path
required: true
- description: Cart prefixed ID (e.g., cart_abc123)
+ description: Product slug (e.g., spree-tote) or prefix ID (e.g., product_abc123)
schema:
type: string
- name: expand
in: query
required: false
- description: Comma-separated associations to expand (items, fulfillments,
- payments, discounts, billing_address, shipping_address, gift_card, payment_methods).
- Use "none" to skip associations.
+ description: Comma-separated associations to expand (variants, media, categories,
+ option_types, prior_price, seller, seller.policies). On a marketplace, `seller`
+ embeds the seller public profile and `seller.policies` adds their published
+ legal documents; `seller_id` is present without either.
schema:
type: string
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
id is always included.
schema:
type: string
responses:
'200':
- description: cart with out-of-stock item removed (warnings returned)
+ description: product without prior_price expanded does not include field
content:
application/json:
+ example:
+ id: prod_UkLWZg9DAJ
+ name: Product 2606885
+ slug: product-2606885
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 2
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: A comfortable cotton t-shirt.
+ description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ prior_price:
+ id: _AXs1igzRC6
+ amount: '9.99'
+ amount_in_cents: 999
+ currency: USD
+ display_amount: "$9.99"
+ recorded_at: '2025-12-31T12:00:00Z'
schema:
- "$ref": "#/components/schemas/Cart"
+ "$ref": "#/components/schemas/Product"
'404':
- description: cart not found
+ description: draft product not visible
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Product not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a cart
+ "/api/v3/store/products/filters":
+ get:
+ summary: Get product filters
tags:
- - Carts
+ - Product Catalog
security:
- api_key: []
- bearer_auth: []
- description: Updates cart info (email, addresses, customer note). When addresses
- change, the order state is reverted to address to ensure shipments are recalculated.
+ description: |
+ Returns available filters for products with their options and counts.
+ Use this endpoint to build filter UIs for product listing pages.
+
+ The filters are context-aware - when a category_id is provided, only filters
+ relevant to products in that category are returned.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1120,136 +1287,136 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.update(
- 'cart_abc123',
- {
- email: '[email protected]',
- shipping_address: {
- first_name: 'John',
- last_name: 'Doe',
- address1: '123 Main St',
- city: 'New York',
- postal_code: '10001',
- country_code: 'US',
- state_abbr: 'NY',
- },
- },
- {
- token: '<token>',
- },
- )
+ const filters = await client.products.filters({
+ category_id: 'ctg_abc123',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
+ description: Publishable API key
schema:
type: string
- - name: Authorization
- in: header
- required: false
- schema:
- type: string
- - name: x-spree-token
- in: header
+ - name: category_id
+ in: query
required: false
+ description: Scope filters to products in this category (prefix ID)
schema:
type: string
- - name: Idempotency-Key
- in: header
+ - name: q[name_cont]
+ in: query
required: false
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Cart prefixed ID
+ description: Filter by name containing string
schema:
type: string
responses:
'200':
- description: cart updated
+ description: filters scoped to category
content:
application/json:
+ example:
+ id:
+ default_sort: manual
+ total_count: 2
+ filters:
+ - id: price
+ type: price_range
+ min: 19.99
+ max: 19.99
+ currency: USD
+ - id: availability
+ type: availability
+ options:
+ - id: in_stock
+ count: 2
+ - id: out_of_stock
+ count: 0
+ - id: opt_UkLWZg9DAJ
+ type: option
+ name: size
+ label: Size
+ kind: dropdown
+ options:
+ - id: optval_UkLWZg9DAJ
+ name: small
+ label: S
+ position: 1
+ color_code:
+ image_url:
+ count: 1
+ - id: categories
+ type: category
+ options:
+ - id: ctg_gbHJdmfrXB
+ name: Shirts
+ permalink: category-34/shirts
+ count: 2
+ sort_options:
+ - id: manual
+ label:
+ - id: best_selling
+ label:
+ - id: price
+ label:
+ - id: "-price"
+ label:
+ - id: "-available_on"
+ label:
+ - id: available_on
+ label:
+ - id: name
+ label:
+ - id: "-name"
+ label:
schema:
- "$ref": "#/components/schemas/Cart"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- customer_note:
- type: string
- example: Leave at door
- metadata:
- type: object
- additionalProperties: true
- shipping_address_id:
- type: string
- description: Existing address ID to use as shipping address
- example: addr_abc123
- billing_address_id:
- type: string
- description: Existing address ID to use as billing address
- example: addr_def456
- billing_address:
- type: object
- properties:
- first_name:
- type: string
- last_name:
- type: string
- address1:
- type: string
- address2:
- type: string
- city:
- type: string
- postal_code:
- type: string
- phone:
- type: string
- company:
- type: string
- country_code:
- type: string
- state_code:
- type: string
- shipping_address:
- type: object
- properties:
- first_name:
- type: string
- last_name:
- type: string
- address1:
- type: string
- address2:
- type: string
- city:
- type: string
- postal_code:
- type: string
- phone:
- type: string
- company:
- type: string
- country_code:
- type: string
- state_code:
- type: string
- delete:
- summary: Delete a cart
+ type: object
+ properties:
+ filters:
+ type: array
+ description: Available filters (price_range, availability, option,
+ category)
+ items:
+ type: object
+ sort_options:
+ type: array
+ description: Available sort options
+ items:
+ type: object
+ properties:
+ id:
+ type: string
+ required:
+ - id
+ default_sort:
+ type: string
+ description: Default sort option ID
+ total_count:
+ type: integer
+ description: Total products matching current filters
+ required:
+ - filters
+ - sort_options
+ - default_sort
+ - total_count
+ '401':
+ description: unauthorized - invalid or missing API key
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/carts":
+ get:
+ summary: List active carts
tags:
- Carts
security:
- api_key: []
bearer_auth: []
- description: Deletes/abandons the cart.
+ description: Returns all active (incomplete) carts for the authenticated user.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1261,7 +1428,7 @@ paths:
publishableKey: '<api-key>',
})
- await client.carts.delete('cart_abc123', {
+ const carts = await client.carts.list({
token: '<token>',
})
parameters:
@@ -1272,35 +1439,327 @@ paths:
type: string
- name: Authorization
in: header
+ required: true
+ schema:
+ type: string
+ - name: page
+ in: query
+ required: false
+ description: 'Page number (default: 1)'
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: 'Number of results per page (default: 25, max: 100)'
+ schema:
+ type: integer
+ - name: sort
+ in: query
required: false
+ description: 'Sort order. Prefix with - for descending. Values: created_at,
+ -created_at, updated_at, -updated_at'
schema:
type: string
- - name: x-spree-token
- in: header
+ - name: q[created_at_gt]
+ in: query
required: false
+ description: Filter by created after date (ISO 8601)
schema:
type: string
- - name: id
- in: path
- required: true
- description: Cart prefixed ID
+ - name: q[updated_at_gt]
+ in: query
+ required: false
+ description: Filter by updated after date (ISO 8601)
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (items, fulfillments,
+ payments, discounts, billing_address, shipping_address, gift_card, payment_methods).
+ Use "none" to skip associations.
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
+ id is always included.
schema:
type: string
responses:
- '204':
- description: cart deleted
- "/api/v3/store/carts/{id}/associate":
- patch:
- summary: Associate guest cart with authenticated user
- tags:
- - Carts
- security:
- - api_key: []
- bearer_auth: []
- description: |
- Associates a guest cart with the currently authenticated user.
- Requires JWT authentication and possession of the cart's token
- (x-spree-token) — the token authorizes claiming the cart.
+ '200':
+ description: carts listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: ckMf2iQ6r5adLceTPfKVH9BP
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: ship_address_required
+ step: address
+ field: ship_address
+ message: Shipping address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 160715
+ slug: product-160715
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ - id: cart_gbHJdmfrXB
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_gbHJdmfrXB
+ token: pvLw1ZWLLQNxh1uvSPUCdSmt
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: ship_address_required
+ step: address
+ field: ship_address
+ message: Shipping address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_gbHJdmfrXB
+ variant_id: variant_gbHJdmfrXB
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 1612171
+ slug: product-1612171
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ 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 new cart
+ tags:
+ - Carts
+ security:
+ - api_key: []
+ description: |
+ Creates a new shopping cart. Can be created by guests or authenticated customers.
+ Returns a `token` that must be used for guest access to the cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1312,8 +1771,12 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.associate('cart_abc123', {
- token: '<token>',
+ // Create an empty cart
+ const cart = await client.carts.create()
+
+ // Create a cart with items
+ const cartWithItems = await client.carts.create({
+ items: [{ variant_id: 'variant_abc123', quantity: 2 }],
})
parameters:
- name: x-spree-api-key
@@ -1323,50 +1786,142 @@ paths:
type: string
- name: Authorization
in: header
- required: true
+ required: false
+ description: Bearer JWT token (optional - for authenticated customers)
schema:
type: string
- - name: x-spree-token
+ - name: Idempotency-Key
in: header
- required: true
- description: Cart token
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Cart prefixed ID
- schema:
- type: string
- responses:
- '200':
- description: cart associated successfully
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Cart"
- '401':
- description: unauthorized - JWT required
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '403':
- description: forbidden - cart token missing or does not match
+ required: false
+ description: Unique key for request idempotency.
+ schema:
+ type: string
+ responses:
+ '201':
+ description: cart created
content:
application/json:
+ example:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: jBrNbC8FSNyavqebdqu7e3uL
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ warnings: []
+ coupon_code:
+ item_total: '0.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: line_items_required
+ step: cart
+ field: line_items
+ message: Add at least one item to your cart
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{id}/complete":
- post:
- summary: Complete cart
+ "$ref": "#/components/schemas/Cart"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ metadata:
+ type: object
+ description: Write-only key-value metadata (Stripe-style).
+ items:
+ type: array
+ description: Items to add to the cart on creation
+ items:
+ type: object
+ properties:
+ variant_id:
+ type: string
+ example: variant_abc123
+ description: Prefixed variant ID
+ quantity:
+ type: integer
+ example: 2
+ description: Quantity (defaults to 1)
+ metadata:
+ type: object
+ additionalProperties: true
+ required:
+ - variant_id
+ "/api/v3/store/carts/{id}":
+ get:
+ summary: Get a cart
tags:
- Carts
security:
- api_key: []
bearer_auth: []
- description: Completes the cart and finalizes the purchase. Returns an Order
- (not Cart).
+ description: |
+ Returns a shopping cart by prefixed ID.
+ Authorize via x-spree-token header (guest) or JWT Bearer token (authenticated user).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1378,7 +1933,7 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.carts.complete('cart_abc123', {
+ const cart = await client.carts.get('cart_abc123', {
token: '<token>',
})
parameters:
@@ -1400,30 +1955,134 @@ paths:
- name: id
in: path
required: true
- description: Cart prefixed ID
+ description: Cart prefixed ID (e.g., cart_abc123)
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (items, fulfillments,
+ payments, discounts, billing_address, shipping_address, gift_card, payment_methods).
+ Use "none" to skip associations.
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
+ id is always included.
schema:
type: string
responses:
'200':
- description: cart completed
+ description: cart with out-of-stock item removed (warnings returned)
content:
application/json:
+ example:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: HnnryvFFwjfx9P6ykByF4Gg2
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ warnings:
+ - code: line_item_removed
+ message: Product 165307 was removed because it was sold out
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ coupon_code:
+ item_total: '0.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: line_items_required
+ step: cart
+ field: line_items
+ message: Add at least one item to your cart
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- "$ref": "#/components/schemas/Order"
- '422':
- description: cannot complete
+ "$ref": "#/components/schemas/Cart"
+ '404':
+ description: cart not found
content:
application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Cart not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/categories":
- get:
- summary: List categories
+ patch:
+ summary: Update a cart
tags:
- - Product Catalog
+ - Carts
security:
- api_key: []
- description: Returns a paginated list of categories for the current store
+ bearer_auth: []
+ description: Updates cart info (email, addresses, customer note). When addresses
+ change, the order state is reverted to address to ensure shipments are recalculated.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1435,67 +2094,251 @@ paths:
publishableKey: '<api-key>',
})
- const categories = await client.categories.list({
- page: 1,
- limit: 25,
- })
+ const cart = await client.carts.update(
+ 'cart_abc123',
+ {
+ email: '[email protected]',
+ shipping_address: {
+ first_name: 'John',
+ last_name: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ postal_code: '10001',
+ country_code: 'US',
+ state_abbr: 'NY',
+ },
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: page
- in: query
+ - name: Authorization
+ in: header
required: false
schema:
- type: integer
- - name: limit
- in: query
+ type: string
+ - name: x-spree-token
+ in: header
required: false
schema:
- type: integer
- - name: q[name_cont]
- in: query
+ type: string
+ - name: Idempotency-Key
+ in: header
required: false
- description: Filter by name
schema:
type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ - name: id
+ in: path
+ required: true
+ description: Cart prefixed ID
schema:
type: string
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"
- '401':
- description: unauthorized
+ description: cart updated
content:
application/json:
+ example:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: PMVmxRAiLqMivU5QgJqfpQMD
+ email:
+ customer_note: Leave at door
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 1663263
+ slug: product-1663263
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/categories/{id}":
- get:
- summary: Get a category
+ "$ref": "#/components/schemas/Cart"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ customer_note:
+ type: string
+ example: Leave at door
+ metadata:
+ type: object
+ additionalProperties: true
+ shipping_address_id:
+ type: string
+ description: Existing address ID to use as shipping address
+ example: addr_abc123
+ billing_address_id:
+ type: string
+ description: Existing address ID to use as billing address
+ example: addr_def456
+ billing_address:
+ type: object
+ properties:
+ first_name:
+ type: string
+ last_name:
+ type: string
+ address1:
+ type: string
+ address2:
+ type: string
+ city:
+ type: string
+ postal_code:
+ type: string
+ phone:
+ type: string
+ company:
+ type: string
+ country_code:
+ type: string
+ state_code:
+ type: string
+ shipping_address:
+ type: object
+ properties:
+ first_name:
+ type: string
+ last_name:
+ type: string
+ address1:
+ type: string
+ address2:
+ type: string
+ city:
+ type: string
+ postal_code:
+ type: string
+ phone:
+ type: string
+ company:
+ type: string
+ country_code:
+ type: string
+ state_code:
+ type: string
+ delete:
+ summary: Delete a cart
tags:
- - Product Catalog
+ - Carts
security:
- api_key: []
- description: Returns a single category by permalink or prefix ID
+ bearer_auth: []
+ description: Deletes/abandons the cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1507,8 +2350,8 @@ paths:
publishableKey: '<api-key>',
})
- const category = await client.categories.get('categories/clothing/shirts', {
- expand: ['children'],
+ await client.carts.delete('cart_abc123', {
+ token: '<token>',
})
parameters:
- name: x-spree-api-key
@@ -1516,56 +2359,37 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- description: Category permalink (e.g., clothing/shirts) or prefix ID (e.g.,
- ctg_abc123)
- schema:
- type: string
- - name: expand
- in: query
+ - name: Authorization
+ in: header
required: false
- description: Expand associations (children, parent, ancestors, custom_fields)
schema:
type: string
- - name: fields
- in: query
+ - name: x-spree-token
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Cart prefixed ID
schema:
type: string
responses:
- '200':
- description: category found by prefix ID
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Category"
- '404':
- description: category from other store not accessible
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: unauthorized
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/channel":
- get:
- summary: Get the current channel
+ '204':
+ description: cart deleted
+ "/api/v3/store/carts/{id}/associate":
+ patch:
+ summary: Associate guest cart with authenticated user
tags:
- - Channel
+ - Carts
security:
- api_key: []
- description: Returns the channel this request resolved to (key binding → X-Spree-Channel
- header → store default), including the resolved storefront access posture.
- Reachable before authentication so gated storefronts can render a sign-in
- wall.
+ bearer_auth: []
+ description: |
+ Associates a guest cart with the currently authenticated user.
+ Requires JWT authentication and possession of the cart's token
+ (x-spree-token) — the token authorizes claiming the cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1577,205 +2401,731 @@ paths:
publishableKey: '<api-key>',
})
- const channel = await client.channel.get()
-
- if (channel.storefront_access === 'login_required') {
- // render a sign-in wall before any catalog UI
- }
+ const cart = await client.carts.associate('cart_abc123', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: X-Spree-Channel
+ - name: Authorization
in: header
- required: false
- description: Channel code or prefixed ID to resolve. When the API key is channel-bound,
- a value naming a different channel is rejected with 422 channel_mismatch;
- a value matching the bound channel is accepted.
+ required: true
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: true
+ description: Cart token
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Cart prefixed ID
schema:
type: string
responses:
'200':
- description: channel found
+ description: cart associated successfully
content:
application/json:
+ example:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: rrGvkDXx3KcQVwLVk8XiVCVk
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: delivery
+ completed_steps:
+ - address
+ requirements:
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: false
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 1688992
+ slug: product-1688992
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 180 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: true
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ shipping_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 179 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: true
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- "$ref": "#/components/schemas/Channel"
+ "$ref": "#/components/schemas/Cart"
'401':
- description: unauthorized
+ description: unauthorized - JWT required
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '403':
+ description: forbidden - cart token missing or does not match
content:
application/json:
+ example:
+ error:
+ code: access_denied
+ message: You are not authorized to access this page.
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/collections":
- get:
- summary: List collections
+ "/api/v3/store/carts/{id}/complete":
+ post:
+ summary: Complete cart
tags:
- - Product Catalog
+ - Carts
security:
- api_key: []
- description: Returns a paginated list of collections for the current store.
+ bearer_auth: []
+ description: Completes the cart and finalizes the purchase. Returns an Order
+ (not Cart).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const order = await client.carts.complete('cart_abc123', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
+ - name: Authorization
+ in: header
required: false
schema:
- type: integer
- - name: q[name_cont]
- in: query
+ type: string
+ - name: x-spree-token
+ in: header
required: false
- description: Filter by name
schema:
type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,permalink).
- id is always included.
+ - name: id
+ in: path
+ required: true
+ description: Cart prefixed ID
schema:
type: string
responses:
'200':
- description: collections found
+ description: cart completed
content:
application/json:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Collection"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
+ example:
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ cart_id: cart_UkLWZg9DAJ
+ 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: backorder
+ payment_status: paid
+ completed_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '20.0'
+ display_total: "$20.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '20.0'
+ display_amount_due: "$20.00"
+ delivery_total: '10.0'
+ display_delivery_total: "$10.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ discounts: []
+ fees: []
+ items:
+ - id: li_gbHJdmfrXB
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 1714794
+ slug: product-1714794
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_gbHJdmfrXB
+ number: R1001-F1
+ tracking:
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_gbHJdmfrXB
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries: []
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ name: Deangelo Prosacco
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ additional_tax_total: '0.0'
+ included_tax_total: '0.0'
+ tax_total: '0.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ display_additional_tax_total: "$0.00"
+ display_included_tax_total: "$0.00"
+ display_tax_total: "$0.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: BGS-518d4ef9738e
+ number: R1001-P1
+ status: completed
+ amount: '20.0'
+ display_amount: "$20.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:
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Check
+ description:
+ type: check
+ session_required: false
+ source_required: false
+ billing_address:
+ id: addr_uw2YK1rnl0
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 186 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
+ shipping_address:
+ id: addr_OIJLhNcSbf
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 185 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
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ schema:
+ "$ref": "#/components/schemas/Order"
+ '422':
+ description: cannot complete
content:
application/json:
+ example:
+ error:
+ code: cart_cannot_complete
+ message: '{code: "validation_failed", errors: [{code: "email_required",
+ step: "address", field: "email", message: "Email address is required"},
+ {code: "delivery_method_required", step: "delivery", field: "delivery_method",
+ message: "Select a delivery method for all fulfillments"}, {code:
+ "payment_required", step: "payment", field: "payment", message:
+ "Add a payment method"}]}'
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/collections/{id}":
- get:
- summary: Get a collection
+ "/api/v3/store/carts/{cart_id}/discount_codes":
+ post:
+ summary: Apply discount code
tags:
- - Product Catalog
+ - Carts
security:
- api_key: []
- description: Returns a single collection by permalink or prefix ID.
+ bearer_auth: []
+ description: |
+ Applies a promotion discount code to the cart. The code is matched case-insensitively.
+
+ For gift cards, use the dedicated `POST /carts/{cart_id}/gift_cards` endpoint instead.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const cart = await client.carts.discountCodes.apply('cart_abc123', 'SAVE10', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- description: Collection permalink (e.g., summer-sale) or prefix ID (e.g.,
- coll_abc123)
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Expand associations (custom_fields)
- schema:
- type: string
- - name: fields
- in: query
+ - name: Authorization
+ in: header
required: false
- description: Comma-separated list of fields to include. id is always included.
+ description: Bearer token for authenticated customers
schema:
type: string
- responses:
- '200':
- description: collection found by prefix ID
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Collection"
- '404':
- description: collection from other store not accessible
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/collections/{collection_id}/products":
- get:
- summary: List collection products
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Products in the collection. Defaults to the collection's own sort
- order and accepts the same filters, sort, and pagination as the products endpoint.
- parameters:
- - name: x-spree-api-key
+ - name: x-spree-token
in: header
- required: true
+ required: false
+ description: Order token for guest access
schema:
type: string
- - name: collection_id
+ - name: cart_id
in: path
required: true
- description: Collection permalink or prefix ID
+ description: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: sort
- in: query
+ - name: Idempotency-Key
+ in: header
required: false
- description: Sort order (e.g., price, -price). Defaults to the collection's
- sort_order.
+ description: Unique key for request idempotency.
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
responses:
- '200':
- description: products found
+ '201':
+ description: discount code applied
+ content:
+ application/json:
+ example:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: 4ryA4ms4Nim9TfxNW4fZi3au
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code: save10
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: "-10.0"
+ display_adjustment_total: "-$10.00"
+ discount_total: "-10.0"
+ display_discount_total: "-$10.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts:
+ - id: discount_UkLWZg9DAJ
+ promotion_id: promo_UkLWZg9DAJ
+ name: Promo
+ description:
+ code: save10
+ amount: "-10.0"
+ display_amount: "-$10.00"
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 1984241
+ slug: product-1984241
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '0.0'
+ display_total: "$0.00"
+ adjustment_total: "-10.0"
+ display_adjustment_total: "-$10.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: "-10.0"
+ display_discount_total: "-$10.00"
+ pre_tax_amount: '0.0'
+ display_pre_tax_amount: "$0.00"
+ discounted_amount: '0.0'
+ display_discounted_amount: "$0.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ schema:
+ "$ref": "#/components/schemas/Cart"
+ '422':
+ description: invalid discount code
content:
application/json:
+ example:
+ error:
+ code: processing_error
+ message: The coupon code you entered doesn't exist. Please try again.
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Product"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- "/api/v3/store/account/companies":
- get:
- summary: List my company memberships
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ code:
+ type: string
+ example: SAVE10
+ description: Promotion discount code to apply
+ required:
+ - code
+ "/api/v3/store/carts/{cart_id}/discount_codes/{id}":
+ delete:
+ summary: Remove discount code
tags:
- - Companies
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: |
- Returns the authenticated customer's company memberships, each with the node it
- is held on and the path of nodes above it. Standing covers the node and every
- node below it, so a membership on a parent authorizes buying for its divisions.
+ description: Removes a previously applied discount code from the cart. The ID
+ is the discount code string itself.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1787,8 +3137,9 @@ paths:
publishableKey: '<api-key>',
})
- // The buyer's memberships, each carrying its node and the path above it.
- const { data: memberships } = await client.account.companies({ token: '<token>' })
+ const cart = await client.carts.discountCodes.remove('cart_abc123', 'SAVE10', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
@@ -1797,134 +3148,191 @@ paths:
type: string
- name: Authorization
in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: memberships listed
- '401':
- description: not authenticated
- "/api/v3/store/companies/{id}":
- parameters:
- - name: id
- in: path
- required: true
- description: Company node ID (comp_...)
- schema:
- type: string
- get:
- summary: Get a company node
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: |
- Returns one node of the buyer's organization. Requires standing — a membership on
- the node or on one of its ancestors; any other node is not found rather than
- refused, so its existence is not disclosed.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const company = await client.companies.get('comp_86Rf07xd4z', { token: '<token>' })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- - name: Authorization
- in: header
+ - name: cart_id
+ in: path
required: true
+ description: Cart prefixed ID
schema:
type: string
- responses:
- '200':
- description: company found
- content:
- application/json:
- example:
- id: comp_UkLWZg9DAJ
- name: Acme Industrial
- kind: company
- po_number_required: false
- parent_id:
- ancestors: []
- '404':
- description: no standing over this node
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Company not found
- patch:
- summary: Update a company node
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: Renames the node. Structure — the parent and the kind — is managed
- by the merchant, not by buyers.
- parameters:
- - name: x-spree-api-key
- in: header
+ - name: id
+ in: path
required: true
+ description: The discount code string to remove (e.g., SAVE10)
schema:
type: string
- - name: Authorization
+ - name: x-spree-token
in: header
- required: true
+ required: false
+ description: Order token for guest access
schema:
type: string
responses:
'200':
- description: company updated
+ description: discount code removed
content:
application/json:
example:
- id: comp_UkLWZg9DAJ
- name: Acme Industrial Group
- kind: company
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
po_number_required: false
- parent_id:
- ancestors: []
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Acme Industrial Group
- "/api/v3/store/companies/{company_id}/members":
- parameters:
- - name: company_id
- in: path
- required: true
- description: Company node ID (comp_...)
- schema:
- type: string
- get:
- summary: List company members
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: gvr8TwNVJpxWf27uUHDj5Lj4
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 2003461
+ slug: product-2003461
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ schema:
+ "$ref": "#/components/schemas/Cart"
+ '422':
+ description: discount code not found on cart
+ content:
+ application/json:
+ example:
+ error:
+ code: processing_error
+ message: The coupon code you entered doesn't exist. Please try again.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/carts/{cart_id}/fulfillments/{id}":
+ patch:
+ summary: Select delivery rate for fulfillment
tags:
- - Companies
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: The people with standing over this node. Within a company every
- member may read and manage the directory.
+ description: Selects a delivery rate for a specific fulfillment and auto-advances
+ checkout.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const cart = await client.carts.fulfillments.update(
+ 'cart_abc123',
+ 'ful_abc123',
+ {
+ selected_delivery_rate_id: 'dr_abc123',
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
@@ -1933,41 +3341,274 @@ paths:
type: string
- name: Authorization
in: header
+ required: false
+ schema:
+ type: string
+ - name: cart_id
+ in: path
+ required: true
+ description: Cart prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
required: true
+ description: Fulfillment ID
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
schema:
type: string
responses:
'200':
- description: members listed
+ description: delivery rate selected, returns updated cart
+ content:
+ application/json:
+ example:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: KLLfFWg9T6dGonBb65hHjaZr
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '20.0'
+ display_total: "$20.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '20.0'
+ display_amount_due: "$20.00"
+ delivery_total: '10.0'
+ display_delivery_total: "$10.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: payment
+ completed_steps:
+ - address
+ - delivery
+ requirements:
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: false
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 2028182
+ slug: product-2028182
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: cart_UkLWZg9DAJ-F1
+ tracking:
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '10.0'
+ display_cost: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries: []
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ name: Monnie O'Keefe
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ additional_tax_total: '0.0'
+ included_tax_total: '0.0'
+ tax_total: '0.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ display_additional_tax_total: "$0.00"
+ display_included_tax_total: "$0.00"
+ display_tax_total: "$0.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ payments: []
+ billing_address:
+ shipping_address:
+ id: addr_EfhxLZ9ck8
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 270 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
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ schema:
+ "$ref": "#/components/schemas/Cart"
+ '404':
+ description: delivery rate not found
content:
application/json:
example:
- data:
- - id: cmem_UkLWZg9DAJ
- company_id: comp_UkLWZg9DAJ
- customer_id: cust_UkLWZg9DAJ
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ error:
+ code: record_not_found
+ message: Delivery rate not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ selected_delivery_rate_id:
+ type: string
+ example: dr_abc123
+ description: Delivery rate ID to select
+ required:
+ - selected_delivery_rate_id
+ "/api/v3/store/carts/{cart_id}/gift_cards":
post:
- summary: Add a member by email
+ summary: Apply gift card
tags:
- - Companies
+ - Carts
security:
- api_key: []
bearer_auth: []
description: |
- Adds a person to the node by email. An email that already belongs to a customer of
- this store becomes a membership immediately (a `cmem_...` id); any other email
- becomes an invitation (a `cinv_...` id) and the invite email goes out.
+ Applies a gift card to the cart. Gift cards are treated as a payment method, not a discount —
+ the cart `total` remains unchanged while `amount_due` is reduced.
+
+ For promotion discount codes, use the `POST /carts/{cart_id}/discount_codes` endpoint instead.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -1979,13 +3620,9 @@ paths:
publishableKey: '<api-key>',
})
- // An existing customer joins immediately (cmem_…); anyone else is emailed an
- // invitation (cinv_…).
- const member = await client.companies.members.create(
- 'comp_86Rf07xd4z',
- { customer_email: '[email protected]' },
- { token: '<token>' },
- )
+ const cart = await client.carts.giftCards.apply('cart_abc123', 'GC-ABCD-1234', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
@@ -1994,154 +3631,247 @@ paths:
type: string
- name: Authorization
in: header
- required: true
+ required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- responses:
- '201':
- description: member added or invitation sent
- content:
- application/json:
- example:
- id: cmem_gbHJdmfrXB
- company_id: comp_UkLWZg9DAJ
- customer_id: cust_gbHJdmfrXB
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- customer_email:
- type: string
- required:
- - customer_email
- "/api/v3/store/companies/{company_id}/addresses":
- parameters:
- - name: company_id
- in: path
- required: true
- description: Company node ID (comp_...)
- schema:
- type: string
- get:
- summary: List the company address book
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: The labeled ship-to and bill-to sites this node owns. A node with
- no default of its own falls back to its nearest ancestor when prefilling checkout.
- parameters:
- - name: x-spree-api-key
+ - name: x-spree-token
in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ - name: cart_id
+ in: path
required: true
+ description: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: Authorization
+ - name: Idempotency-Key
in: header
- required: true
+ required: false
+ description: Unique key for request idempotency.
schema:
type: string
responses:
- '200':
- description: addresses listed
+ '201':
+ description: gift card applied
+ content:
+ application/json:
+ example:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: nZjAPYSKrNaHf2ZVT6eZfNJV
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '10.0'
+ display_gift_card_total: "$10.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '10.0'
+ display_store_credit_total: "-$10.00"
+ covered_by_store_credit: true
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 2045702
+ slug: product-2045702
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: 1-SC-20260115120000000000
+ number: cart_UkLWZg9DAJ-P1
+ status: checkout
+ amount: '10.0'
+ display_amount: "$10.00"
+ source_type: store_credit
+ source_id: credit_UkLWZg9DAJ
+ source:
+ id: credit_UkLWZg9DAJ
+ amount: '10.0'
+ amount_used: '0.0'
+ amount_remaining: '10.0'
+ display_amount: "$10.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$10.00"
+ currency: USD
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: store_credit
+ session_required: false
+ source_required: true
+ billing_address:
+ shipping_address:
+ payment_methods:
+ - id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: store_credit
+ session_required: false
+ source_required: true
+ gift_card:
+ id: gc_UkLWZg9DAJ
+ code: GIFTCODE1
+ status: active
+ currency: USD
+ amount: '50.0'
+ amount_used: '10.0'
+ amount_authorized: '0.0'
+ amount_remaining: '40.0'
+ display_amount: "$50.00"
+ display_amount_used: "$10.00"
+ display_amount_remaining: "$40.00"
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ schema:
+ "$ref": "#/components/schemas/Cart"
+ '404':
+ description: gift card not found
content:
application/json:
example:
- data:
- - id: addr_EfhxLZ9ck8
- label: Headquarters
- first_name:
- last_name:
- full_name: ''
- address1: 42 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
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- "/api/v3/store/companies/{company_id}/addresses/{id}":
- parameters:
- - name: company_id
- in: path
- required: true
- description: Company node ID (comp_...)
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Address ID (addr_...)
- schema:
- type: string
- patch:
- summary: Update an address book entry
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: Renames a site or moves the default ship-to or bill-to flag to
- it. Only one entry per node holds each default.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: address book entry updated
+ error:
+ code: gift_card_not_found
+ message: The Gift Card was not found.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '422':
+ description: gift card already redeemed
+ content:
+ application/json:
+ example:
+ error:
+ code: gift_card_already_redeemed
+ message: The Gift Card has already been redeemed.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- label:
+ code:
type: string
- example: Northern Warehouse
- default_shipping:
- type: boolean
- example: true
+ example: GC-ABCD-1234
+ description: Gift card code to apply
+ required:
+ - code
+ "/api/v3/store/carts/{cart_id}/gift_cards/{id}":
delete:
- summary: Remove an address book entry
+ summary: Remove gift card
tags:
- - Companies
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Takes the site out of the address book. Orders already placed to
- it keep their own copy of the address.
+ description: Removes a previously applied gift card from the cart.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const cart = await client.carts.giftCards.remove('cart_abc123', 'gc_abc123', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
@@ -2150,438 +3880,449 @@ paths:
type: string
- name: Authorization
in: header
- required: true
- schema:
- type: string
- responses:
- '204':
- description: address book entry removed
- "/api/v3/store/companies/{company_id}/invitations/{id}":
- parameters:
- - name: company_id
- in: path
- required: true
- description: Company node ID (comp_...)
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Invitation ID (cinv_...)
- schema:
- type: string
- delete:
- summary: Revoke an invitation
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: Withdraws a pending invitation, spending its token. Any member
- with standing over the node may revoke.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- - name: Authorization
- in: header
+ - name: cart_id
+ in: path
required: true
+ description: Cart prefixed ID
schema:
type: string
- responses:
- '204':
- description: invitation revoked
- "/api/v3/store/companies/{company_id}/orders":
- parameters:
- - name: company_id
- in: path
- required: true
- description: Company node ID (comp_...)
- schema:
- type: string
- get:
- summary: List the company purchases
- tags:
- - Companies
- security:
- - api_key: []
- bearer_auth: []
- description: Completed orders placed for this node and every node below it,
- so a parent sees what its divisions bought.
- parameters:
- - name: x-spree-api-key
- in: header
+ - name: id
+ in: path
required: true
+ description: Gift card prefixed ID (e.g., gc_abc123)
schema:
type: string
- - name: Authorization
+ - name: x-spree-token
in: header
- required: true
+ required: false
+ description: Order token for guest access
schema:
type: string
responses:
'200':
- description: orders listed
+ description: gift card removed
content:
application/json:
example:
- data:
- - id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id: comp_UkLWZg9DAJ
- company_name: Acme Industrial
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: Wgq8NrLX3TUQLroJRYWFdQd5
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
currency: USD
- locale: en
- total_quantity: 1
- coupon_code:
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
- display_item_total: "$10.00"
+ name: Product 2089569
+ slug: product-2089569
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 725649
- slug: product-725649
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- tracking: U10000
- tracking_url:
- pickup_point_data:
- selected_delivery_rate_id: dr_gbHJdmfrXB
- cost: '100.0'
- display_cost: "$100.00"
- total: '100.0'
- display_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- status: unfulfilled
- fulfillment_type: shipping
- fulfilled_at:
- delivered_at:
- items:
- - item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- stock_location:
- id: sloc_UkLWZg9DAJ
- name: Kali Pacocha
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- delivery_rates:
- - id: dr_gbHJdmfrXB
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- display_additional_tax_total: "$0.00"
- display_included_tax_total: "$0.00"
- display_tax_total: "$0.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- payments: []
- billing_address:
- id: addr_EfhxLZ9ck8
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 47 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
- shipping_address:
- id: addr_VqXmZF31wY
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 48 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
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: 1-SC-20260115120000000000
+ number: cart_UkLWZg9DAJ-P1
+ status: invalid
+ amount: '10.0'
+ display_amount: "$10.00"
+ source_type: store_credit
+ source_id: credit_UkLWZg9DAJ
+ source:
+ id: credit_UkLWZg9DAJ
+ amount: '10.0'
+ amount_used: '0.0'
+ amount_remaining: '10.0'
+ display_amount: "$10.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$10.00"
currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
- "/api/v3/store/company_invitations/{token}":
- parameters:
- - name: token
- in: path
- required: true
- description: Plaintext invitation token from the invite email
- schema:
- type: string
- get:
- summary: Look up an invitation
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description:
+ type: store_credit
+ session_required: false
+ source_required: true
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ schema:
+ "$ref": "#/components/schemas/Cart"
+ "/api/v3/store/carts/{cart_id}/items":
+ post:
+ summary: Add item to cart
tags:
- - Companies
+ - Carts
security:
- api_key: []
- description: |
- Shows what is being joined, so the acceptance page can render before the invitee
- has an account. Deliberately unauthenticated — the token from the email is the
- credential. Spent, revoked and expired tokens are not found.
+ bearer_auth: []
+ description: Adds a variant to the cart. Creates a new line item or increases
+ quantity if variant already in cart.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const cart = await client.carts.items.create(
+ 'cart_abc123',
+ {
+ variant_id: 'variant_abc123',
+ quantity: 2,
+ },
+ {
+ token: '<token>',
+ },
+ )
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: cart_id
+ in: path
+ required: true
+ description: Cart prefixed ID (e.g., cart_abc123)
+ schema:
+ type: string
+ - name: Idempotency-Key
+ in: header
+ required: false
+ description: Unique key for request idempotency.
+ schema:
+ type: string
responses:
- '200':
- description: invitation found
+ '201':
+ description: item added with metadata
content:
application/json:
example:
- id: cinv_UkLWZg9DAJ
- expires_at: '2026-02-14T12:00:00.000Z'
- company_id: comp_UkLWZg9DAJ
- status: pending
- company_name: Acme Industrial
- store_name: Spree Test Store
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: d12LXVnL3KtzGjXePqRawnPc
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 2
+ warnings:
+ - code: delivery_unavailable
+ message: Product 21163 cannot be delivered to the selected address
+ line_item_id: li_UkLWZg9DAJ
+ - code: delivery_unavailable
+ message: Product 212298 cannot be delivered to the selected address
+ line_item_id: li_gbHJdmfrXB
+ coupon_code:
+ item_total: '29.99'
+ display_item_total: "$29.99"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '29.99'
+ display_total: "$29.99"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '29.99'
+ display_amount_due: "$29.99"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 21163
+ slug: product-21163
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ - id: li_gbHJdmfrXB
+ variant_id: variant_gbHJdmfrXB
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 212298
+ slug: product-212298
+ options_text: ''
+ price: '19.99'
+ display_price: "$19.99"
+ total: '19.99'
+ display_total: "$19.99"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '19.99'
+ display_pre_tax_amount: "$19.99"
+ discounted_amount: '19.99'
+ display_discounted_amount: "$19.99"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ schema:
+ "$ref": "#/components/schemas/Cart"
'404':
- description: token spent, revoked or expired
+ description: variant not found
content:
application/json:
example:
error:
- code: record_not_found
- message: Company invitation not found
- "/api/v3/store/company_invitations/{token}/accept":
- parameters:
- - name: token
- in: path
- required: true
- description: Plaintext invitation token from the invite email
- schema:
- type: string
- post:
- summary: Accept an invitation
- tags:
- - Companies
- security:
- - api_key: []
- description: |
- Turns the invitation into a membership. Send a registration payload to create the
- account — it is always created with the invited email — or call it authenticated as
- the customer who owns that email to bind the invitation to the existing account.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- // Unauthenticated: the token from the invite email is the credential, and the
- // registration payload creates the account with the invited address.
- const membership = await client.companyInvitations.accept('<invitation-token>', {
- first_name: 'Ada',
- password: 'a-strong-password',
- password_confirmation: 'a-strong-password',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- responses:
- '201':
- description: membership created
+ code: variant_not_found
+ message: Variant not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '422':
+ description: rejected by a store rule
content:
application/json:
example:
- id: cmem_UkLWZg9DAJ
- company_id: comp_UkLWZg9DAJ
- customer_id: cust_UkLWZg9DAJ
+ error:
+ code: validation_error
+ message: Quantity You can order at most 10 of this item.
+ details:
+ quantity:
+ - You can order at most 10 of this item.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- first_name:
- type: string
- example: Ada
- last_name:
- type: string
- example: Lovelace
- password:
- type: string
- example: a-strong-password
- password_confirmation:
+ variant_id:
type: string
- example: a-strong-password
- "/api/v3/store/countries":
- get:
- summary: List countries
+ example: variant_abc123
+ description: Variant ID to add
+ quantity:
+ type: integer
+ example: 2
+ description: 'Quantity to add (default: 1)'
+ metadata:
+ type: object
+ additionalProperties: true
+ description: Arbitrary key-value metadata
+ example:
+ gift_message: Happy Birthday!
+ required:
+ - variant_id
+ "/api/v3/store/carts/{cart_id}/items/{id}":
+ patch:
+ summary: Update line item quantity
tags:
- - Markets
+ - Carts
security:
- api_key: []
- description: Returns countries available in the store. Use ?expand=market to
- include market details (currency, locale, tax_inclusive).
+ bearer_auth: []
+ description: Updates the quantity of a line item in the cart
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2593,146 +4334,194 @@ paths:
publishableKey: '<api-key>',
})
- const countries = await client.countries.list()
+ const cart = await client.carts.items.update(
+ 'cart_abc123',
+ 'li_abc123',
+ {
+ quantity: 5,
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: countries found
- content:
- application/json:
- example:
- data:
- - iso: DE
- iso3: DEU
- name: Germany
- states_required: false
- zipcode_required: true
- - iso: US
- iso3: USA
- name: United States
- states_required: true
- zipcode_required: true
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Country"
- required:
- - data
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: invalid_token
- message: Valid API key required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/countries/{iso}":
- get:
- summary: Get a country
- tags:
- - Markets
- security:
- - api_key: []
- description: Returns a single country by ISO code. Supports ?expand=states for
- address forms and ?expand=market for market details.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const country = await client.countries.get('US')
- parameters:
- - name: x-spree-api-key
+ - name: Authorization
in: header
- required: true
- schema:
- type: string
- - name: iso
- in: path
- required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE")
- schema:
- type: string
- - name: fields
- in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
- responses:
- '200':
- description: country found
- content:
- application/json:
- example:
- iso: US
- iso3: USA
- name: United States
- states_required: true
- zipcode_required: true
- schema:
- type: object
- properties:
- iso:
- type: string
- iso3:
- type: string
- name:
- type: string
- states_required:
- type: boolean
- zipcode_required:
- type: boolean
- required:
- - iso
- - iso3
- - name
- - states_required
- - zipcode_required
- '404':
- description: country not found
+ schema:
+ type: string
+ - name: cart_id
+ in: path
+ required: true
+ description: Cart prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Line item ID
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ schema:
+ type: string
+ responses:
+ '200':
+ description: quantity change rejected, reported in warnings
content:
application/json:
example:
- error:
- code: record_not_found
- message: record not found
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: Yq5XuZqq7KS7y7n2dMsChnZM
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings:
+ - code: purchase_limit_exceeded
+ message: Quantity You can order at most 10 of this item.
+ variant_id: variant_UkLWZg9DAJ
+ item_index: 0
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 2189165
+ slug: product-2189165
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/credit_cards":
- get:
- summary: List saved credit cards
+ "$ref": "#/components/schemas/Cart"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ quantity:
+ type: integer
+ minimum: 1
+ example: 5
+ metadata:
+ type: object
+ additionalProperties: true
+ description: Arbitrary key-value metadata (merged with existing)
+ example:
+ engraving: J.D.
+ delete:
+ summary: Remove line item from cart
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Returns the authenticated customer's saved credit cards for the
- current store's payment methods
+ description: Removes a line item from the cart
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2744,12 +4533,9 @@ paths:
publishableKey: '<api-key>',
})
- const cards = await client.customer.creditCards.list(
- {},
- {
- token: '<token>',
- },
- )
+ const cart = await client.carts.items.delete('cart_abc123', 'li_abc123', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
@@ -2758,79 +4544,133 @@ paths:
type: string
- name: Authorization
in: header
- required: true
+ required: false
schema:
type: string
- - name: page
- in: query
- required: false
+ - name: cart_id
+ in: path
+ required: true
+ description: Cart prefixed ID
schema:
- type: integer
- - name: limit
- in: query
- required: false
+ type: string
+ - name: id
+ in: path
+ required: true
schema:
- type: integer
- - name: fields
- in: query
+ type: string
+ - name: x-spree-token
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
schema:
type: string
responses:
'200':
- description: credit cards found
+ description: line item removed, returns updated cart
content:
application/json:
example:
- data:
- - id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: arTvbVzmU1krWKLbRnWDZ3cL
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 0
+ warnings: []
+ coupon_code:
+ item_total: '0.0'
+ display_item_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '0.0'
+ display_total: "$0.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: line_items_required
+ step: cart
+ field: line_items
+ message: Add at least one item to your cart
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items: []
+ fulfillments: []
+ payments: []
+ billing_address:
+ shipping_address:
+ payment_methods: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/CreditCard"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/Cart"
+ '404':
+ description: line item not found
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: line_item_not_found
+ message: Line item not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/credit_cards/{id}":
- get:
- summary: Get a credit card
+ "/api/v3/store/carts/{cart_id}/payment_sessions":
+ post:
+ summary: Create payment session
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Returns a saved credit card by its ID
+ description: Creates a new payment session for the cart. Delegates to the payment
+ gateway to initialize a provider-specific session (e.g. Stripe PaymentIntent,
+ Adyen session, PayPal order).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2842,9 +4682,15 @@ paths:
publishableKey: '<api-key>',
})
- const card = await client.customer.creditCards.get('card_abc123', {
- token: '<token>',
- })
+ const session = await client.carts.paymentSessions.create(
+ 'cart_abc123',
+ {
+ payment_method_id: 'pm_abc123',
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
@@ -2853,55 +4699,115 @@ paths:
type: string
- name: Authorization
in: header
- required: true
+ required: false
+ description: Bearer token for authenticated customers
schema:
type: string
- - name: id
+ - name: cart_id
in: path
required: true
+ description: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: fields
- in: query
+ - name: x-spree-token
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ description: Order token for guest access
+ schema:
+ type: string
+ - name: Idempotency-Key
+ in: header
+ required: false
+ description: Unique key for request idempotency.
schema:
type: string
responses:
- '200':
- description: credit card found
- content:
- application/json:
- example:
- id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- schema:
- "$ref": "#/components/schemas/CreditCard"
- '404':
- description: credit card not found
+ '201':
+ description: payment session created
content:
application/json:
example:
- error:
- code: record_not_found
- message: Credit card not found
+ id: ps_gbHJdmfrXB
+ status: pending
+ currency: USD
+ external_id: bogus_208a8eb2883f955fd5c07616
+ external_data:
+ client_secret: bogus_secret_a8b3afe691c933c1
+ customer_external_id:
+ expires_at:
+ amount: '10.0'
+ payment_method_id: pm_UkLWZg9DAJ
+ order_id: cart_UkLWZg9DAJ
+ cart_id: cart_UkLWZg9DAJ
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Credit Card
+ description:
+ type: bogus
+ session_required: true
+ source_required: true
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- delete:
- summary: Delete a credit card
+ "$ref": "#/components/schemas/PaymentSession"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ payment_method_id:
+ type: string
+ example: pm_abc123
+ description: Payment method ID
+ amount:
+ type: string
+ example: '99.99'
+ description: Payment amount (defaults to order total minus store
+ credits)
+ external_data:
+ type: object
+ description: Provider-specific data passed to the gateway
+ required:
+ - payment_method_id
+ "/api/v3/store/carts/{cart_id}/payment_sessions/{id}":
+ 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: cart_id
+ in: path
+ required: true
+ description: Cart prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Payment session ID
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ get:
+ summary: Get payment session
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Removes a saved credit card from the customer account
+ description: Returns a single payment session with its current status and provider
+ data.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2913,46 +4819,55 @@ paths:
publishableKey: '<api-key>',
})
- await client.customer.creditCards.delete('card_abc123', {
+ const session = await client.carts.paymentSessions.get('cart_abc123', 'ps_abc123', {
token: '<token>',
})
- 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: credit card deleted
+ '200':
+ description: payment session found
+ content:
+ application/json:
+ example:
+ id: ps_UkLWZg9DAJ
+ status: pending
+ currency: USD
+ external_id: bogus_96d0ebf0a4300304c930f3c0
+ external_data:
+ client_secret: secret_123
+ customer_external_id:
+ expires_at:
+ amount: '10.0'
+ payment_method_id: pm_UkLWZg9DAJ
+ order_id: cart_UkLWZg9DAJ
+ cart_id: cart_UkLWZg9DAJ
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Credit Card
+ description:
+ type: bogus
+ session_required: true
+ source_required: true
+ schema:
+ "$ref": "#/components/schemas/PaymentSession"
'404':
- description: credit card not found
+ description: payment session not found
content:
application/json:
example:
error:
code: record_not_found
- message: Credit card not found
+ message: Payment session not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/currencies":
- get:
- summary: List supported currencies
+ patch:
+ summary: Update payment session
tags:
- - Markets
+ - Carts
security:
- api_key: []
- description: Returns currencies supported by the store (derived from markets)
+ bearer_auth: []
+ description: Updates a payment session. Delegates to the payment gateway to
+ sync changes with the provider.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -2964,64 +4879,97 @@ paths:
publishableKey: '<api-key>',
})
- const currencies = await client.currencies.list()
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
+ const session = await client.carts.paymentSessions.update(
+ 'cart_abc123',
+ 'ps_abc123',
+ {
+ amount: '50.00',
+ },
+ {
+ token: '<token>',
+ },
+ )
+ parameters: []
responses:
'200':
- description: currencies found
- content:
- application/json:
- example:
- data:
- - iso_code: USD
- name: United States Dollar
- symbol: "$"
- - iso_code: EUR
- name: Euro
- symbol: "€"
- - iso_code: GBP
- name: British Pound
- symbol: "£"
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Currency"
- required:
- - data
- '401':
- description: unauthorized
+ description: payment session updated
content:
application/json:
example:
- error:
- code: invalid_token
- message: Valid API key required
+ id: ps_UkLWZg9DAJ
+ status: pending
+ currency: USD
+ external_id: bogus_8a53bedc6c12205d0e31f231
+ external_data:
+ client_secret: secret_123
+ customer_external_id:
+ expires_at:
+ amount: '50.0'
+ payment_method_id: pm_UkLWZg9DAJ
+ order_id: cart_UkLWZg9DAJ
+ cart_id: cart_UkLWZg9DAJ
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Credit Card
+ description:
+ type: bogus
+ session_required: true
+ source_required: true
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/password_resets":
- post:
- summary: Request a password reset
+ "$ref": "#/components/schemas/PaymentSession"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ amount:
+ type: string
+ example: '50.00'
+ description: Updated payment amount
+ external_data:
+ type: object
+ description: Provider-specific data to update
+ "/api/v3/store/carts/{cart_id}/payment_sessions/{id}/complete":
+ 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: cart_id
+ in: path
+ required: true
+ description: Cart prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Payment session ID
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ patch:
+ summary: Complete payment session
tags:
- - Authentication
+ - Carts
security:
- api_key: []
- description: Sends a password reset email if an account exists for the given
- email address. Always returns 202 Accepted to prevent email enumeration.
+ bearer_auth: []
+ description: Completes a payment session by confirming the payment with the
+ provider. This triggers payment capture/authorization and order completion.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3033,37 +4981,58 @@ paths:
publishableKey: '<api-key>',
})
- await client.passwordResets.create({
- email: '[email protected]',
- redirect_url: 'https://myshop.com/reset-password',
- })
+ const session = await client.carts.paymentSessions.complete(
+ 'cart_abc123',
+ 'ps_abc123',
+ {
+ session_result: 'success',
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- - name: x-spree-api-key
+ - name: Idempotency-Key
in: header
- required: true
+ required: false
+ description: Unique key for request idempotency.
schema:
type: string
responses:
- '202':
- description: email not found (same response to prevent enumeration)
+ '200':
+ description: payment session completed
content:
application/json:
example:
- message: If an account exists for that email, password reset instructions
- have been sent.
+ id: ps_UkLWZg9DAJ
+ status: completed
+ currency: USD
+ external_id: bogus_f6de6a6c7dddf8f63c45a3f0
+ external_data:
+ client_secret: secret_123
+ customer_external_id:
+ expires_at:
+ amount: '10.0'
+ payment_method_id: pm_UkLWZg9DAJ
+ order_id: cart_UkLWZg9DAJ
+ cart_id: cart_UkLWZg9DAJ
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Credit Card
+ description:
+ type: bogus
+ session_required: true
+ source_required: true
schema:
- type: object
- properties:
- message:
- type: string
- '401':
- description: missing API key
+ "$ref": "#/components/schemas/PaymentSession"
+ '404':
+ description: payment session not found
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: record_not_found
+ message: Payment session not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -3072,28 +5041,23 @@ paths:
schema:
type: object
properties:
- email:
- type: string
- format: email
- description: Email address of the account to reset
- redirect_url:
+ session_result:
type: string
- format: uri
- example: https://myshop.com/reset-password
- description: URL to redirect the user to after clicking the reset
- link. Validated against the store's allowed origins.
- required:
- - email
- "/api/v3/store/password_resets/{token}":
- patch:
- summary: Reset password with token
+ description: Provider-specific session result token
+ external_data:
+ type: object
+ description: Provider-specific completion data
+ "/api/v3/store/carts/{cart_id}/payments":
+ post:
+ summary: Create payment
tags:
- - Authentication
+ - Carts
security:
- api_key: []
- description: Resets the password using a token received via email. Returns a
- JWT token on success (auto-login).
+ bearer_auth: []
+ description: Creates a payment for a non-session payment method (e.g. Check,
+ Cash on Delivery, Bank Transfer). For payment methods that require a session
+ (e.g. Stripe, PayPal), use the payment sessions endpoint instead.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3105,68 +5069,72 @@ paths:
publishableKey: '<api-key>',
})
- const auth = await client.passwordResets.update('reset-token-from-email', {
- password: 'newsecurepassword',
- password_confirmation: 'newsecurepassword',
- })
+ const payment = await client.carts.payments.create(
+ 'cart_abc123',
+ {
+ payment_method_id: 'pm_abc123',
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: token
+ - name: Authorization
+ in: header
+ required: false
+ schema:
+ type: string
+ - name: cart_id
in: path
required: true
- description: Password reset token from the email
+ description: Cart prefixed ID
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
schema:
type: string
responses:
- '200':
- description: password reset successful
+ '201':
+ description: payment created
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjdlOGI2Njc5LTBjNzYtNDQ1Mi1hMWMyLWJhY2U0MWNhN2IyMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.grC4diUECUp8b3p6jJBHAZp_MyiSUQwA4rdQLel_zuM
- refresh_token: JNJKeT5cELhdSfb2tWHj3ctp
- user:
- id: cust_UkLWZg9DAJ
- first_name: Lucas
- last_name: Stiedemann
- phone:
- accepts_email_marketing: false
- full_name: Lucas Stiedemann
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses: []
- default_billing_address:
- default_shipping_address:
- newsletter_subscriber:
- customer_groups: []
+ id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code:
+ number: cart_UkLWZg9DAJ-P1
+ status: checkout
+ amount: '10.0'
+ display_amount: "$10.00"
+ source_type:
+ source_id:
+ source:
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Check
+ description:
+ type: check
+ session_required: false
+ source_required: false
schema:
- "$ref": "#/components/schemas/AuthResponse"
+ "$ref": "#/components/schemas/Payment"
'422':
- description: password confirmation mismatch
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Password confirmation doesn't match Password
- details:
- password_confirmation:
- - doesn't match Password
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: missing API key
+ description: session-based payment method
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: payment_session_required
+ message: This payment method requires a payment session. Use the
+ payment sessions endpoint instead.
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -3175,26 +5143,29 @@ paths:
schema:
type: object
properties:
- password:
+ payment_method_id:
type: string
- minLength: 6
- example: newsecurepassword
- password_confirmation:
+ example: pm_abc123
+ description: Payment method ID (must be a non-session payment method)
+ amount:
type: string
- example: newsecurepassword
+ example: '99.99'
+ description: Payment amount (defaults to order total minus store
+ credits)
+ metadata:
+ type: object
+ description: Arbitrary metadata to attach to the payment
required:
- - password
- - password_confirmation
- "/api/v3/store/customers/me/orders":
- get:
- summary: List orders
+ - payment_method_id
+ "/api/v3/store/carts/{cart_id}/store_credits":
+ post:
+ summary: Apply store credit
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Returns a paginated list of completed orders for the authenticated
- customer.
+ description: Applies store credit to the cart during checkout.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3206,13 +5177,9 @@ paths:
publishableKey: '<api-key>',
})
- const orders = await client.customer.orders.list(
- {
- completed_at_gt: '2026-01-01',
- sort: '-completed_at',
- },
- { token: '<token>' },
- )
+ const cart = await client.carts.storeCredits.apply('cart_abc123', 10.0, {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
@@ -3224,351 +5191,200 @@ paths:
required: true
schema:
type: string
- - name: page
- in: query
- required: false
- description: 'Page number (default: 1)'
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: 'Number of results per page (default: 25, max: 100)'
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: 'Sort order. Prefix with - for descending. Values: completed_at,
- -completed_at, total, -total, number, -number'
- schema:
- type: string
- - name: q[completed_at_gt]
- in: query
- required: false
- description: Filter by completed after date (ISO 8601)
- schema:
- type: string
- - name: q[completed_at_lt]
- in: query
- required: false
- description: Filter by completed before date (ISO 8601)
- schema:
- type: string
- - name: q[number_eq]
- in: query
- required: false
- description: Filter by exact order number (e.g., R123456)
- schema:
- type: string
- - name: q[state_eq]
- in: query
- required: false
- description: Filter by order state (complete, returned, canceled)
- schema:
- type: string
- - name: q[payment_state_eq]
- in: query
- required: false
- description: Filter by payment state (paid, balance_due, credit_owed, void,
- failed)
+ - name: cart_id
+ in: path
+ required: true
+ description: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: q[total_gteq]
- in: query
- required: false
- description: Filter by minimum total
- schema:
- type: number
- - name: q[total_lteq]
- in: query
- required: false
- description: Filter by maximum total
- schema:
- type: number
- - name: expand
- in: query
+ - name: x-spree-token
+ in: header
required: false
- description: Comma-separated associations to expand (items, fulfillments,
- payments, discounts, billing_address, shipping_address, gift_card). Use
- "none" to skip associations.
schema:
type: string
- - name: fields
- in: query
+ - name: Idempotency-Key
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
- id is always included.
+ description: Unique key for request idempotency.
schema:
type: string
responses:
'200':
- description: orders listed
+ description: store credit applied
content:
application/json:
example:
- data:
- - id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- cart_id:
- channel_id: ch_UkLWZg9DAJ
- company_id:
- company_name:
- po_document_filename:
- po_document_byte_size:
- number: R1001
- customer_note:
- po_number:
+ id: cart_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
+ company_id:
+ company_name:
+ po_number_required: false
+ po_document_filename:
+ po_document_byte_size:
+ number: cart_UkLWZg9DAJ
+ token: acfBZtWemHae74Y3g18LQg1f
+ email:
+ customer_note:
+ po_number:
+ currency: USD
+ locale: en
+ total_quantity: 1
+ warnings: []
+ coupon_code:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '10.0'
+ display_total: "$10.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '0.0'
+ display_amount_due: "$0.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '10.0'
+ display_store_credit_total: "-$10.00"
+ covered_by_store_credit: true
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
currency: USD
- locale: en
- total_quantity: 1
- coupon_code:
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
- item_total: '10.0'
- display_item_total: "$10.00"
+ name: Product 2809789
+ slug: product-2809789
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 735270
- slug: product-735270
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- tracking: U10000
- tracking_url:
- pickup_point_data:
- selected_delivery_rate_id: dr_gbHJdmfrXB
- cost: '100.0'
- display_cost: "$100.00"
- total: '100.0'
- display_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- status: unfulfilled
- fulfillment_type: shipping
- fulfilled_at:
- delivered_at:
- items:
- - item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- stock_location:
- id: sloc_UkLWZg9DAJ
- name: Macy Goyette
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- delivery_rates:
- - id: dr_gbHJdmfrXB
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- display_additional_tax_total: "$0.00"
- display_included_tax_total: "$0.00"
- display_tax_total: "$0.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- payments: []
- billing_address:
- id: addr_EfhxLZ9ck8
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 63 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
- shipping_address:
- id: addr_VqXmZF31wY
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 64 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
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
+ payments:
+ - id: py_UkLWZg9DAJ
+ payment_method_id: pm_UkLWZg9DAJ
+ response_code: 1-SC-20260115120000000000
+ number: cart_UkLWZg9DAJ-P1
+ status: checkout
+ amount: '10.0'
+ display_amount: "$10.00"
+ source_type: store_credit
+ source_id: credit_UkLWZg9DAJ
+ source:
+ id: credit_UkLWZg9DAJ
+ amount: '50.0'
+ amount_used: '0.0'
+ amount_remaining: '50.0'
+ display_amount: "$50.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$50.00"
+ currency: USD
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description: Store Credit
+ type: store_credit
+ session_required: false
+ source_required: true
+ billing_address:
+ shipping_address:
+ payment_methods:
+ - id: pm_UkLWZg9DAJ
+ name: Store Credit
+ description: Store Credit
+ type: store_credit
+ session_required: false
+ source_required: true
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Order"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/Cart"
+ '422':
+ description: no store credit available
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: processing_error
+ message: User does not have any Store Credits available
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/orders/{id}":
- get:
- summary: Get an order
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ amount:
+ type: number
+ example: 10.0
+ description: Amount to apply (optional - defaults to max available)
+ delete:
+ summary: Remove store credit
tags:
- - Customers
+ - Carts
security:
- api_key: []
bearer_auth: []
- description: Returns a single completed order for the authenticated customer.
+ description: Removes store credit from the cart.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3580,13 +5396,9 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.customer.orders.get(
- 'or_abc123',
- {},
- {
- token: '<token>',
- },
- )
+ const cart = await client.carts.storeCredits.remove('cart_abc123', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
@@ -3598,52 +5410,42 @@ paths:
required: true
schema:
type: string
- - name: id
+ - name: cart_id
in: path
required: true
- description: Order prefixed ID
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (items, fulfillments,
- payments, discounts, billing_address, shipping_address, gift_card). Use
- "none" to skip associations.
+ description: Cart prefixed ID
schema:
type: string
- - name: fields
- in: query
+ - name: x-spree-token
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
- id is always included.
schema:
type: string
responses:
'200':
- description: order found
+ description: store credit removed
content:
application/json:
example:
- id: or_UkLWZg9DAJ
+ id: cart_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
- cart_id:
channel_id: ch_UkLWZg9DAJ
+ preferred_stock_location_id:
company_id:
company_name:
+ po_number_required: false
po_document_filename:
po_document_byte_size:
- number: R1001
+ number: cart_UkLWZg9DAJ
+ token: BHWevnp2PQxC1jSWU3ZFLejT
+ email:
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
+ warnings: []
coupon_code:
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -3656,183 +5458,77 @@ paths:
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
+ total: '10.0'
+ display_total: "$10.00"
gift_card_total: '0.0'
display_gift_card_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
+ amount_due: '10.0'
+ display_amount_due: "$10.00"
+ delivery_total: '0.0'
+ display_delivery_total: "$0.00"
fee_total: '0.0'
display_fee_total: "$0.00"
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
+ current_step: address
+ completed_steps: []
+ requirements:
+ - code: email_required
+ step: address
+ field: email
+ message: Email address is required
+ - code: delivery_method_required
+ step: delivery
+ field: delivery_method
+ message: Select a delivery method for all fulfillments
+ - code: payment_required
+ step: payment
+ field: payment
+ message: Add a payment method
+ order_minimum:
+ order_minimum_shortfall:
+ below_order_minimum: false
+ shipping_eq_billing_address: true
discounts: []
fees: []
items:
- id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 755633
- slug: product-755633
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- tracking: U10000
- tracking_url:
- pickup_point_data:
- selected_delivery_rate_id: dr_gbHJdmfrXB
- cost: '100.0'
- display_cost: "$100.00"
- total: '100.0'
- display_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- status: unfulfilled
- fulfillment_type: shipping
- fulfilled_at:
- delivered_at:
- items:
- - item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- stock_location:
- id: sloc_UkLWZg9DAJ
- name: Sunny Bernier
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- delivery_rates:
- - id: dr_gbHJdmfrXB
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- display_additional_tax_total: "$0.00"
- display_included_tax_total: "$0.00"
- display_tax_total: "$0.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 282179
+ slug: product-282179
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments: []
payments: []
billing_address:
- id: addr_EfhxLZ9ck8
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 69 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
shipping_address:
- id: addr_VqXmZF31wY
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 70 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
+ payment_methods: []
gift_card:
market:
id: mkt_UkLWZg9DAJ
@@ -3846,142 +5542,17 @@ paths:
supported_locales:
- en
schema:
- "$ref": "#/components/schemas/Order"
- '404':
- description: order belongs to another user
- content:
- application/json:
- example:
- error:
- code: order_not_found
- message: Order not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers":
- post:
- summary: Register a new customer
- tags:
- - Customers
- security:
- - api_key: []
- description: Creates a new customer account and returns a JWT token
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const auth = await client.customers.create({
- email: '[email protected]',
- password: 'password123',
- password_confirmation: 'password123',
- first_name: 'John',
- last_name: 'Doe',
- phone: '+1234567890',
- accepts_email_marketing: true,
- metadata: { source: 'storefront' },
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- responses:
- '201':
- description: registration successful
- content:
- application/json:
- example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY0OWM2NTkzLTBhZWQtNDA5Ny1hYTI3LThhMjVmYTU4OGI3OSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.llCt1j8kVryteixNYywlzA1x8CGqCNBaKiT3-ihDrsE
- refresh_token: mLm6vdSzLUgPhw8SCzDiagfL
- user:
- id: cust_UkLWZg9DAJ
- first_name: John
- last_name: Doe
- phone: "+1234567890"
- accepts_email_marketing: true
- full_name: John Doe
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses: []
- default_billing_address:
- default_shipping_address:
- newsletter_subscriber:
- id: sub_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- verified: true
- verified_at: '2026-01-15T12:00:00Z'
- customer_id: cust_UkLWZg9DAJ
- customer_groups: []
- schema:
- "$ref": "#/components/schemas/AuthResponse"
- '422':
- description: email already taken
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Email has already been taken
- details:
- email:
- - has already been taken
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- password:
- type: string
- minLength: 6
- example: password123
- password_confirmation:
- type: string
- example: password123
- first_name:
- type: string
- example: John
- last_name:
- type: string
- example: Doe
- phone:
- type: string
- example: "+1234567890"
- accepts_email_marketing:
- type: boolean
- example: true
- metadata:
- type: object
- example:
- source: storefront
- required:
- - email
- - password
- "/api/v3/store/customers/me":
+ "$ref": "#/components/schemas/Cart"
+ "/api/v3/store/orders/{id}":
get:
- summary: Get current customer profile
+ summary: Get an order
tags:
- - Customers
+ - Orders
security:
- api_key: []
bearer_auth: []
- description: Returns the profile of the currently authenticated customer
+ description: Returns a single completed order by prefixed ID. Accessible via
+ JWT (authenticated users) or order token header (guests).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -3993,9 +5564,13 @@ paths:
publishableKey: '<api-key>',
})
- const customer = await client.customer.get({
- token: '<token>',
- })
+ const order = await client.orders.get(
+ 'or_abc123',
+ {},
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
@@ -4004,39 +5579,214 @@ paths:
type: string
- name: Authorization
in: header
+ required: false
+ description: Bearer token for authenticated customers
+ schema:
+ type: string
+ - name: id
+ in: path
required: true
- description: Bearer JWT token
+ description: Order prefixed ID
+ schema:
+ type: string
+ - name: x-spree-token
+ in: header
+ required: false
+ description: Order token for guest access
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (items, fulfillments,
+ payments, discounts, billing_address, shipping_address, gift_card). Use
+ "none" to skip associations.
schema:
type: string
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
+ description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
id is always included.
schema:
type: string
responses:
'200':
- description: profile found
+ description: order found (guest via order token)
content:
application/json:
example:
- id: cust_UkLWZg9DAJ
- first_name: Felix
- last_name: Rowe
- phone: 555-555-0199
- accepts_email_marketing: false
- full_name: Felix Rowe
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses:
- - id: addr_UkLWZg9DAJ
+ id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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.0'
+ display_item_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 222496
+ slug: product-222496
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ name: Thomasine Armstrong
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ additional_tax_total: '0.0'
+ included_tax_total: '0.0'
+ tax_total: '0.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ display_additional_tax_total: "$0.00"
+ display_included_tax_total: "$0.00"
+ display_tax_total: "$0.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ payments: []
+ billing_address:
+ id: addr_UkLWZg9DAJ
label:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 75 Lovely Street
+ address1: 326 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4048,60 +5798,17 @@ paths:
state_code: NY
quick_checkout: false
is_default_billing: false
- is_default_shipping: true
- state_abbr: NY
- country_iso: US
- state_name: New York
- - id: addr_gbHJdmfrXB
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 76 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: true
is_default_shipping: false
state_abbr: NY
country_iso: US
state_name: New York
- default_billing_address:
+ shipping_address:
id: addr_gbHJdmfrXB
label:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 76 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: true
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
- default_shipping_address:
- id: addr_UkLWZg9DAJ
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 75 Lovely Street
+ address1: 327 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4113,32 +5820,43 @@ paths:
state_code: NY
quick_checkout: false
is_default_billing: false
- is_default_shipping: true
+ is_default_shipping: false
state_abbr: NY
country_iso: US
state_name: New York
- newsletter_subscriber:
- customer_groups: []
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
schema:
- "$ref": "#/components/schemas/Customer"
- '401':
- description: unauthorized - invalid token
+ "$ref": "#/components/schemas/Order"
+ '404':
+ description: incomplete order not accessible
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: order_not_found
+ message: Order not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update current customer profile
+ "/api/v3/store/customers/me/addresses":
+ get:
+ summary: List customer addresses
tags:
- Customers
security:
- api_key: []
bearer_auth: []
- description: Updates the profile of the currently authenticated customer
+ description: Returns all addresses in the customer address book
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4150,12 +5868,8 @@ paths:
publishableKey: '<api-key>',
})
- const customer = await client.customer.update(
- {
- first_name: 'John',
- last_name: 'Doe',
- metadata: { preferred_contact: 'email' },
- },
+ const addresses = await client.customer.addresses.list(
+ {},
{
token: '<token>',
},
@@ -4165,34 +5879,42 @@ paths:
in: header
required: true
schema:
- type: string
- - name: Authorization
- in: header
- required: true
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: profile updated
+ description: addresses found
content:
application/json:
example:
- id: cust_UkLWZg9DAJ
- first_name: Updated
- last_name: Name
- phone: 555-555-0199
- accepts_email_marketing: false
- full_name: Updated Name
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- addresses:
+ data:
- id: addr_UkLWZg9DAJ
label:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 77 Lovely Street
+ address1: 144 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4213,29 +5935,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 78 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: true
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
- default_billing_address:
- id: addr_gbHJdmfrXB
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 78 Lovely Street
+ address1: 145 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4251,13 +5951,12 @@ paths:
state_abbr: NY
country_iso: US
state_name: New York
- default_shipping_address:
- id: addr_UkLWZg9DAJ
+ - id: addr_EfhxLZ9ck8
label:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 77 Lovely Street
+ address1: 146 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -4269,129 +5968,47 @@ paths:
state_code: NY
quick_checkout: false
is_default_billing: false
- is_default_shipping: true
+ is_default_shipping: false
state_abbr: NY
country_iso: US
state_name: New York
- newsletter_subscriber:
- customer_groups: []
- schema:
- "$ref": "#/components/schemas/Customer"
- '422':
- description: validation error
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Email can't be blank
- details:
- email:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- first_name:
- type: string
- example: John
- last_name:
- type: string
- example: Doe
- email:
- type: string
- format: email
- password:
- type: string
- example: newpassword123
- password_confirmation:
- type: string
- example: newpassword123
- accepts_email_marketing:
- type: boolean
- example: true
- phone:
- type: string
- example: "+1 555 123 4567"
- metadata:
- type: object
- example:
- preferred_contact: email
- "/api/v3/store/delivery_methods":
- get:
- summary: List delivery methods
- tags:
- - Delivery
- security:
- - api_key: []
- description: Storefront-visible delivery methods. Filter by fulfillment_type
- to discover pickup options.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const { data: pickupMethods } = await client.deliveryMethods.list({
- fulfillment_type: 'pickup',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: fulfillment_type
- in: query
- required: false
- description: 'Filter: shipping, digital, pickup'
- schema:
- type: string
- responses:
- '200':
- description: delivery methods found
- content:
- application/json:
- example:
- data:
- - id: dm_gbHJdmfrXB
- name: Store pickup
- code: PICKUP
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: true
- pickup_point: false
meta:
page: 1
limit: 25
- count: 1
+ count: 3
pages: 1
from: 1
- to: 1
- in: 1
+ to: 3
+ in: 3
previous:
next:
- "/api/v3/store/delivery_methods/{id}/pickup_locations":
- get:
- summary: List pickup locations
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Address"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ post:
+ summary: Create an address
tags:
- - Delivery
+ - Customers
security:
- api_key: []
- description: Pickup-enabled stock locations for a pickup delivery method. Pass
- cart_id to keep only locations that can fulfill the whole cart from local
- stock.
+ bearer_auth: []
+ description: Adds a new address to the customer address book
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4403,102 +6020,152 @@ paths:
publishableKey: '<api-key>',
})
- const { data: pickupLocations } = await client.deliveryMethods.pickupLocations('dm_abc123', {
- cart_id: 'cart_abc123',
- })
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Delivery method prefixed ID
- schema:
- type: string
- - name: cart_id
- in: query
- required: false
- description: Cart prefixed ID for availability filtering
- schema:
- type: string
- responses:
- '200':
- description: pickup locations found
- content:
- application/json:
- example:
- data:
- - id: sloc_UkLWZg9DAJ
- name: Downtown
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- "/api/v3/store/digital_links/{token}":
- get:
- summary: Download a digital product
- tags:
- - Digital Links
- description: |
- Downloads a digital product file using the digital link token.
- The token is provided via the `download_url` field on digital links
- returned with order line items. No API key or authentication required —
- the token itself grants access.
-
- Responds with a redirect to a short-lived download URL; follow it to
- fetch the file. Each download increments the access counter. Downloads
- may be limited by the asset's own settings, falling back to the store's
- (number of downloads and/or time-based expiration).
+ const address = await client.customer.addresses.create(
+ {
+ first_name: 'John',
+ last_name: 'Doe',
+ address1: '123 Main St',
+ city: 'New York',
+ postal_code: '10001',
+ country_code: 'US',
+ state_abbr: 'NY',
+ phone: '+1 555 123 4567',
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- - name: token
- in: path
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
required: true
- description: Digital link token
schema:
type: string
responses:
- '302':
- description: redirect to the file download
- '403':
- description: download link expired or limit exceeded
+ '201':
+ description: address created
content:
application/json:
example:
- error:
- code: digital_link_expired
- message: Download link expired or invalid
+ id: addr_VqXmZF31wY
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 123 Main St
+ address2:
+ postal_code: '10001'
+ city: New York
+ phone: "+1 555 123 4567"
+ 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
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: digital link not found
+ "$ref": "#/components/schemas/Address"
+ '422':
+ description: validation error
content:
application/json:
example:
error:
- code: record_not_found
- message: Digital link not found
+ code: validation_error
+ message: First Name can't be blank, Last Name can't be blank, Address
+ can't be blank, City can't be blank, Country can't be blank, and
+ Zip Code can't be blank
+ details:
+ first_name:
+ - can't be blank
+ last_name:
+ - can't be blank
+ address1:
+ - can't be blank
+ city:
+ - can't be blank
+ country:
+ - can't be blank
+ postal_code:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{cart_id}/discount_codes":
- post:
- summary: Apply discount code
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ first_name:
+ type: string
+ example: John
+ last_name:
+ type: string
+ example: Doe
+ address1:
+ type: string
+ example: 123 Main St
+ address2:
+ type: string
+ example: Apt 4B
+ city:
+ type: string
+ example: New York
+ postal_code:
+ type: string
+ example: '10001'
+ phone:
+ type: string
+ example: "+1 555 123 4567"
+ company:
+ type: string
+ example: Acme Inc
+ country_code:
+ type: string
+ example: US
+ description: ISO 3166-1 alpha-2 country code (e.g., "US", "DE")
+ state_code:
+ type: string
+ example: NY
+ description: ISO 3166-2 subdivision code without country prefix
+ (e.g., "CA", "NY")
+ state_name:
+ type: string
+ example: New York
+ description: State name - for countries without predefined states
+ is_default_billing:
+ type: boolean
+ example: true
+ description: Set as default billing address
+ is_default_shipping:
+ type: boolean
+ example: true
+ description: Set as default shipping address
+ required:
+ - first_name
+ - last_name
+ - address1
+ - city
+ - postal_code
+ - country_code
+ "/api/v3/store/customers/me/addresses/{id}":
+ get:
+ summary: Get an address
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: |
- Applies a promotion discount code to the cart. The code is matched case-insensitively.
-
- For gift cards, use the dedicated `POST /carts/{cart_id}/gift_cards` endpoint instead.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4510,7 +6177,7 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.discountCodes.apply('cart_abc123', 'SAVE10', {
+ const address = await client.customer.addresses.get('addr_abc123', {
token: '<token>',
})
parameters:
@@ -4521,185 +6188,165 @@ paths:
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: cart_id
- in: path
required: true
- description: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: Idempotency-Key
- in: header
- required: false
- description: Unique key for request idempotency.
- schema:
- type: string
- responses:
- '201':
- description: discount code applied
- content:
- application/json:
- example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: 4ryA4ms4Nim9TfxNW4fZi3au
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code: save10
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: "-10.0"
- display_adjustment_total: "-$10.00"
- discount_total: "-10.0"
- display_discount_total: "-$10.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts:
- - id: discount_UkLWZg9DAJ
- promotion_id: promo_UkLWZg9DAJ
- name: Promo
- description:
- code: save10
- amount: "-10.0"
- display_amount: "-$10.00"
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 834241
- slug: product-834241
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '0.0'
- display_total: "$0.00"
- adjustment_total: "-10.0"
- display_adjustment_total: "-$10.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: "-10.0"
- display_discount_total: "-$10.00"
- pre_tax_amount: '0.0'
- display_pre_tax_amount: "$0.00"
- discounted_amount: '0.0'
- display_discounted_amount: "$0.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
+ schema:
+ type: string
+ responses:
+ '200':
+ description: address found
+ content:
+ application/json:
+ example:
+ id: addr_EfhxLZ9ck8
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 158 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
schema:
- "$ref": "#/components/schemas/Cart"
- '422':
- description: invalid discount code
+ "$ref": "#/components/schemas/Address"
+ '404':
+ description: address not found
content:
application/json:
example:
error:
- code: processing_error
- message: The coupon code you entered doesn't exist. Please try again.
+ code: record_not_found
+ message: Address not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update an address
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const address = await client.customer.addresses.update(
+ 'addr_abc123',
+ {
+ city: 'Los Angeles',
+ },
+ {
+ token: '<token>',
+ },
+ )
+ 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: address updated
+ content:
+ application/json:
+ example:
+ id: addr_EfhxLZ9ck8
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 164 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: Los Angeles
+ 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
+ schema:
+ "$ref": "#/components/schemas/Address"
requestBody:
content:
application/json:
schema:
type: object
properties:
- code:
+ first_name:
type: string
- example: SAVE10
- description: Promotion discount code to apply
- required:
- - code
- "/api/v3/store/carts/{cart_id}/discount_codes/{id}":
+ example: John
+ last_name:
+ type: string
+ example: Doe
+ address1:
+ type: string
+ example: 456 Oak Ave
+ city:
+ type: string
+ example: Los Angeles
+ is_default_billing:
+ type: boolean
+ example: true
+ description: Set as default billing address
+ is_default_shipping:
+ type: boolean
+ example: true
+ description: Set as default shipping address
delete:
- summary: Remove discount code
+ summary: Delete an address
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Removes a previously applied discount code from the cart. The ID
- is the discount code string itself.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4711,7 +6358,7 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.discountCodes.remove('cart_abc123', 'SAVE10', {
+ await client.customer.addresses.delete('addr_abc123', {
token: '<token>',
})
parameters:
@@ -4722,170 +6369,37 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: cart_id
- in: path
required: true
- description: Cart prefixed ID
schema:
type: string
- name: id
in: path
required: true
- description: The discount code string to remove (e.g., SAVE10)
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
- description: Order token for guest access
schema:
type: string
responses:
- '200':
- description: discount code removed
- content:
- application/json:
- example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: gvr8TwNVJpxWf27uUHDj5Lj4
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '10.0'
- display_amount_due: "$10.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 853461
- slug: product-853461
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- schema:
- "$ref": "#/components/schemas/Cart"
- '422':
- description: discount code not found on cart
+ '204':
+ description: address deleted
+ '404':
+ description: address not found
content:
application/json:
example:
error:
- code: processing_error
- message: The coupon code you entered doesn't exist. Please try again.
+ code: record_not_found
+ message: Address not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{cart_id}/fulfillments/{id}":
- patch:
- summary: Select delivery rate for fulfillment
+ "/api/v3/store/customers/me/credit_cards":
+ get:
+ summary: List saved credit cards
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Selects a delivery rate for a specific fulfillment and auto-advances
- checkout.
+ description: Returns the authenticated customer's saved credit cards for the
+ current store's payment methods
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -4897,12 +6411,8 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.fulfillments.update(
- 'cart_abc123',
- 'ful_abc123',
- {
- selected_delivery_rate_id: 'dr_abc123',
- },
+ const cards = await client.customer.creditCards.list(
+ {},
{
token: '<token>',
},
@@ -4915,274 +6425,79 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- schema:
- type: string
- - name: cart_id
- in: path
required: true
- description: Cart prefixed ID
schema:
type: string
- - name: id
- in: path
- required: true
- description: Fulfillment ID
+ - name: page
+ in: query
+ required: false
schema:
- type: string
- - name: x-spree-token
- in: header
+ type: integer
+ - name: limit
+ in: query
required: false
- description: Order token for guest access
+ schema:
+ type: integer
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: delivery rate selected, returns updated cart
+ description: credit cards found
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: KLLfFWg9T6dGonBb65hHjaZr
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '20.0'
- display_total: "$20.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '20.0'
- display_amount_due: "$20.00"
- delivery_total: '10.0'
- display_delivery_total: "$10.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: payment
- completed_steps:
- - address
- - delivery
- requirements:
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: false
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 878182
- slug: product-878182
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: cart_UkLWZg9DAJ-F1
- tracking:
- tracking_url:
- pickup_point_data:
- selected_delivery_rate_id: dr_gbHJdmfrXB
- cost: '10.0'
- display_cost: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- status: unfulfilled
- fulfillment_type: shipping
- fulfilled_at:
- delivered_at:
- items:
- - item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- deliveries: []
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- stock_location:
- id: sloc_UkLWZg9DAJ
- name: Monnie O'Keefe
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- delivery_rates:
- - id: dr_gbHJdmfrXB
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- display_additional_tax_total: "$0.00"
- display_included_tax_total: "$0.00"
- display_tax_total: "$0.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- payments: []
- billing_address:
- shipping_address:
- id: addr_EfhxLZ9ck8
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 103 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
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
+ data:
+ - id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Cart"
- '404':
- description: delivery rate not found
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/CreditCard"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: record_not_found
- message: Delivery rate not found
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- selected_delivery_rate_id:
- type: string
- example: dr_abc123
- description: Delivery rate ID to select
- required:
- - selected_delivery_rate_id
- "/api/v3/store/carts/{cart_id}/gift_cards":
- post:
- summary: Apply gift card
+ "/api/v3/store/customers/me/credit_cards/{id}":
+ get:
+ summary: Get a credit card
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: |
- Applies a gift card to the cart. Gift cards are treated as a payment method, not a discount —
- the cart `total` remains unchanged while `amount_due` is reduced.
-
- For promotion discount codes, use the `POST /carts/{cart_id}/discount_codes` endpoint instead.
+ description: Returns a saved credit card by its ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5194,7 +6509,7 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.giftCards.apply('cart_abc123', 'GC-ABCD-1234', {
+ const card = await client.customer.creditCards.get('card_abc123', {
token: '<token>',
})
parameters:
@@ -5205,233 +6520,482 @@ paths:
type: string
- name: Authorization
in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: fields
+ in: query
required: false
- description: Bearer token for authenticated customers
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
- - name: x-spree-token
+ responses:
+ '200':
+ description: credit card found
+ content:
+ application/json:
+ example:
+ id: card_UkLWZg9DAJ
+ brand: visa
+ last4: '1111'
+ month: 12
+ year: 2027
+ name: Spree Commerce
+ default: false
+ gateway_payment_profile_id:
+ schema:
+ "$ref": "#/components/schemas/CreditCard"
+ '404':
+ description: credit card not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Credit card not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ delete:
+ summary: Delete a credit card
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Removes a saved credit card from the customer account
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ await client.customer.creditCards.delete('card_abc123', {
+ token: '<token>',
+ })
+ parameters:
+ - name: x-spree-api-key
in: header
- required: false
- description: Order token for guest access
+ required: true
schema:
type: string
- - name: cart_id
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
in: path
required: true
- description: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: Idempotency-Key
+ responses:
+ '204':
+ description: credit card deleted
+ '404':
+ description: credit card not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Credit card not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customers/me/orders":
+ get:
+ summary: List orders
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns a paginated list of completed orders for the authenticated
+ customer.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const orders = await client.customer.orders.list(
+ {
+ completed_at_gt: '2026-01-01',
+ sort: '-completed_at',
+ },
+ { token: '<token>' },
+ )
+ 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 (default: 1)'
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: 'Number of results per page (default: 25, max: 100)'
+ schema:
+ type: integer
+ - name: sort
+ in: query
+ required: false
+ description: 'Sort order. Prefix with - for descending. Values: completed_at,
+ -completed_at, total, -total, number, -number'
+ schema:
+ type: string
+ - name: q[completed_at_gt]
+ in: query
+ required: false
+ description: Filter by completed after date (ISO 8601)
+ schema:
+ type: string
+ - name: q[completed_at_lt]
+ in: query
+ required: false
+ description: Filter by completed before date (ISO 8601)
+ schema:
+ type: string
+ - name: q[number_eq]
+ in: query
+ required: false
+ description: Filter by exact order number (e.g., R123456)
+ schema:
+ type: string
+ - name: q[state_eq]
+ in: query
+ required: false
+ description: Filter by order state (complete, returned, canceled)
+ schema:
+ type: string
+ - name: q[payment_state_eq]
+ in: query
+ required: false
+ description: Filter by payment state (paid, balance_due, credit_owed, void,
+ failed)
+ schema:
+ type: string
+ - name: q[total_gteq]
+ in: query
+ required: false
+ description: Filter by minimum total
+ schema:
+ type: number
+ - name: q[total_lteq]
+ in: query
+ required: false
+ description: Filter by maximum total
+ schema:
+ type: number
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (items, fulfillments,
+ payments, discounts, billing_address, shipping_address, gift_card). Use
+ "none" to skip associations.
+ schema:
+ type: string
+ - name: fields
+ in: query
required: false
- description: Unique key for request idempotency.
+ description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
+ id is always included.
schema:
type: string
responses:
- '201':
- description: gift card applied
+ '200':
+ description: orders listed
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: nZjAPYSKrNaHf2ZVT6eZfNJV
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '10.0'
- display_gift_card_total: "$10.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '10.0'
- display_store_credit_total: "-$10.00"
- covered_by_store_credit: true
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
+ data:
+ - id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ 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
- name: Product 895702
- slug: product-895702
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
+ locale: en
+ total_quantity: 1
+ coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.0'
+ display_item_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
discount_total: '0.0'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260115120000000000
- number: cart_UkLWZg9DAJ-P1
- status: checkout
- amount: '10.0'
- display_amount: "$10.00"
- source_type: store_credit
- source_id: credit_UkLWZg9DAJ
- source:
- id: credit_UkLWZg9DAJ
- amount: '10.0'
- amount_used: '0.0'
- amount_remaining: '10.0'
- display_amount: "$10.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$10.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 1885270
+ slug: product-1885270
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ name: Macy Goyette
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ additional_tax_total: '0.0'
+ included_tax_total: '0.0'
+ tax_total: '0.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ display_additional_tax_total: "$0.00"
+ display_included_tax_total: "$0.00"
+ display_tax_total: "$0.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ payments: []
+ billing_address:
+ id: addr_EfhxLZ9ck8
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 230 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
+ shipping_address:
+ id: addr_VqXmZF31wY
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 231 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
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
currency: USD
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: store_credit
- session_required: false
- source_required: true
- billing_address:
- shipping_address:
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: store_credit
- session_required: false
- source_required: true
- gift_card:
- id: gc_UkLWZg9DAJ
- code: GIFTCODE1
- status: active
- currency: USD
- amount: '50.0'
- amount_used: '10.0'
- amount_authorized: '0.0'
- amount_remaining: '40.0'
- display_amount: "$50.00"
- display_amount_used: "$10.00"
- display_amount_remaining: "$40.00"
- expires_at:
- redeemed_at:
- expired: false
- active: true
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- schema:
- "$ref": "#/components/schemas/Cart"
- '404':
- description: gift card not found
- content:
- application/json:
- example:
- error:
- code: gift_card_not_found
- message: The Gift Card was not found.
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '422':
- description: gift card already redeemed
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Order"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: gift_card_already_redeemed
- message: The Gift Card has already been redeemed.
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- code:
- type: string
- example: GC-ABCD-1234
- description: Gift card code to apply
- required:
- - code
- "/api/v3/store/carts/{cart_id}/gift_cards/{id}":
- delete:
- summary: Remove gift card
+ "/api/v3/store/customers/me/orders/{id}":
+ get:
+ summary: Get an order
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Removes a previously applied gift card from the cart.
+ description: Returns a single completed order for the authenticated customer.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5443,9 +7007,13 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.giftCards.remove('cart_abc123', 'gc_abc123', {
- token: '<token>',
- })
+ const order = await client.customer.orders.get(
+ 'or_abc123',
+ {},
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
@@ -5454,53 +7022,55 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- description: Bearer token for authenticated customers
- schema:
- type: string
- - name: cart_id
- in: path
required: true
- description: Cart prefixed ID
schema:
type: string
- name: id
in: path
required: true
- description: Gift card prefixed ID (e.g., gc_abc123)
+ description: Order prefixed ID
schema:
type: string
- - name: x-spree-token
- in: header
+ - name: expand
+ in: query
required: false
- description: Order token for guest access
+ description: Comma-separated associations to expand (items, fulfillments,
+ payments, discounts, billing_address, shipping_address, gift_card). Use
+ "none" to skip associations.
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
+ id is always included.
schema:
type: string
responses:
'200':
- description: gift card removed
+ description: order found
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
+ id: or_UkLWZg9DAJ
market_id: mkt_UkLWZg9DAJ
+ cart_id:
channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
company_id:
company_name:
- po_number_required: false
po_document_filename:
po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: Wgq8NrLX3TUQLroJRYWFdQd5
- email:
+ number: R1001
customer_note:
po_number:
currency: USD
locale: en
total_quantity: 1
- warnings: []
coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -5513,38 +7083,19 @@ paths:
display_included_tax_total: "$0.00"
additional_tax_total: '0.0'
display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '10.0'
- display_amount_due: "$10.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
discounts: []
fees: []
items:
@@ -5555,8 +7106,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 939569
- slug: product-939569
+ name: Product 1905633
+ slug: product-1905633
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5579,36 +7130,136 @@ paths:
thumbnail_url:
option_values: []
digital_links: []
- fulfillments: []
- payments:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260115120000000000
- number: cart_UkLWZg9DAJ-P1
- status: invalid
- amount: '10.0'
- display_amount: "$10.00"
- source_type: store_credit
- source_id: credit_UkLWZg9DAJ
- source:
- id: credit_UkLWZg9DAJ
- amount: '10.0'
- amount_used: '0.0'
- amount_remaining: '10.0'
- display_amount: "$10.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$10.00"
- currency: USD
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Store Credit
- description:
- type: store_credit
- session_required: false
- source_required: true
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ name: Sunny Bernier
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ additional_tax_total: '0.0'
+ included_tax_total: '0.0'
+ tax_total: '0.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ display_additional_tax_total: "$0.00"
+ display_included_tax_total: "$0.00"
+ display_tax_total: "$0.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ payments: []
billing_address:
+ id: addr_EfhxLZ9ck8
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 236 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
shipping_address:
- payment_methods: []
+ id: addr_VqXmZF31wY
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 237 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
gift_card:
market:
id: mkt_UkLWZg9DAJ
@@ -5622,16 +7273,25 @@ paths:
supported_locales:
- en
schema:
- "$ref": "#/components/schemas/Cart"
- "/api/v3/store/customers/me/gift_cards":
- get:
- summary: List gift cards
+ "$ref": "#/components/schemas/Order"
+ '404':
+ description: order belongs to another user
+ content:
+ application/json:
+ example:
+ error:
+ code: order_not_found
+ message: Order not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customers":
+ post:
+ summary: Register a new customer
tags:
- Customers
security:
- api_key: []
- bearer_auth: []
- description: Returns all gift cards for the authenticated customer
+ description: Creates a new customer account and returns a JWT token
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5643,100 +7303,112 @@ paths:
publishableKey: '<api-key>',
})
- const giftCards = await client.customer.giftCards.list(
- {},
- {
- token: '<token>',
- },
- )
+ const auth = await client.customers.create({
+ email: '[email protected]',
+ password: 'password123',
+ password_confirmation: 'password123',
+ first_name: 'John',
+ last_name: 'Doe',
+ phone: '+1234567890',
+ accepts_email_marketing: true,
+ metadata: { source: 'storefront' },
+ })
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
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
responses:
- '200':
- description: gift cards found
- content:
- application/json:
- example:
- data:
- - id: gc_UkLWZg9DAJ
- code: 1A288BF2DA45E295
- status: active
- currency: USD
- amount: '10.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '10.0'
- display_amount: "$10.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$10.00"
- expires_at:
- redeemed_at:
- expired: false
- active: true
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ '201':
+ description: registration successful
+ content:
+ application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjY0OWM2NTkzLTBhZWQtNDA5Ny1hYTI3LThhMjVmYTU4OGI3OSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.llCt1j8kVryteixNYywlzA1x8CGqCNBaKiT3-ihDrsE
+ refresh_token: mLm6vdSzLUgPhw8SCzDiagfL
+ user:
+ id: cust_UkLWZg9DAJ
+ first_name: John
+ last_name: Doe
+ phone: "+1234567890"
+ accepts_email_marketing: true
+ full_name: John Doe
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses: []
+ default_billing_address:
+ default_shipping_address:
+ newsletter_subscriber:
+ id: sub_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ verified: true
+ verified_at: '2026-01-15T12:00:00Z'
+ customer_id: cust_UkLWZg9DAJ
+ customer_groups: []
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/GiftCard"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/AuthResponse"
+ '422':
+ description: email already taken
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: validation_error
+ message: Email has already been taken
+ details:
+ email:
+ - has already been taken
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/gift_cards/{id}":
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ password:
+ type: string
+ minLength: 6
+ example: password123
+ password_confirmation:
+ type: string
+ example: password123
+ first_name:
+ type: string
+ example: John
+ last_name:
+ type: string
+ example: Doe
+ phone:
+ type: string
+ example: "+1234567890"
+ accepts_email_marketing:
+ type: boolean
+ example: true
+ metadata:
+ type: object
+ example:
+ source: storefront
+ required:
+ - email
+ - password
+ "/api/v3/store/customers/me":
get:
- summary: Get a gift card
+ summary: Get current customer profile
tags:
- Customers
security:
- api_key: []
bearer_auth: []
- description: Returns a gift card by its ID
+ description: Returns the profile of the currently authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5748,7 +7420,7 @@ paths:
publishableKey: '<api-key>',
})
- const giftCard = await client.customer.giftCards.get('gc_abc123', {
+ const customer = await client.customer.get({
token: '<token>',
})
parameters:
@@ -5760,11 +7432,7 @@ paths:
- name: Authorization
in: header
required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
+ description: Bearer JWT token
schema:
type: string
- name: fields
@@ -5776,47 +7444,128 @@ paths:
type: string
responses:
'200':
- description: gift card found
+ description: profile found
content:
application/json:
example:
- id: gc_UkLWZg9DAJ
- code: B7180B830F0E5992
- status: active
- currency: USD
- amount: '10.0'
- amount_used: '0.0'
- amount_authorized: '0.0'
- amount_remaining: '10.0'
- display_amount: "$10.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$10.00"
- expires_at:
- redeemed_at:
- expired: false
- active: true
+ id: cust_UkLWZg9DAJ
+ first_name: Felix
+ last_name: Rowe
+ phone: 555-555-0199
+ accepts_email_marketing: false
+ full_name: Felix Rowe
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses:
+ - id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 242 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: true
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ - id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 243 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: true
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ default_billing_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 243 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: true
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ default_shipping_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 242 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: true
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ newsletter_subscriber:
+ customer_groups: []
schema:
- "$ref": "#/components/schemas/GiftCard"
- '404':
- description: gift card not found
+ "$ref": "#/components/schemas/Customer"
+ '401':
+ description: unauthorized - invalid token
content:
application/json:
example:
error:
- code: record_not_found
- message: Gift card not found
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{cart_id}/items":
- post:
- summary: Add item to cart
+ patch:
+ summary: Update current customer profile
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Adds a variant to the cart. Creates a new line item or increases
- quantity if variant already in cart.
+ description: Updates the profile of the currently authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -5828,11 +7577,11 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.items.create(
- 'cart_abc123',
+ const customer = await client.customer.update(
{
- variant_id: 'variant_abc123',
- quantity: 2,
+ first_name: 'John',
+ last_name: 'Doe',
+ metadata: { preferred_contact: 'email' },
},
{
token: '<token>',
@@ -5844,210 +7593,128 @@ paths:
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: cart_id
- in: path
- required: true
- description: Cart prefixed ID (e.g., cart_abc123)
- schema:
- type: string
- - name: Idempotency-Key
+ - name: Authorization
in: header
- required: false
- description: Unique key for request idempotency.
+ required: true
schema:
type: string
responses:
- '201':
- description: item added with metadata
- content:
- application/json:
- example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: d12LXVnL3KtzGjXePqRawnPc
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 2
- warnings:
- - code: delivery_unavailable
- message: Product 9663 cannot be delivered to the selected address
- line_item_id: li_UkLWZg9DAJ
- - code: delivery_unavailable
- message: Product 97298 cannot be delivered to the selected address
- line_item_id: li_gbHJdmfrXB
- coupon_code:
- item_total: '29.99'
- display_item_total: "$29.99"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '29.99'
- display_total: "$29.99"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '29.99'
- display_amount_due: "$29.99"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 9663
- slug: product-9663
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- - id: li_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 97298
- slug: product-97298
- options_text: ''
- price: '19.99'
- display_price: "$19.99"
- total: '19.99'
- display_total: "$19.99"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '19.99'
- display_pre_tax_amount: "$19.99"
- discounted_amount: '19.99'
- display_discounted_amount: "$19.99"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- schema:
- "$ref": "#/components/schemas/Cart"
- '404':
- description: variant not found
+ '200':
+ description: profile updated
content:
application/json:
example:
- error:
- code: variant_not_found
- message: Variant not found
+ id: cust_UkLWZg9DAJ
+ first_name: Updated
+ last_name: Name
+ phone: 555-555-0199
+ accepts_email_marketing: false
+ full_name: Updated Name
+ available_store_credit_total: '0'
+ display_available_store_credit_total: "$0.00"
+ addresses:
+ - id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 244 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: true
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ - id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 245 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: true
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ default_billing_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 245 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: true
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ default_shipping_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 244 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: true
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ newsletter_subscriber:
+ customer_groups: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/Customer"
'422':
- description: rejected by a store rule
+ description: validation error
content:
application/json:
example:
error:
code: validation_error
- message: Quantity You can order at most 10 of this item.
+ message: Email can't be blank
details:
- quantity:
- - You can order at most 10 of this item.
+ email:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -6056,31 +7723,41 @@ paths:
schema:
type: object
properties:
- variant_id:
+ first_name:
type: string
- example: variant_abc123
- description: Variant ID to add
- quantity:
- type: integer
- example: 2
- description: 'Quantity to add (default: 1)'
+ example: John
+ last_name:
+ type: string
+ example: Doe
+ email:
+ type: string
+ format: email
+ password:
+ type: string
+ example: newpassword123
+ password_confirmation:
+ type: string
+ example: newpassword123
+ accepts_email_marketing:
+ type: boolean
+ example: true
+ phone:
+ type: string
+ example: "+1 555 123 4567"
metadata:
type: object
- additionalProperties: true
- description: Arbitrary key-value metadata
example:
- gift_message: Happy Birthday!
- required:
- - variant_id
- "/api/v3/store/carts/{cart_id}/items/{id}":
- patch:
- summary: Update line item quantity
+ preferred_contact: email
+ "/api/v3/store/customers/me/gift_cards":
+ get:
+ summary: List gift cards
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Updates the quantity of a line item in the cart
+ description: Returns all gift cards for the authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6092,12 +7769,8 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.items.update(
- 'cart_abc123',
- 'li_abc123',
- {
- quantity: 5,
- },
+ const giftCards = await client.customer.giftCards.list(
+ {},
{
token: '<token>',
},
@@ -6110,176 +7783,86 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- schema:
- type: string
- - name: cart_id
- in: path
required: true
- description: Cart prefixed ID
schema:
type: string
- - name: id
- in: path
- required: true
- description: Line item ID
+ - name: page
+ in: query
+ required: false
schema:
- type: string
- - name: x-spree-token
- in: header
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: fields
+ in: query
required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: quantity change rejected, reported in warnings
+ description: gift cards found
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: Yq5XuZqq7KS7y7n2dMsChnZM
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings:
- - code: purchase_limit_exceeded
- message: Quantity You can order at most 10 of this item.
- variant_id: variant_UkLWZg9DAJ
- item_index: 0
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '10.0'
- display_amount_due: "$10.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 1039165
- slug: product-1039165
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
+ data:
+ - id: gc_UkLWZg9DAJ
+ code: 1A288BF2DA45E295
+ status: active
currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
+ amount: '10.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '10.0'
+ display_amount: "$10.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$10.00"
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Cart"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- quantity:
- type: integer
- minimum: 1
- example: 5
- metadata:
- type: object
- additionalProperties: true
- description: Arbitrary key-value metadata (merged with existing)
- example:
- engraving: J.D.
- delete:
- summary: Remove line item from cart
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/GiftCard"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/customers/me/gift_cards/{id}":
+ get:
+ summary: Get a gift card
tags:
- - Carts
+ - Customers
security:
- api_key: []
bearer_auth: []
- description: Removes a line item from the cart
+ description: Returns a gift card by its ID
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6291,7 +7874,7 @@ paths:
publishableKey: '<api-key>',
})
- const cart = await client.carts.items.delete('cart_abc123', 'li_abc123', {
+ const giftCard = await client.customer.giftCards.get('gc_abc123', {
token: '<token>',
})
parameters:
@@ -6302,13 +7885,7 @@ paths:
type: string
- name: Authorization
in: header
- required: false
- schema:
- type: string
- - name: cart_id
- in: path
required: true
- description: Cart prefixed ID
schema:
type: string
- name: id
@@ -6316,116 +7893,57 @@ paths:
required: true
schema:
type: string
- - name: x-spree-token
- in: header
+ - name: fields
+ in: query
required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: line item removed, returns updated cart
+ description: gift card found
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: arTvbVzmU1krWKLbRnWDZ3cL
- email:
- customer_note:
- po_number:
+ id: gc_UkLWZg9DAJ
+ code: B7180B830F0E5992
+ status: active
currency: USD
- locale: en
- total_quantity: 0
- warnings: []
- coupon_code:
- item_total: '0.0'
- display_item_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '0.0'
- display_total: "$0.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: line_items_required
- step: cart
- field: line_items
- message: Add at least one item to your cart
- - code: email_required
- step: address
- field: email
- message: Email address is required
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
+ amount: '10.0'
+ amount_used: '0.0'
+ amount_authorized: '0.0'
+ amount_remaining: '10.0'
+ display_amount: "$10.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$10.00"
+ expires_at:
+ redeemed_at:
+ expired: false
+ active: true
schema:
- "$ref": "#/components/schemas/Cart"
+ "$ref": "#/components/schemas/GiftCard"
'404':
- description: line item not found
+ description: gift card not found
content:
application/json:
example:
error:
- code: line_item_not_found
- message: Line item not found
+ code: record_not_found
+ message: Gift card not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/locales":
- get:
- summary: List supported locales
+ "/api/v3/store/customers/me/payment_setup_sessions":
+ post:
+ summary: Create payment setup session
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Returns locales supported by the store (derived from markets)
+ bearer_auth: []
+ description: Creates a new payment setup session for saving a payment method
+ for future use. Delegates to the payment gateway to initialize a provider-specific
+ setup flow (e.g. Stripe SetupIntent, Adyen zero-auth tokenization).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6437,63 +7955,187 @@ paths:
publishableKey: '<api-key>',
})
- const locales = await client.locales.list()
+ const session = await client.customer.paymentSetupSessions.create(
+ {
+ payment_method_id: 'pm_abc123',
+ },
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
+ responses:
+ '201':
+ description: payment setup session created
+ content:
+ application/json:
+ example:
+ id: pss_gbHJdmfrXB
+ status: pending
+ external_id: bogus_seti_b0f840e3d99ea3a536ef5be0
+ external_client_secret: bogus_seti_secret_8fa01173ccc21ceb
+ external_data: {}
+ payment_method_id: pm_UkLWZg9DAJ
+ payment_source_id:
+ payment_source_type:
+ customer_id: cust_UkLWZg9DAJ
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Credit Card
+ description:
+ type: bogus
+ session_required: true
+ source_required: true
+ schema:
+ "$ref": "#/components/schemas/PaymentSetupSession"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '404':
+ description: payment method not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Payment method not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ payment_method_id:
+ type: string
+ example: pm_abc123
+ description: Payment method ID
+ external_data:
+ type: object
+ description: Provider-specific data passed to the gateway
+ required:
+ - payment_method_id
+ "/api/v3/store/customers/me/payment_setup_sessions/{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
+ description: Payment setup session ID
+ schema:
+ type: string
+ get:
+ summary: Get payment setup session
+ tags:
+ - Customers
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Returns a payment setup session with its current status and provider
+ data.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const session = await client.customer.paymentSetupSessions.get('pss_abc123', {
+ token: '<token>',
+ })
responses:
'200':
- description: locales found
+ description: payment setup session found
content:
application/json:
example:
- data:
- - code: de
- name: de
- default: false
- rtl: false
- - code: en
- name: English
- default: true
- rtl: false
+ id: pss_UkLWZg9DAJ
+ status: pending
+ external_id: seti_test_469ea499603a54b5a5f4b192
+ external_client_secret: seti_secret_ee50fe0dfcb78f21eabebb03
+ external_data:
+ client_secret: secret_123
+ payment_method_id: pm_UkLWZg9DAJ
+ payment_source_id:
+ payment_source_type:
+ customer_id: cust_UkLWZg9DAJ
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Credit Card
+ description:
+ type: bogus
+ session_required: true
+ source_required: true
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Locale"
- required:
- - data
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/PaymentSetupSession"
+ '404':
+ description: payment setup session not found
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: record_not_found
+ message: Payment setup session not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/markets":
- get:
- summary: List markets
+ "/api/v3/store/customers/me/payment_setup_sessions/{id}/complete":
+ 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: Payment setup session ID
+ schema:
+ type: string
+ patch:
+ summary: Complete payment setup session
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Returns all markets for the current store with their countries,
- currency, locales, and tax configuration.
+ bearer_auth: []
+ description: Completes a payment setup session by confirming the setup with
+ the provider, resulting in a saved payment method.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6505,94 +8147,68 @@ paths:
publishableKey: '<api-key>',
})
- const markets = await client.markets.list()
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
+ const session = await client.customer.paymentSetupSessions.complete(
+ 'pss_abc123',
+ {},
+ {
+ token: '<token>',
+ },
+ )
+ parameters: []
responses:
'200':
- description: markets found
+ description: payment setup session completed
content:
application/json:
example:
- data:
- - id: mkt_UkLWZg9DAJ
- name: North America
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- - es
- countries:
- - iso: US
- iso3: USA
- name: United States
- states_required: true
- zipcode_required: true
- - id: mkt_gbHJdmfrXB
- name: Europe
- currency: EUR
- default_locale: de
- tax_inclusive: true
- default: false
- country_codes:
- - DE
- - FR
- supported_locales:
- - de
- - en
- - fr
- countries:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- - iso: DE
- iso3: DEU
- name: Germany
- states_required: false
- zipcode_required: true
+ id: pss_UkLWZg9DAJ
+ status: completed
+ external_id: seti_test_d9e0e43453e8ba9aff74d4b9
+ external_client_secret: seti_secret_73ff06ddd3b1edb4c9b6db1c
+ external_data:
+ client_secret: secret_123
+ payment_method_id: pm_UkLWZg9DAJ
+ payment_source_id: card_UkLWZg9DAJ
+ payment_source_type: Spree::CreditCard
+ customer_id: cust_UkLWZg9DAJ
+ payment_method:
+ id: pm_UkLWZg9DAJ
+ name: Credit Card
+ description:
+ type: bogus
+ session_required: true
+ source_required: true
schema:
- type: object
- properties:
- data:
- type: array
- required:
- - data
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/PaymentSetupSession"
+ '404':
+ description: payment setup session not found
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: record_not_found
+ message: Payment setup session not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/markets/{id}":
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ external_data:
+ type: object
+ description: Provider-specific completion data
+ "/api/v3/store/customers/me/store_credits":
get:
- summary: Get a market
+ summary: List store credits
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Returns a single market by prefixed ID with its countries, currency,
- locales, and tax configuration.
+ bearer_auth: []
+ description: Returns store credits for the authenticated customer, filtered
+ by current store and currency. Supports Ransack filtering.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6604,78 +8220,92 @@ paths:
publishableKey: '<api-key>',
})
- const market = await client.markets.get('mkt_xxx')
+ const credits = await client.customer.storeCredits.list(
+ {},
+ {
+ token: '<token>',
+ },
+ )
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: id
- in: path
+ - name: Authorization
+ in: header
required: true
- description: Market prefixed ID (e.g., "mkt_k5nR8xLq")
schema:
type: string
+ - name: page
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
+ description: Comma-separated list of fields to include (e.g., amount,currency).
id is always included.
schema:
type: string
responses:
'200':
- description: market found
+ description: store credits found
content:
application/json:
example:
- id: mkt_gbHJdmfrXB
- name: Europe
- currency: EUR
- default_locale: de
- tax_inclusive: true
- default: false
- country_codes:
- - DE
- - FR
- supported_locales:
- - de
- - en
- - fr
- countries:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- - iso: DE
- iso3: DEU
- name: Germany
- states_required: false
- zipcode_required: true
+ data:
+ - id: credit_UkLWZg9DAJ
+ amount: '100.0'
+ amount_used: '0.0'
+ amount_remaining: '100.0'
+ display_amount: "$100.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$100.00"
+ currency: USD
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
type: object
- '404':
- description: market not found
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/StoreCredit"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: record_not_found
- message: Market not found
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/markets/resolve":
+ "/api/v3/store/customers/me/store_credits/{id}":
get:
- summary: Resolve market by country
+ summary: Get a store credit
tags:
- - Markets
+ - Customers
security:
- api_key: []
- description: Determine which market applies for a given country ISO code. Useful
- for auto-selecting the correct currency and locale when a customer's location
- is known.
+ bearer_auth: []
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6687,77 +8317,67 @@ paths:
publishableKey: '<api-key>',
})
- const market = await client.markets.resolve('DE')
+ const credit = await client.customer.storeCredits.get('credit_abc123', {
+ token: '<token>',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: country
- in: query
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "DE", "US")
schema:
type: string
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
+ description: Comma-separated list of fields to include (e.g., amount,currency).
id is always included.
schema:
type: string
responses:
'200':
- description: market resolved
+ description: store credit found
content:
application/json:
example:
- id: mkt_gbHJdmfrXB
- name: Europe
- currency: EUR
- default_locale: de
- tax_inclusive: true
- default: false
- country_codes:
- - DE
- - FR
- supported_locales:
- - de
- - en
- - fr
- countries:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- - iso: DE
- iso3: DEU
- name: Germany
- states_required: false
- zipcode_required: true
+ id: credit_UkLWZg9DAJ
+ amount: '100.0'
+ amount_used: '0.0'
+ amount_remaining: '100.0'
+ display_amount: "$100.00"
+ display_amount_used: "$0.00"
+ display_amount_remaining: "$100.00"
+ currency: USD
schema:
- type: object
+ "$ref": "#/components/schemas/StoreCredit"
'404':
- description: no market for country
+ description: store credit not found
content:
application/json:
example:
error:
code: record_not_found
- message: record not found
+ message: Store credit not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/markets/{market_id}/countries":
+ "/api/v3/store/countries":
get:
- summary: List countries in a market
+ summary: List countries
tags:
- Markets
security:
- api_key: []
- description: Returns countries belonging to a specific market. Use this for
- address form country dropdowns during checkout.
+ description: Returns countries available in the store. Use ?expand=market to
+ include market details (currency, locale, tax_inclusive).
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6769,19 +8389,13 @@ paths:
publishableKey: '<api-key>',
})
- const countries = await client.markets.countries.list('mkt_xxx')
+ const countries = await client.countries.list()
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: market_id
- in: path
- required: true
- description: Market prefixed ID
- schema:
- type: string
- name: fields
in: query
required: false
@@ -6796,32 +8410,44 @@ paths:
application/json:
example:
data:
- - iso: FR
- iso3: FRA
- name: France
- states_required: false
- zipcode_required: true
- iso: DE
iso3: DEU
name: Germany
states_required: false
zipcode_required: true
+ - iso: US
+ iso3: USA
+ name: United States
+ states_required: true
+ zipcode_required: true
schema:
type: object
properties:
data:
type: array
+ items:
+ "$ref": "#/components/schemas/Country"
required:
- data
- "/api/v3/store/markets/{market_id}/countries/{id}":
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/countries/{iso}":
get:
- summary: Get a country in a market
+ summary: Get a country
tags:
- Markets
security:
- api_key: []
- description: Returns a single country by ISO code within a market. Supports
- ?expand=states for address forms.
+ description: Returns a single country by ISO code. Supports ?expand=states for
+ address forms and ?expand=market for market details.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6833,23 +8459,17 @@ paths:
publishableKey: '<api-key>',
})
- const country = await client.markets.countries.get('mkt_xxx', 'DE')
+ const country = await client.countries.get('US')
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: market_id
- in: path
- required: true
- description: Market prefixed ID
- schema:
- type: string
- - name: id
+ - name: iso
in: path
required: true
- description: Country ISO 3166-1 alpha-2 code (e.g., "DE")
+ description: Country ISO 3166-1 alpha-2 code (e.g., "US", "DE")
schema:
type: string
- name: fields
@@ -6872,8 +8492,25 @@ paths:
zipcode_required: true
schema:
type: object
+ properties:
+ iso:
+ type: string
+ iso3:
+ type: string
+ name:
+ type: string
+ states_required:
+ type: boolean
+ zipcode_required:
+ type: boolean
+ required:
+ - iso
+ - iso3
+ - name
+ - states_required
+ - zipcode_required
'404':
- description: country not in market
+ description: country not found
content:
application/json:
example:
@@ -6882,41 +8519,14 @@ paths:
message: record not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/newsletter_subscribers":
- post:
- summary: Subscribe to the newsletter
+ "/api/v3/store/currencies":
+ get:
+ summary: List supported currencies
tags:
- - Newsletter Subscribers
+ - Markets
security:
- api_key: []
- description: |
- Subscribes an email address to the newsletter for the current store.
-
- Behavior:
-
- - If the email is already verified for this store, the existing subscription is returned unchanged.
- - If the request is unauthenticated (guest), the subscription is created in an unverified state
- and two events are published: `newsletter_subscriber.subscription_requested` (carrying the
- `verification_token` and the validated `redirect_url`, intended for headless storefronts that
- want to send the confirmation email themselves via a webhook handler) and the legacy
- `newsletter_subscriber.subscribed` lifecycle event (which the bundled `spree_emails` package
- listens to and uses to send a default confirmation email). The confirmation link should point
- at `redirect_url?token=<verification_token>` and call `POST /newsletter_subscribers/verify`
- when the user clicks it.
- - If the request is authenticated via JWT and the customer's email matches the subscribed email,
- the subscription is auto-verified and no events are fired — the JWT already proves email
- ownership, so no confirmation email is needed.
-
- The optional `redirect_url` is where the verification token should land on the storefront. The
- server does not return a validation error when the URL is outside the store's
- [Allowed Origins](/developer/core-concepts/allowed-origins); instead, the URL is silently
- omitted from the webhook payload (secure-by-default). When no allow-list is configured on the
- store, the URL is also omitted. Callers therefore receive the same 201 regardless, and the
- webhook handler should fall back to the store's storefront URL when `redirect_url` is missing
- from the payload.
-
- Newsletter consent is preserved across registration: if a guest subscribes and later registers
- with the same email, the existing subscriber record is reused.
+ description: Returns currencies supported by the store (derived from markets)
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -6928,85 +8538,63 @@ paths:
publishableKey: '<api-key>',
})
- const subscriber = await client.newsletterSubscribers.create({
- email: '[email protected]',
- redirect_url: 'https://your-store.com/newsletter/confirm',
- })
+ const currencies = await client.currencies.list()
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
+ - name: fields
+ in: query
required: false
- description: Optional Bearer JWT — when present, links the subscription to
- that customer
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
- '201':
- description: auto-verified when JWT matches subscribed email
+ '200':
+ description: currencies found
content:
application/json:
example:
- id: sub_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- verified: true
- verified_at: '2026-01-15T12:00:00Z'
- customer_id: cust_UkLWZg9DAJ
+ data:
+ - iso_code: USD
+ name: United States Dollar
+ symbol: "$"
+ - iso_code: EUR
+ name: Euro
+ symbol: "€"
+ - iso_code: GBP
+ name: British Pound
+ symbol: "£"
schema:
- "$ref": "#/components/schemas/NewsletterSubscriber"
- '422':
- description: invalid email format
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Currency"
+ required:
+ - data
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: validation_error
- message: Email is invalid
- details:
- email:
- - is invalid
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- redirect_url:
- type: string
- format: uri
- example: https://your-store.com/newsletter/confirm
- description: Storefront URL the verification token should be appended
- to. Silently omitted from the webhook payload when the store has
- allowed origins configured and this URL does not match one of
- them, or when no allowed origins are configured at all.
- required:
- - email
- "/api/v3/store/newsletter_subscribers/verify":
- post:
- summary: Verify a newsletter subscription
+ "/api/v3/store/locales":
+ get:
+ summary: List supported locales
tags:
- - Newsletter Subscribers
+ - Markets
security:
- api_key: []
- description: |
- Confirms a pending newsletter subscription using the verification token sent by email.
-
- After successful verification:
- - The subscriber record is marked verified.
- - If the subscription is associated with a customer, that customer's `accepts_email_marketing`
- flag is set to `true`.
+ description: Returns locales supported by the store (derived from markets)
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7018,157 +8606,162 @@ paths:
publishableKey: '<api-key>',
})
- const subscriber = await client.newsletterSubscribers.verify({
- token: 'abc123def456',
- })
+ const locales = await client.locales.list()
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
+ schema:
+ type: string
responses:
'200':
- description: subscription verified
+ description: locales found
content:
application/json:
example:
- id: sub_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- verified: true
- verified_at: '2026-01-15T12:00:00Z'
- customer_id:
+ data:
+ - code: de
+ name: de
+ default: false
+ rtl: false
+ - code: en
+ name: English
+ default: true
+ rtl: false
schema:
- "$ref": "#/components/schemas/NewsletterSubscriber"
- '422':
- description: missing token
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Locale"
+ required:
+ - data
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: parameter_missing
- message: token is required
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- token:
- type: string
- example: abc123def456
- description: Verification token from the confirmation email
- required:
- - token
- "/api/v3/store/newsletter_subscribers/{id}":
- parameters:
- - name: id
- in: path
- description: Newsletter subscriber prefix id (sub_*)
- required: true
- schema:
- type: string
- delete:
- summary: Unsubscribe from the newsletter
+ "/api/v3/store/markets":
+ get:
+ summary: List markets
tags:
- - Newsletter Subscribers
+ - Markets
security:
- api_key: []
- description: |
- Destroys the newsletter subscription, firing the `newsletter_subscriber.deleted`
- lifecycle event. Two authorization paths are accepted:
+ description: Returns all markets for the current store with their countries,
+ currency, locales, and tax configuration.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
- - **Unsubscribe token** in the `?token=` query param — bearer delivered to the
- subscriber by email (the link in an unsubscribe message). The token is
- cryptographically signed and is cross-checked against the `:id` in the URL —
- tampering with either is rejected. To request such an email be sent, call the
- collection action `POST /newsletter_subscribers/request_unsubscribe` with the
- subscriber's email in the body.
- - **JWT bearer** for the logged-in customer who owns the subscription. No `token`
- query param is needed in this path.
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
- All failure modes return a generic `invalid_token` 422.
+ const markets = await client.markets.list()
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: false
- description: Optional Bearer JWT — alternative to the `token` query param
- schema:
- type: string
- - name: token
+ - name: fields
in: query
required: false
- description: Unsubscribe token delivered to the subscriber by email (e.g.
- the link in an unsubscribe message).
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
- '204':
- description: unsubscribed via JWT (owner)
- '422':
- description: JWT-authenticated, subscriber on a different store
+ '200':
+ description: markets found
+ content:
+ application/json:
+ example:
+ data:
+ - id: mkt_UkLWZg9DAJ
+ name: North America
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ - es
+ countries:
+ - iso: US
+ iso3: USA
+ name: United States
+ states_required: true
+ zipcode_required: true
+ - id: mkt_gbHJdmfrXB
+ name: Europe
+ currency: EUR
+ default_locale: de
+ tax_inclusive: true
+ default: false
+ country_codes:
+ - DE
+ - FR
+ supported_locales:
+ - de
+ - en
+ - fr
+ countries:
+ - iso: FR
+ iso3: FRA
+ name: France
+ states_required: false
+ zipcode_required: true
+ - iso: DE
+ iso3: DEU
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ required:
+ - data
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
code: invalid_token
- message: Newsletter unsubscribe token is invalid or has expired.
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/newsletter_subscribers/request_unsubscribe":
- post:
- summary: Request an unsubscribe token
- tags:
- - Newsletter Subscribers
- security:
- - api_key: []
- description: |
- Publishes a `newsletter_subscriber.unsubscribe_requested` event carrying an unsubscribe token in the payload.
- Always returns 202 Accepted to prevent email enumeration.
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- responses:
- '202':
- description: returns accepted even when email is missing
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- redirect_url:
- type: string
- format: uri
- description: Storefront URL the unsubscribe token should be appended
- to in the resulting email. Silently dropped from the event payload
- if outside the store's allowed origins.
- "/api/v3/store/orders/{id}":
+ "/api/v3/store/markets/{id}":
get:
- summary: Get an order
+ summary: Get a market
tags:
- - Orders
+ - Markets
security:
- api_key: []
- bearer_auth: []
- description: Returns a single completed order by prefixed ID. Accessible via
- JWT (authenticated users) or order token header (guests).
+ description: Returns a single market by prefixed ID with its countries, currency,
+ locales, and tax configuration.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7180,301 +8773,78 @@ paths:
publishableKey: '<api-key>',
})
- const order = await client.orders.get(
- 'or_abc123',
- {},
- {
- token: '<token>',
- },
- )
+ const market = await client.markets.get('mkt_xxx')
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: id
in: path
required: true
- description: Order prefixed ID
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
- description: Order token for guest access
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (items, fulfillments,
- payments, discounts, billing_address, shipping_address, gift_card). Use
- "none" to skip associations.
+ description: Market prefixed ID (e.g., "mkt_k5nR8xLq")
schema:
type: string
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
id is always included.
schema:
type: string
responses:
'200':
- description: order found (guest via order token)
+ description: market found
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- 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.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 107496
- slug: product-107496
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- tracking: U10000
- tracking_url:
- pickup_point_data:
- selected_delivery_rate_id: dr_gbHJdmfrXB
- cost: '100.0'
- display_cost: "$100.00"
- total: '100.0'
- display_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- status: unfulfilled
- fulfillment_type: shipping
- fulfilled_at:
- delivered_at:
- items:
- - item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- quantity: 1
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- stock_location:
- id: sloc_UkLWZg9DAJ
- name: Thomasine Armstrong
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- delivery_rates:
- - id: dr_gbHJdmfrXB
- delivery_method_id: dm_UkLWZg9DAJ
- name: UPS Ground
- selected: true
- cost: '10.0'
- total: '10.0'
- additional_tax_total: '0.0'
- included_tax_total: '0.0'
- tax_total: '0.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- display_additional_tax_total: "$0.00"
- display_included_tax_total: "$0.00"
- display_tax_total: "$0.00"
- delivery_method:
- id: dm_UkLWZg9DAJ
- name: UPS Ground
- code: UPS_GROUND
- estimated_transit_business_days_min:
- estimated_transit_business_days_max:
- digital: false
- pickup: false
- pickup_point: false
- payments: []
- billing_address:
- id: addr_UkLWZg9DAJ
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 159 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
- shipping_address:
- id: addr_gbHJdmfrXB
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 160 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
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
+ id: mkt_gbHJdmfrXB
+ name: Europe
+ currency: EUR
+ default_locale: de
+ tax_inclusive: true
+ default: false
+ country_codes:
+ - DE
+ - FR
+ supported_locales:
+ - de
+ - en
+ - fr
+ countries:
+ - iso: FR
+ iso3: FRA
+ name: France
+ states_required: false
+ zipcode_required: true
+ - iso: DE
+ iso3: DEU
+ name: Germany
+ states_required: false
+ zipcode_required: true
schema:
- "$ref": "#/components/schemas/Order"
+ type: object
'404':
- description: incomplete order not accessible
+ description: market not found
content:
application/json:
example:
error:
- code: order_not_found
- message: Order not found
+ code: record_not_found
+ message: Market not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{cart_id}/payment_sessions":
- post:
- summary: Create payment session
+ "/api/v3/store/markets/resolve":
+ get:
+ summary: Resolve market by country
tags:
- - Carts
+ - Markets
security:
- api_key: []
- bearer_auth: []
- description: Creates a new payment session for the cart. Delegates to the payment
- gateway to initialize a provider-specific session (e.g. Stripe PaymentIntent,
- Adyen session, PayPal order).
+ description: Determine which market applies for a given country ISO code. Useful
+ for auto-selecting the correct currency and locale when a customer's location
+ is known.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7486,132 +8856,141 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.carts.paymentSessions.create(
- 'cart_abc123',
- {
- payment_method_id: 'pm_abc123',
- },
- {
- token: '<token>',
- },
- )
+ const market = await client.markets.resolve('DE')
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
+ - name: country
+ in: query
+ required: true
+ description: Country ISO 3166-1 alpha-2 code (e.g., "DE", "US")
+ schema:
+ type: string
+ - name: fields
+ in: query
required: false
- description: Bearer token for authenticated customers
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
- - name: cart_id
- in: path
+ responses:
+ '200':
+ description: market resolved
+ content:
+ application/json:
+ example:
+ id: mkt_gbHJdmfrXB
+ name: Europe
+ currency: EUR
+ default_locale: de
+ tax_inclusive: true
+ default: false
+ country_codes:
+ - DE
+ - FR
+ supported_locales:
+ - de
+ - en
+ - fr
+ countries:
+ - iso: FR
+ iso3: FRA
+ name: France
+ states_required: false
+ zipcode_required: true
+ - iso: DE
+ iso3: DEU
+ name: Germany
+ states_required: false
+ zipcode_required: true
+ schema:
+ type: object
+ '404':
+ description: no market for country
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: record not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/markets/{market_id}/countries":
+ get:
+ summary: List countries in a market
+ tags:
+ - Markets
+ security:
+ - api_key: []
+ description: Returns countries belonging to a specific market. Use this for
+ address form country dropdowns during checkout.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const countries = await client.markets.countries.list('mkt_xxx')
+ parameters:
+ - name: x-spree-api-key
+ in: header
required: true
- description: Cart prefixed ID (e.g., cart_abc123)
schema:
type: string
- - name: x-spree-token
- in: header
- required: false
- description: Order token for guest access
+ - name: market_id
+ in: path
+ required: true
+ description: Market prefixed ID
schema:
type: string
- - name: Idempotency-Key
- in: header
+ - name: fields
+ in: query
required: false
- description: Unique key for request idempotency.
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
- '201':
- description: payment session created
+ '200':
+ description: countries found
content:
application/json:
example:
- id: ps_gbHJdmfrXB
- status: pending
- currency: USD
- external_id: bogus_208a8eb2883f955fd5c07616
- external_data:
- client_secret: bogus_secret_a8b3afe691c933c1
- customer_external_id:
- expires_at:
- amount: '10.0'
- payment_method_id: pm_UkLWZg9DAJ
- order_id: cart_UkLWZg9DAJ
- cart_id: cart_UkLWZg9DAJ
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: bogus
- session_required: true
- source_required: true
+ data:
+ - iso: FR
+ iso3: FRA
+ name: France
+ states_required: false
+ zipcode_required: true
+ - iso: DE
+ iso3: DEU
+ name: Germany
+ states_required: false
+ zipcode_required: true
schema:
- "$ref": "#/components/schemas/PaymentSession"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- payment_method_id:
- type: string
- example: pm_abc123
- description: Payment method ID
- amount:
- type: string
- example: '99.99'
- description: Payment amount (defaults to order total minus store
- credits)
- external_data:
- type: object
- description: Provider-specific data passed to the gateway
- required:
- - payment_method_id
- "/api/v3/store/carts/{cart_id}/payment_sessions/{id}":
- 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: cart_id
- in: path
- required: true
- description: Cart prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Payment session ID
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
- description: Order token for guest access
- schema:
- type: string
+ type: object
+ properties:
+ data:
+ type: array
+ required:
+ - data
+ "/api/v3/store/markets/{market_id}/countries/{id}":
get:
- summary: Get payment session
+ summary: Get a country in a market
tags:
- - Carts
- security:
- - api_key: []
- bearer_auth: []
- description: Returns a single payment session with its current status and provider
- data.
+ - Markets
+ security:
+ - api_key: []
+ description: Returns a single country by ISO code within a market. Supports
+ ?expand=states for address forms.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7623,157 +9002,64 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.carts.paymentSessions.get('cart_abc123', 'ps_abc123', {
- token: '<token>',
- })
+ const country = await client.markets.countries.get('mkt_xxx', 'DE')
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: market_id
+ in: path
+ required: true
+ description: Market prefixed ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Country ISO 3166-1 alpha-2 code (e.g., "DE")
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
+ schema:
+ type: string
responses:
'200':
- description: payment session found
+ description: country found
content:
application/json:
example:
- id: ps_UkLWZg9DAJ
- status: pending
- currency: USD
- external_id: bogus_96d0ebf0a4300304c930f3c0
- external_data:
- client_secret: secret_123
- customer_external_id:
- expires_at:
- amount: '10.0'
- payment_method_id: pm_UkLWZg9DAJ
- order_id: cart_UkLWZg9DAJ
- cart_id: cart_UkLWZg9DAJ
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: bogus
- session_required: true
- source_required: true
+ iso: US
+ iso3: USA
+ name: United States
+ states_required: true
+ zipcode_required: true
schema:
- "$ref": "#/components/schemas/PaymentSession"
+ type: object
'404':
- description: payment session not found
+ description: country not in market
content:
application/json:
example:
error:
code: record_not_found
- message: Payment session not found
+ message: record not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update payment session
- tags:
- - Carts
- security:
- - api_key: []
- bearer_auth: []
- description: Updates a payment session. Delegates to the payment gateway to
- sync changes with the provider.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const session = await client.carts.paymentSessions.update(
- 'cart_abc123',
- 'ps_abc123',
- {
- amount: '50.00',
- },
- {
- token: '<token>',
- },
- )
- parameters: []
- responses:
- '200':
- description: payment session updated
- content:
- application/json:
- example:
- id: ps_UkLWZg9DAJ
- status: pending
- currency: USD
- external_id: bogus_8a53bedc6c12205d0e31f231
- external_data:
- client_secret: secret_123
- customer_external_id:
- expires_at:
- amount: '50.0'
- payment_method_id: pm_UkLWZg9DAJ
- order_id: cart_UkLWZg9DAJ
- cart_id: cart_UkLWZg9DAJ
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: bogus
- session_required: true
- source_required: true
- schema:
- "$ref": "#/components/schemas/PaymentSession"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- amount:
- type: string
- example: '50.00'
- description: Updated payment amount
- external_data:
- type: object
- description: Provider-specific data to update
- "/api/v3/store/carts/{cart_id}/payment_sessions/{id}/complete":
- 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: cart_id
- in: path
- required: true
- description: Cart prefixed ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Payment session ID
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
- description: Order token for guest access
- schema:
- type: string
- patch:
- summary: Complete payment session
+ "/api/v3/store/wishlists":
+ get:
+ summary: List wishlists
tags:
- - Carts
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Completes a payment session by confirming the payment with the
- provider. This triggers payment capture/authorization and order completion.
+ description: Returns all wishlists for the authenticated customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7785,83 +9071,89 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.carts.paymentSessions.complete(
- 'cart_abc123',
- 'ps_abc123',
- {
- session_result: 'success',
- },
+ const wishlists = await client.wishlists.list(
+ {},
{
token: '<token>',
},
)
parameters:
- - name: Idempotency-Key
+ - 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: Unique key for request idempotency.
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ schema:
+ type: integer
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
schema:
type: string
responses:
'200':
- description: payment session completed
+ description: wishlists found
content:
application/json:
example:
- id: ps_UkLWZg9DAJ
- status: completed
- currency: USD
- external_id: bogus_f6de6a6c7dddf8f63c45a3f0
- external_data:
- client_secret: secret_123
- customer_external_id:
- expires_at:
- amount: '10.0'
- payment_method_id: pm_UkLWZg9DAJ
- order_id: cart_UkLWZg9DAJ
- cart_id: cart_UkLWZg9DAJ
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: bogus
- session_required: true
- source_required: true
+ data:
+ - id: wl_UkLWZg9DAJ
+ name: My Wishlist
+ token: Po2FxovL4CYgapsDQCvBKmwP
+ is_default: false
+ is_private: true
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/PaymentSession"
- '404':
- description: payment session not found
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Wishlist"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: record_not_found
- message: Payment session not found
+ code: authentication_required
+ message: Authentication required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- session_result:
- type: string
- description: Provider-specific session result token
- external_data:
- type: object
- description: Provider-specific completion data
- "/api/v3/store/customers/me/payment_setup_sessions":
post:
- summary: Create payment setup session
+ summary: Create a wishlist
tags:
- - Customers
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Creates a new payment setup session for saving a payment method
- for future use. Delegates to the payment gateway to initialize a provider-specific
- setup flow (e.g. Stripe SetupIntent, Adyen zero-auth tokenization).
+ description: Creates a new wishlist for the customer
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7873,9 +9165,10 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.customer.paymentSetupSessions.create(
+ const wishlist = await client.wishlists.create(
{
- payment_method_id: 'pm_abc123',
+ name: 'Birthday Ideas',
+ is_private: true,
},
{
token: '<token>',
@@ -7894,46 +9187,28 @@ paths:
type: string
responses:
'201':
- description: payment setup session created
- content:
- application/json:
- example:
- id: pss_gbHJdmfrXB
- status: pending
- external_id: bogus_seti_b0f840e3d99ea3a536ef5be0
- external_client_secret: bogus_seti_secret_8fa01173ccc21ceb
- external_data: {}
- payment_method_id: pm_UkLWZg9DAJ
- payment_source_id:
- payment_source_type:
- customer_id: cust_UkLWZg9DAJ
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: bogus
- session_required: true
- source_required: true
- schema:
- "$ref": "#/components/schemas/PaymentSetupSession"
- '401':
- description: unauthorized
+ description: wishlist created
content:
application/json:
example:
- error:
- code: authentication_required
- message: Authentication required
+ id: wl_gbHJdmfrXB
+ name: Birthday Ideas
+ token: 9QwEwKPqhv9b6g6vN3mSu4Pm
+ is_default: false
+ is_private: true
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: payment method not found
+ "$ref": "#/components/schemas/Wishlist"
+ '422':
+ description: validation error
content:
application/json:
example:
error:
- code: record_not_found
- message: Payment method not found
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
requestBody:
@@ -7942,42 +9217,25 @@ paths:
schema:
type: object
properties:
- payment_method_id:
+ name:
type: string
- example: pm_abc123
- description: Payment method ID
- external_data:
- type: object
- description: Provider-specific data passed to the gateway
+ example: Birthday Ideas
+ is_private:
+ type: boolean
+ example: true
+ is_default:
+ type: boolean
+ example: false
required:
- - payment_method_id
- "/api/v3/store/customers/me/payment_setup_sessions/{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
- description: Payment setup session ID
- schema:
- type: string
+ - name
+ "/api/v3/store/wishlists/{id}":
get:
- summary: Get payment setup session
+ summary: Get a wishlist
tags:
- - Customers
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Returns a payment setup session with its current status and provider
- data.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -7989,71 +9247,146 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.customer.paymentSetupSessions.get('pss_abc123', {
- token: '<token>',
- })
+ const wishlist = await client.wishlists.get(
+ 'wl_abc123',
+ {
+ expand: ['items.product'],
+ },
+ {
+ token: '<token>',
+ },
+ )
+ 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 (eg items.product to get
+ wishlist items with associated products)
+ schema:
+ type: string
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include (e.g., name,slug,price).
+ id is always included.
+ schema:
+ type: string
responses:
'200':
- description: payment setup session found
+ description: wishlist found
content:
application/json:
example:
- id: pss_UkLWZg9DAJ
- status: pending
- external_id: seti_test_469ea499603a54b5a5f4b192
- external_client_secret: seti_secret_ee50fe0dfcb78f21eabebb03
- external_data:
- client_secret: secret_123
- payment_method_id: pm_UkLWZg9DAJ
- payment_source_id:
- payment_source_type:
- customer_id: cust_UkLWZg9DAJ
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: bogus
- session_required: true
- source_required: true
+ id: wl_UkLWZg9DAJ
+ name: My Wishlist
+ token: MScw7Kpbgn8BpAxVkttfKab8
+ is_default: false
+ is_private: true
schema:
- "$ref": "#/components/schemas/PaymentSetupSession"
+ "$ref": "#/components/schemas/Wishlist"
'404':
- description: payment setup session not found
+ description: wishlist not found
content:
application/json:
example:
error:
code: record_not_found
- message: Payment setup session not found
+ message: Wishlist not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/payment_setup_sessions/{id}/complete":
- 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: Payment setup session ID
- schema:
- type: string
patch:
- summary: Complete payment setup session
+ summary: Update a wishlist
+ tags:
+ - Wishlists
+ security:
+ - api_key: []
+ bearer_auth: []
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const wishlist = await client.wishlists.update(
+ 'wl_abc123',
+ {
+ name: 'Updated Name',
+ },
+ {
+ token: '<token>',
+ },
+ )
+ 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: wishlist updated
+ content:
+ application/json:
+ example:
+ id: wl_UkLWZg9DAJ
+ name: Updated Name
+ token: AMc2ph626mbJo7u5VjvVs9CA
+ is_default: false
+ is_private: true
+ schema:
+ "$ref": "#/components/schemas/Wishlist"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Updated Name
+ is_private:
+ type: boolean
+ example: true
+ is_default:
+ type: boolean
+ example: false
+ delete:
+ summary: Delete a wishlist
tags:
- - Customers
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Completes a payment setup session by confirming the setup with
- the provider, resulting in a saved payment method.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -8065,69 +9398,37 @@ paths:
publishableKey: '<api-key>',
})
- const session = await client.customer.paymentSetupSessions.complete(
- 'pss_abc123',
- {},
- {
- token: '<token>',
- },
- )
- parameters: []
+ await client.wishlists.delete('wl_abc123', {
+ token: '<token>',
+ })
+ 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: payment setup session completed
- content:
- application/json:
- example:
- id: pss_UkLWZg9DAJ
- status: completed
- external_id: seti_test_d9e0e43453e8ba9aff74d4b9
- external_client_secret: seti_secret_73ff06ddd3b1edb4c9b6db1c
- external_data:
- client_secret: secret_123
- payment_method_id: pm_UkLWZg9DAJ
- payment_source_id: card_UkLWZg9DAJ
- payment_source_type: Spree::CreditCard
- customer_id: cust_UkLWZg9DAJ
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Credit Card
- description:
- type: bogus
- session_required: true
- source_required: true
- schema:
- "$ref": "#/components/schemas/PaymentSetupSession"
- '404':
- description: payment setup session not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Payment setup session not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- external_data:
- type: object
- description: Provider-specific completion data
- "/api/v3/store/carts/{cart_id}/payments":
+ '204':
+ description: wishlist deleted
+ "/api/v3/store/wishlists/{wishlist_id}/items":
post:
- summary: Create payment
+ summary: Add item to wishlist
tags:
- - Carts
+ - Wishlists
security:
- api_key: []
bearer_auth: []
- description: Creates a payment for a non-session payment method (e.g. Check,
- Cash on Delivery, Bank Transfer). For payment methods that require a session
- (e.g. Stripe, PayPal), use the payment sessions endpoint instead.
+ description: Adds a variant to the wishlist
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -8139,10 +9440,11 @@ paths:
publishableKey: '<api-key>',
})
- const payment = await client.carts.payments.create(
- 'cart_abc123',
+ const item = await client.wishlists.items.create(
+ 'wl_abc123',
{
- payment_method_id: 'pm_abc123',
+ variant_id: 'variant_abc123',
+ quantity: 1,
},
{
token: '<token>',
@@ -8156,87 +9458,164 @@ paths:
type: string
- name: Authorization
in: header
- required: false
+ required: true
schema:
type: string
- - name: cart_id
+ - name: wishlist_id
in: path
required: true
- description: Cart prefixed ID
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
- description: Order token for guest access
schema:
type: string
responses:
'201':
- description: payment created
- content:
- application/json:
- example:
- id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code:
- number: cart_UkLWZg9DAJ-P1
- status: checkout
- amount: '10.0'
- display_amount: "$10.00"
- source_type:
- source_id:
- source:
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Check
- description:
- type: check
- session_required: false
- source_required: false
- schema:
- "$ref": "#/components/schemas/Payment"
- '422':
- description: session-based payment method
+ description: item added
content:
application/json:
example:
- error:
- code: payment_session_required
- message: This payment method requires a payment session. Use the
- payment sessions endpoint instead.
+ id: wi_gbHJdmfrXB
+ variant_id: variant_gbHJdmfrXB
+ product_id: prod_gbHJdmfrXB
+ wishlist_id: wl_UkLWZg9DAJ
+ quantity: 1
+ variant:
+ id: variant_gbHJdmfrXB
+ product_id: prod_gbHJdmfrXB
+ sku: SKU-343
+ 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:
+ minimum_order_quantity: 1
+ order_multiple: 1
+ purchase_unit: unit
+ units_per_carton:
+ price:
+ id: price_gbHJdmfrXB
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id:
+ option_values: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/WishlistItem"
requestBody:
content:
application/json:
schema:
type: object
properties:
- payment_method_id:
- type: string
- example: pm_abc123
- description: Payment method ID (must be a non-session payment method)
- amount:
+ variant_id:
type: string
- example: '99.99'
- description: Payment amount (defaults to order total minus store
- credits)
- metadata:
- type: object
- description: Arbitrary metadata to attach to the payment
+ example: variant_abc123
+ quantity:
+ type: integer
+ example: 1
required:
- - payment_method_id
- "/api/v3/store/policies":
- get:
- summary: List store policies
+ - variant_id
+ "/api/v3/store/wishlists/{wishlist_id}/items/{id}":
+ delete:
+ summary: Remove item from wishlist
+ tags:
+ - Wishlists
+ security:
+ - api_key: []
+ bearer_auth: []
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ await client.wishlists.items.delete('wl_abc123', 'wi_abc123', {
+ token: '<token>',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: wishlist_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: item removed
+ '404':
+ description: item not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Wishlist item not found
+ "/api/v3/store/newsletter_subscribers":
+ post:
+ summary: Subscribe to the newsletter
tags:
- - Policies
+ - Newsletter Subscribers
security:
- api_key: []
description: |
- Returns all policies for the current store (e.g., return policy, privacy policy, terms of service).
- Policies are managed in Spree Admin and contain rich text content.
+ Subscribes an email address to the newsletter for the current store.
+
+ Behavior:
+
+ - If the email is already verified for this store, the existing subscription is returned unchanged.
+ - If the request is unauthenticated (guest), the subscription is created in an unverified state
+ and two events are published: `newsletter_subscriber.subscription_requested` (carrying the
+ `verification_token` and the validated `redirect_url`, intended for headless storefronts that
+ want to send the confirmation email themselves via a webhook handler) and the legacy
+ `newsletter_subscriber.subscribed` lifecycle event (which the bundled `spree_emails` package
+ listens to and uses to send a default confirmation email). The confirmation link should point
+ at `redirect_url?token=<verification_token>` and call `POST /newsletter_subscribers/verify`
+ when the user clicks it.
+ - If the request is authenticated via JWT and the customer's email matches the subscribed email,
+ the subscription is auto-verified and no events are fired — the JWT already proves email
+ ownership, so no confirmation email is needed.
+
+ The optional `redirect_url` is where the verification token should land on the storefront. The
+ server does not return a validation error when the URL is outside the store's
+ [Allowed Origins](/developer/core-concepts/allowed-origins); instead, the URL is silently
+ omitted from the webhook payload (secure-by-default). When no allow-list is configured on the
+ store, the URL is also omitted. Callers therefore receive the same 201 regardless, and the
+ webhook handler should fall back to the store's storefront URL when `redirect_url` is missing
+ from the payload.
+
+ Newsletter consent is preserved across registration: if a guest subscribes and later registers
+ with the same email, the existing subscriber record is reused.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -8248,101 +9627,85 @@ paths:
publishableKey: '<api-key>',
})
- const policies = await client.policies.list()
+ const subscriber = await client.newsletterSubscribers.create({
+ email: '[email protected]',
+ redirect_url: 'https://your-store.com/newsletter/confirm',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: fields
- in: query
+ - name: Authorization
+ in: header
required: false
- description: Comma-separated list of fields to include (e.g., name,slug).
- id is always included.
+ description: Optional Bearer JWT — when present, links the subscription to
+ that customer
schema:
type: string
responses:
- '200':
- description: policies listed
+ '201':
+ description: auto-verified when JWT matches subscribed email
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'
- - id: pol_OIJLhNcSbf
- name: Privacy Policy
- slug: privacy-policy-f4e5666d-52c2-4d89-aec5-cc55d69c7174
- body: We respect your privacy.
- body_html: We respect your privacy.
- updated_at: '2026-01-15T12:00:00.000Z'
- - id: pol_uw2YK1rnl0
- name: Return Policy
- slug: return-policy
- body: You can return items within 30 days.
- body_html: You can return items within 30 days.
- updated_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'
- - id: pol_VqXmZF31wY
- name: Shipping Policy
- slug: shipping-policy
- body: ''
- body_html: ''
- updated_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'
- meta:
- page: 1
- limit: 25
- count: 6
- pages: 1
- from: 1
- to: 6
- in: 6
- previous:
- next:
+ id: sub_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ verified: true
+ verified_at: '2026-01-15T12:00:00Z'
+ customer_id: cust_UkLWZg9DAJ
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Policy"
- required:
- - data
- '401':
- description: unauthorized
+ "$ref": "#/components/schemas/NewsletterSubscriber"
+ '422':
+ description: invalid email format
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: validation_error
+ message: Email is invalid
+ details:
+ email:
+ - is invalid
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/policies/{id}":
- get:
- summary: Get a policy
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ redirect_url:
+ type: string
+ format: uri
+ example: https://your-store.com/newsletter/confirm
+ description: Storefront URL the verification token should be appended
+ to. Silently omitted from the webhook payload when the store has
+ allowed origins configured and this URL does not match one of
+ them, or when no allowed origins are configured at all.
+ required:
+ - email
+ "/api/v3/store/newsletter_subscribers/verify":
+ post:
+ summary: Verify a newsletter subscription
tags:
- - Policies
+ - Newsletter Subscribers
security:
- api_key: []
- description: Returns a single policy by slug or prefixed ID. Includes the full
- rich text body.
+ description: |
+ Confirms a pending newsletter subscription using the verification token sent by email.
+
+ After successful verification:
+ - The subscriber record is marked verified.
+ - If the subscription is associated with a customer, that customer's `accepts_email_marketing`
+ flag is set to `true`.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -8354,282 +9717,157 @@ paths:
publishableKey: '<api-key>',
})
- const policy = await client.policies.get('return-policy')
+ const subscriber = await client.newsletterSubscribers.verify({
+ token: 'abc123def456',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- description: Policy slug (e.g., return-policy) or prefixed ID (e.g., pol_abc123)
- 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: policy found
+ description: subscription verified
content:
application/json:
example:
- id: pol_uw2YK1rnl0
- name: Return Policy
- slug: return-policy
- body: You can return items within 30 days.
- body_html: You can return items within 30 days.
+ id: sub_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
+ verified: true
+ verified_at: '2026-01-15T12:00:00Z'
+ customer_id:
schema:
- "$ref": "#/components/schemas/Policy"
- '404':
- description: policy not found
+ "$ref": "#/components/schemas/NewsletterSubscriber"
+ '422':
+ description: missing token
content:
application/json:
example:
error:
- code: record_not_found
- message: Policy not found
+ code: parameter_missing
+ message: token is required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/products":
- get:
- summary: List products
- tags:
- - Product Catalog
- security:
- - api_key: []
- description: Returns a paginated list of active products for the current store
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ token:
+ type: string
+ example: abc123def456
+ description: Verification token from the confirmation email
+ required:
+ - token
+ "/api/v3/store/newsletter_subscribers/{id}":
+ parameters:
+ - name: id
+ in: path
+ description: Newsletter subscriber prefix id (sub_*)
+ required: true
+ schema:
+ type: string
+ delete:
+ summary: Unsubscribe from the newsletter
+ tags:
+ - Newsletter Subscribers
+ security:
+ - api_key: []
+ description: |
+ Destroys the newsletter subscription, firing the `newsletter_subscriber.deleted`
+ lifecycle event. Two authorization paths are accepted:
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
+ - **Unsubscribe token** in the `?token=` query param — bearer delivered to the
+ subscriber by email (the link in an unsubscribe message). The token is
+ cryptographically signed and is cross-checked against the `:id` in the URL —
+ tampering with either is rejected. To request such an email be sent, call the
+ collection action `POST /newsletter_subscribers/request_unsubscribe` with the
+ subscriber's email in the body.
+ - **JWT bearer** for the logged-in customer who owns the subscription. No `token`
+ query param is needed in this path.
- const products = await client.products.list({
- page: 1,
- limit: 25,
- sort: 'price',
- name_cont: 'shirt',
- price_gte: 20,
- price_lte: 100,
- with_option_value_ids: ['optval_abc', 'optval_def'],
- expand: ['variants', 'media'],
- })
+ All failure modes return a generic `invalid_token` 422.
parameters:
- name: x-spree-api-key
in: header
required: true
- description: Publishable API key
- schema:
- type: string
- - name: page
- in: query
- required: false
- description: 'Page number (default: 1)'
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: 'Number of items per page (default: 25, max: 100)'
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: 'Sort order. Prefix with - for descending. Values: price, -price,
- best_selling, name, -name, -available_on, available_on'
- schema:
- type: string
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name containing string
- schema:
- type: string
- - name: q[in_category]
- in: query
- required: false
- description: Filter by category prefixed ID (includes descendants)
- schema:
- type: string
- - name: q[in_categories][]
- in: query
- required: false
- description: Filter by multiple category prefixed IDs (OR logic, includes
- descendants)
- schema:
- type: string
- - name: q[price_gte]
- in: query
- required: false
- description: Filter by minimum price
- schema:
- type: number
- - name: q[price_lte]
- in: query
- required: false
- description: Filter by maximum price
- schema:
- type: number
- - name: q[with_option_value_ids][]
- in: query
- required: false
- description: Filter by option value prefix IDs (e.g., optval_abc). Pass multiple
- values for OR logic.
schema:
type: string
- - name: q[in_stock]
- in: query
- required: false
- description: Filter to only in-stock products
- schema:
- type: boolean
- - name: expand
- in: query
+ - name: Authorization
+ in: header
required: false
- description: Comma-separated associations to expand (variants, media, categories,
- option_types, seller, seller.policies)
+ description: Optional Bearer JWT — alternative to the `token` query param
schema:
type: string
- - name: fields
+ - name: token
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ description: Unsubscribe token delivered to the subscriber by email (e.g.
+ the link in an unsubscribe message).
schema:
type: string
responses:
- '200':
- description: products found
- content:
- application/json:
- example:
- data:
- - id: prod_UkLWZg9DAJ
- name: Product 1179085
- slug: product-1179085
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 2
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: A comfortable cotton t-shirt.
- description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id:
- - id: prod_gbHJdmfrXB
- name: Product 1188209
- slug: product-1188209
- 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: Quasi nostrum error iste autem recusandae consequuntur
- consectetur. Dolorem ea officia rerum a. Asperiores et occaecati
- laudantium deserunt modi reiciendis rem. Iste soluta tempora odit
- voluptate cupiditate. Architecto nostrum aliquid est odit minima
- repudiandae. Doloribus quos est in illum. Occaecati vero soluta
- asperiores aliquam odio accusamus incidunt. Officia magnam fugiat
- sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati
- rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.
- description_html: |-
- Quasi nostrum error iste autem recusandae consequuntur consectetur. Dolorem ea officia rerum a. Asperiores et occaecati laudantium deserunt modi reiciendis rem. Iste soluta tempora odit voluptate cupiditate. Architecto nostrum aliquid est odit minima repudiandae.
- Doloribus quos est in illum. Occaecati vero soluta asperiores aliquam odio accusamus incidunt. Officia magnam fugiat sint optio ipsa. Deserunt reiciendis aliquid architecto occaecati rem maxime vero doloremque. Recusandae ipsum natus eius assumenda.
- default_variant_id: variant_EfhxLZ9ck8
- buy_box_variant_id: variant_EfhxLZ9ck8
- thumbnail_url:
- tags: []
- price:
- id: price_EfhxLZ9ck8
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id:
- 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/Product"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- '401':
- description: unauthorized - invalid or missing API key
+ '204':
+ description: unsubscribed via JWT (owner)
+ '422':
+ description: JWT-authenticated, subscriber on a different store
content:
application/json:
example:
error:
code: invalid_token
- message: Valid API key required
+ message: Newsletter unsubscribe token is invalid or has expired.
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/products/{id}":
+ "/api/v3/store/newsletter_subscribers/request_unsubscribe":
+ post:
+ summary: Request an unsubscribe token
+ tags:
+ - Newsletter Subscribers
+ security:
+ - api_key: []
+ description: |
+ Publishes a `newsletter_subscriber.unsubscribe_requested` event carrying an unsubscribe token in the payload.
+ Always returns 202 Accepted to prevent email enumeration.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '202':
+ description: returns accepted even when email is missing
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ redirect_url:
+ type: string
+ format: uri
+ description: Storefront URL the unsubscribe token should be appended
+ to in the resulting email. Silently dropped from the event payload
+ if outside the store's allowed origins.
+ "/api/v3/store/policies":
get:
- summary: Get a product
+ summary: List store policies
tags:
- - Product Catalog
+ - Policies
security:
- api_key: []
- description: Returns a single product by slug or prefix ID
+ description: |
+ Returns all policies for the current store (e.g., return policy, privacy policy, terms of service).
+ Policies are managed in Spree Admin and contain rich text content.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -8641,108 +9879,101 @@ paths:
publishableKey: '<api-key>',
})
- const product = await client.products.get('spree-tote', {
- expand: ['variants', 'media'],
- })
+ const policies = await client.policies.list()
parameters:
- name: x-spree-api-key
in: header
required: true
- description: Publishable API key
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Product slug (e.g., spree-tote) or prefix ID (e.g., product_abc123)
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (variants, media, categories,
- option_types, prior_price, seller, seller.policies). On a marketplace, `seller`
- embeds the seller public profile and `seller.policies` adds their published
- legal documents; `seller_id` is present without either.
schema:
type: string
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
+ description: Comma-separated list of fields to include (e.g., name,slug).
id is always included.
schema:
type: string
responses:
'200':
- description: product without prior_price expanded does not include field
+ description: policies listed
content:
application/json:
example:
- id: prod_UkLWZg9DAJ
- name: Product 1456885
- slug: product-1456885
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 2
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: A comfortable cotton t-shirt.
- description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id:
- prior_price:
- id: _AXs1igzRC6
- amount: '9.99'
- amount_in_cents: 999
- currency: USD
- display_amount: "$9.99"
- recorded_at: '2025-12-31T12:00:00Z'
+ data:
+ - id: pol_gbHJdmfrXB
+ name: Privacy Policy
+ slug: privacy-policy
+ body: ''
+ body_html: ''
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: pol_OIJLhNcSbf
+ name: Privacy Policy
+ slug: privacy-policy-f4e5666d-52c2-4d89-aec5-cc55d69c7174
+ body: We respect your privacy.
+ body_html: We respect your privacy.
+ updated_at: '2026-01-15T12:00:00.000Z'
+ - id: pol_uw2YK1rnl0
+ name: Return Policy
+ slug: return-policy
+ body: You can return items within 30 days.
+ body_html: You can return items within 30 days.
+ updated_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'
+ - id: pol_VqXmZF31wY
+ name: Shipping Policy
+ slug: shipping-policy
+ body: ''
+ body_html: ''
+ updated_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'
+ meta:
+ page: 1
+ limit: 25
+ count: 6
+ pages: 1
+ from: 1
+ to: 6
+ in: 6
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Product"
- '404':
- description: draft product not visible
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Policy"
+ required:
+ - data
+ '401':
+ description: unauthorized
content:
application/json:
example:
error:
- code: record_not_found
- message: Product not found
+ code: invalid_token
+ message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/products/filters":
+ "/api/v3/store/policies/{id}":
get:
- summary: Get product filters
+ summary: Get a policy
tags:
- - Product Catalog
+ - Policies
security:
- api_key: []
- description: |
- Returns available filters for products with their options and counts.
- Use this endpoint to build filter UIs for product listing pages.
-
- The filters are context-aware - when a category_id is provided, only filters
- relevant to products in that category are returned.
+ description: Returns a single policy by slug or prefixed ID. Includes the full
+ rich text body.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -8754,212 +9985,105 @@ paths:
publishableKey: '<api-key>',
})
- const filters = await client.products.filters({
- category_id: 'ctg_abc123',
- })
+ const policy = await client.policies.get('return-policy')
parameters:
- name: x-spree-api-key
in: header
required: true
- description: Publishable API key
schema:
type: string
- - name: category_id
- in: query
- required: false
- description: Scope filters to products in this category (prefix ID)
+ - name: id
+ in: path
+ required: true
+ description: Policy slug (e.g., return-policy) or prefixed ID (e.g., pol_abc123)
schema:
type: string
- - name: q[name_cont]
+ - name: fields
in: query
required: false
- description: Filter by name containing string
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
- description: filters scoped to category
+ description: policy found
content:
application/json:
example:
- id:
- default_sort: manual
- total_count: 2
- filters:
- - id: price
- type: price_range
- min: 19.99
- max: 19.99
- currency: USD
- - id: availability
- type: availability
- options:
- - id: in_stock
- count: 2
- - id: out_of_stock
- count: 0
- - id: opt_UkLWZg9DAJ
- type: option
- name: size
- label: Size
- kind: dropdown
- options:
- - id: optval_UkLWZg9DAJ
- name: small
- label: S
- position: 1
- color_code:
- image_url:
- count: 1
- - id: categories
- type: category
- options:
- - id: ctg_gbHJdmfrXB
- name: Shirts
- permalink: category-11/shirts
- count: 2
- sort_options:
- - id: manual
- label:
- - id: best_selling
- label:
- - id: price
- label:
- - id: "-price"
- label:
- - id: "-available_on"
- label:
- - id: available_on
- label:
- - id: name
- label:
- - id: "-name"
- label:
+ id: pol_uw2YK1rnl0
+ name: Return Policy
+ slug: return-policy
+ body: You can return items within 30 days.
+ body_html: You can return items within 30 days.
+ updated_at: '2026-01-15T12:00:00.000Z'
schema:
- type: object
- properties:
- filters:
- type: array
- description: Available filters (price_range, availability, option,
- category)
- items:
- type: object
- sort_options:
- type: array
- description: Available sort options
- items:
- type: object
- properties:
- id:
- type: string
- required:
- - id
- default_sort:
- type: string
- description: Default sort option ID
- total_count:
- type: integer
- description: Total products matching current filters
- required:
- - filters
- - sort_options
- - default_sort
- - total_count
- '401':
- description: unauthorized - invalid or missing API key
+ "$ref": "#/components/schemas/Policy"
+ '404':
+ description: policy not found
content:
application/json:
example:
error:
- code: invalid_token
- message: Valid API key required
+ code: record_not_found
+ message: Policy not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/sellers":
+ "/api/v3/store/channel":
get:
- summary: List sellers
+ summary: Get the current channel
tags:
- - Sellers
+ - Channel
security:
- api_key: []
- description: |
- Returns the sellers on this marketplace that a shopper can currently
- buy from. A seller still onboarding, suspended, or away on holiday is
- not listed — showing them would advertise a seller whose products
- cannot be bought.
+ description: Returns the channel this request resolved to (key binding → X-Spree-Channel
+ header → store default), including the resolved storefront access posture.
+ Reachable before authentication so gated storefronts can render a sign-in
+ wall.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
- The payload is the seller's public profile only. Nothing about how the
- marketplace runs them — status, payout schedule, tax handling, contact
- addresses — is exposed here.
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const channel = await client.channel.get()
+
+ if (channel.storefront_access === 'login_required') {
+ // render a sign-in wall before any catalog UI
+ }
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (`policies`). A seller's
- policies are their own published legal documents.
- schema:
- type: string
- - name: fields
- in: query
+ - name: X-Spree-Channel
+ in: header
required: false
- description: Comma-separated list of fields to include. id is always included.
+ description: Channel code or prefixed ID to resolve. When the API key is channel-bound,
+ a value naming a different channel is rejected with 422 channel_mismatch;
+ a value matching the bound channel is accepted.
schema:
type: string
responses:
'200':
- description: sellers found
+ description: channel found
content:
application/json:
example:
- data:
- - id: sel_UkLWZg9DAJ
- name: Sparks Audio
- slug: sparks-audio
- about: ''
- about_html: ''
- logo_url:
- square_logo_url:
- cover_photo_url:
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ id: ch_gbHJdmfrXB
+ name: Wholesale
+ code: wholesale
+ active: true
+ default: false
+ storefront_access: login_required
+ guest_checkout: false
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Seller"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
+ "$ref": "#/components/schemas/Channel"
'401':
description: unauthorized
content:
@@ -8970,96 +10094,188 @@ paths:
message: Valid API key required
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/sellers/{id}":
+ "/api/v3/store/account/companies":
get:
- summary: Get a seller
+ summary: List my company memberships
tags:
- - Sellers
+ - Companies
security:
- api_key: []
+ bearer_auth: []
description: |
- Returns a single seller's public profile, by slug or prefixed ID, so a
- storefront can route `/sellers/sparks-audio` without holding an id.
+ Returns the authenticated customer's company memberships, each with the node it
+ is held on and the path of nodes above it. Standing covers the node and every
+ node below it, so a membership on a parent authorizes buying for its divisions.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
- A seller who cannot currently sell returns 404 rather than a profile.
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ // The buyer's memberships, each carrying its node and the path above it.
+ const { data: memberships } = await client.account.companies({ token: '<token>' })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: id
- in: path
+ - name: Authorization
+ in: header
required: true
- description: Seller slug (e.g., sparks-audio) or prefixed ID (e.g., sel_abc123)
schema:
type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (`policies`). A seller's
- policies are their own published legal documents.
+ responses:
+ '200':
+ description: memberships listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: cmem_UkLWZg9DAJ
+ company_id: comp_UkLWZg9DAJ
+ customer_id: cust_UkLWZg9DAJ
+ company:
+ id: comp_UkLWZg9DAJ
+ name: Acme Industrial
+ kind: company
+ po_number_required: false
+ parent_id:
+ ancestors: []
+ '401':
+ description: not authenticated
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ "/api/v3/store/companies/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: Company node ID (comp_...)
+ schema:
+ type: string
+ get:
+ summary: Get a company node
+ tags:
+ - Companies
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |
+ Returns one node of the buyer's organization. Requires standing — a membership on
+ the node or on one of its ancestors; any other node is not found rather than
+ refused, so its existence is not disclosed.
+ x-codeSamples:
+ - lang: javascript
+ label: Spree SDK
+ source: |-
+ import { createClient } from '@spree/sdk'
+
+ const client = createClient({
+ baseUrl: 'https://your-store.com',
+ publishableKey: '<api-key>',
+ })
+
+ const company = await client.companies.get('comp_86Rf07xd4z', { token: '<token>' })
+ parameters:
+ - name: x-spree-api-key
+ 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.
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: seller found by slug
+ description: company found
content:
application/json:
example:
- id: sel_UkLWZg9DAJ
- name: Sparks Audio
- slug: sparks-audio
- about: ''
- about_html: ''
- logo_url:
- square_logo_url:
- cover_photo_url:
- schema:
- "$ref": "#/components/schemas/Seller"
+ id: comp_UkLWZg9DAJ
+ name: Acme Industrial
+ kind: company
+ po_number_required: false
+ parent_id:
+ ancestors: []
'404':
- description: seller not found
+ description: no standing over this node
content:
application/json:
example:
error:
code: record_not_found
- message: Seller not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/store_credits":
+ message: Company not found
+ patch:
+ summary: Update a company node
+ tags:
+ - Companies
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Renames the node. Structure — the parent and the kind — is managed
+ by the merchant, not by buyers.
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: company updated
+ content:
+ application/json:
+ example:
+ id: comp_UkLWZg9DAJ
+ name: Acme Industrial Group
+ kind: company
+ po_number_required: false
+ parent_id:
+ ancestors: []
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Acme Industrial Group
+ "/api/v3/store/companies/{company_id}/members":
+ parameters:
+ - name: company_id
+ in: path
+ required: true
+ description: Company node ID (comp_...)
+ schema:
+ type: string
get:
- summary: List store credits
+ summary: List company members
tags:
- - Customers
+ - Companies
security:
- api_key: []
bearer_auth: []
- description: Returns store credits for the authenticated customer, filtered
- by current store and currency. Supports Ransack filtering.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const credits = await client.customer.storeCredits.list(
- {},
- {
- token: '<token>',
- },
- )
+ description: The people with standing over this node. Within a company every
+ member may read and manage the directory.
parameters:
- name: x-spree-api-key
in: header
@@ -9071,38 +10287,17 @@ paths:
required: true
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., amount,currency).
- id is always included.
- schema:
- type: string
responses:
'200':
- description: store credits found
+ description: members listed
content:
application/json:
example:
data:
- - id: credit_UkLWZg9DAJ
- amount: '100.0'
- amount_used: '0.0'
- amount_remaining: '100.0'
- display_amount: "$100.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$100.00"
- currency: USD
+ - id: cmem_UkLWZg9DAJ
+ company_id: comp_UkLWZg9DAJ
+ customer_id: cust_UkLWZg9DAJ
meta:
page: 1
limit: 25
@@ -9113,33 +10308,17 @@ paths:
in: 1
previous:
next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/StoreCredit"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
- content:
- application/json:
- example:
- error:
- code: authentication_required
- message: Authentication required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/customers/me/store_credits/{id}":
- get:
- summary: Get a store credit
+ post:
+ summary: Add a member by email
tags:
- - Customers
+ - Companies
security:
- api_key: []
bearer_auth: []
+ description: |
+ Adds a person to the node by email. An email that already belongs to a customer of
+ this store becomes a membership immediately (a `cmem_...` id); any other email
+ becomes an invitation (a `cinv_...` id) and the invite email goes out.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -9151,9 +10330,13 @@ paths:
publishableKey: '<api-key>',
})
- const credit = await client.customer.storeCredits.get('credit_abc123', {
- token: '<token>',
- })
+ // An existing customer joins immediately (cmem_…); anyone else is emailed an
+ // invitation (cinv_…).
+ const member = await client.companies.members.create(
+ 'comp_86Rf07xd4z',
+ { customer_email: '[email protected]' },
+ { token: '<token>' },
+ )
parameters:
- name: x-spree-api-key
in: header
@@ -9165,67 +10348,44 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., amount,currency).
- id is always included.
- schema:
- type: string
responses:
- '200':
- description: store credit found
- content:
- application/json:
- example:
- id: credit_UkLWZg9DAJ
- amount: '100.0'
- amount_used: '0.0'
- amount_remaining: '100.0'
- display_amount: "$100.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$100.00"
- currency: USD
- schema:
- "$ref": "#/components/schemas/StoreCredit"
- '404':
- description: store credit not found
+ '201':
+ description: member added or invitation sent
content:
application/json:
example:
- error:
- code: record_not_found
- message: Store credit not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/store/carts/{cart_id}/store_credits":
- post:
- summary: Apply store credit
+ id: cmem_gbHJdmfrXB
+ company_id: comp_UkLWZg9DAJ
+ customer_id: cust_gbHJdmfrXB
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ customer_email:
+ type: string
+ required:
+ - customer_email
+ "/api/v3/store/companies/{company_id}/addresses":
+ parameters:
+ - name: company_id
+ in: path
+ required: true
+ description: Company node ID (comp_...)
+ schema:
+ type: string
+ get:
+ summary: List the company address book
tags:
- - Carts
+ - Companies
security:
- api_key: []
bearer_auth: []
- description: Applies store credit to the cart during checkout.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const cart = await client.carts.storeCredits.apply('cart_abc123', 10.0, {
- token: '<token>',
- })
+ description: The labeled ship-to and bill-to sites this node owns. A node with
+ no default of its own falls back to its nearest ancestor when prefilling checkout.
parameters:
- name: x-spree-api-key
in: header
@@ -9237,214 +10397,194 @@ paths:
required: true
schema:
type: string
- - name: cart_id
- in: path
- required: true
- description: Cart prefixed ID (e.g., cart_abc123)
- schema:
- type: string
- - name: x-spree-token
+ responses:
+ '200':
+ description: addresses listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: addr_EfhxLZ9ck8
+ label: Headquarters
+ first_name:
+ last_name:
+ full_name: ''
+ address1: 203 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
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/store/companies/{company_id}/addresses/{id}":
+ parameters:
+ - name: company_id
+ in: path
+ required: true
+ description: Company node ID (comp_...)
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Address ID (addr_...)
+ schema:
+ type: string
+ patch:
+ summary: Update an address book entry
+ tags:
+ - Companies
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Renames a site or moves the default ship-to or bill-to flag to
+ it. Only one entry per node holds each default.
+ parameters:
+ - name: x-spree-api-key
in: header
- required: false
+ required: true
schema:
type: string
- - name: Idempotency-Key
+ - name: Authorization
in: header
- required: false
- description: Unique key for request idempotency.
+ required: true
schema:
type: string
responses:
'200':
- description: store credit applied
- content:
- application/json:
- example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: acfBZtWemHae74Y3g18LQg1f
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '0.0'
- display_amount_due: "$0.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '10.0'
- display_store_credit_total: "-$10.00"
- covered_by_store_credit: true
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
- currency: USD
- name: Product 1659789
- slug: product-1659789
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments:
- - id: py_UkLWZg9DAJ
- payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260115120000000000
- number: cart_UkLWZg9DAJ-P1
- status: checkout
- amount: '10.0'
- display_amount: "$10.00"
- source_type: store_credit
- source_id: credit_UkLWZg9DAJ
- source:
- id: credit_UkLWZg9DAJ
- amount: '50.0'
- amount_used: '0.0'
- amount_remaining: '50.0'
- display_amount: "$50.00"
- display_amount_used: "$0.00"
- display_amount_remaining: "$50.00"
- currency: USD
- payment_method:
- id: pm_UkLWZg9DAJ
- name: Store Credit
- description: Store Credit
- type: store_credit
- session_required: false
- source_required: true
- billing_address:
- shipping_address:
- payment_methods:
- - id: pm_UkLWZg9DAJ
- name: Store Credit
- description: Store Credit
- type: store_credit
- session_required: false
- source_required: true
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- schema:
- "$ref": "#/components/schemas/Cart"
- '422':
- description: no store credit available
+ description: address book entry updated
content:
application/json:
example:
- error:
- code: processing_error
- message: User does not have any Store Credits available
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ id: addr_EfhxLZ9ck8
+ label: Northern Warehouse
+ first_name:
+ last_name:
+ full_name: ''
+ address1: 206 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: true
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
requestBody:
content:
application/json:
schema:
type: object
properties:
- amount:
- type: number
- example: 10.0
- description: Amount to apply (optional - defaults to max available)
+ label:
+ type: string
+ example: Northern Warehouse
+ default_shipping:
+ type: boolean
+ example: true
delete:
- summary: Remove store credit
+ summary: Remove an address book entry
tags:
- - Carts
+ - Companies
security:
- api_key: []
bearer_auth: []
- description: Removes store credit from the cart.
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const cart = await client.carts.storeCredits.remove('cart_abc123', {
- token: '<token>',
- })
+ description: Takes the site out of the address book. Orders already placed to
+ it keep their own copy of the address.
+ 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: address book entry removed
+ "/api/v3/store/companies/{company_id}/invitations/{id}":
+ parameters:
+ - name: company_id
+ in: path
+ required: true
+ description: Company node ID (comp_...)
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Invitation ID (cinv_...)
+ schema:
+ type: string
+ delete:
+ summary: Revoke an invitation
+ tags:
+ - Companies
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Withdraws a pending invitation, spending its token. Any member
+ with standing over the node may revoke.
+ 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: invitation revoked
+ "/api/v3/store/companies/{company_id}/orders":
+ parameters:
+ - name: company_id
+ in: path
+ required: true
+ description: Company node ID (comp_...)
+ schema:
+ type: string
+ get:
+ summary: List the company purchases
+ tags:
+ - Companies
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: Completed orders placed for this node and every node below it,
+ so a parent sees what its divisions bought.
parameters:
- name: x-spree-api-key
in: header
@@ -9456,242 +10596,306 @@ paths:
required: true
schema:
type: string
- - name: cart_id
- in: path
- required: true
- description: Cart prefixed ID
- schema:
- type: string
- - name: x-spree-token
- in: header
- required: false
- schema:
- type: string
responses:
'200':
- description: store credit removed
+ description: orders listed
content:
application/json:
example:
- id: cart_UkLWZg9DAJ
- market_id: mkt_UkLWZg9DAJ
- channel_id: ch_UkLWZg9DAJ
- preferred_stock_location_id:
- company_id:
- company_name:
- po_number_required: false
- po_document_filename:
- po_document_byte_size:
- number: cart_UkLWZg9DAJ
- token: BHWevnp2PQxC1jSWU3ZFLejT
- email:
- customer_note:
- po_number:
- currency: USD
- locale: en
- total_quantity: 1
- warnings: []
- coupon_code:
- item_total: '10.0'
- display_item_total: "$10.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- total: '10.0'
- display_total: "$10.00"
- gift_card_total: '0.0'
- display_gift_card_total: "$0.00"
- amount_due: '10.0'
- display_amount_due: "$10.00"
- delivery_total: '0.0'
- display_delivery_total: "$0.00"
- fee_total: '0.0'
- display_fee_total: "$0.00"
- store_credit_total: '0.0'
- display_store_credit_total: "$0.00"
- covered_by_store_credit: false
- current_step: address
- completed_steps: []
- requirements:
- - code: email_required
- step: address
- field: email
- message: Email address is required
- - code: delivery_method_required
- step: delivery
- field: delivery_method
- message: Select a delivery method for all fulfillments
- - code: payment_required
- step: payment
- field: payment
- message: Add a payment method
- order_minimum:
- order_minimum_shortfall:
- below_order_minimum: false
- shipping_eq_billing_address: true
- discounts: []
- fees: []
- items:
- - id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- seller_id:
- preorder: false
- preorder_ships_at:
- quantity: 1
+ data:
+ - id: or_UkLWZg9DAJ
+ market_id: mkt_UkLWZg9DAJ
+ cart_id:
+ channel_id: ch_UkLWZg9DAJ
+ company_id: comp_UkLWZg9DAJ
+ company_name: Acme Industrial
+ po_document_filename:
+ po_document_byte_size:
+ number: R1001
+ customer_note:
+ po_number:
currency: USD
- name: Product 167179
- slug: product-167179
- options_text: ''
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
+ locale: en
+ total_quantity: 1
+ coupon_code:
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
+ item_total: '10.0'
+ display_item_total: "$10.00"
adjustment_total: '0.0'
display_adjustment_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
discount_total: '0.0'
display_discount_total: "$0.00"
- pre_tax_amount: '10.0'
- display_pre_tax_amount: "$10.00"
- discounted_amount: '10.0'
- display_discounted_amount: "$10.00"
- display_compare_at_amount: "$0.00"
- compare_at_amount:
- thumbnail_url:
- option_values: []
- digital_links: []
- fulfillments: []
- payments: []
- billing_address:
- shipping_address:
- payment_methods: []
- gift_card:
- market:
- id: mkt_UkLWZg9DAJ
- name: United States
- currency: USD
- default_locale: en
- tax_inclusive: false
- default: true
- country_codes:
- - US
- supported_locales:
- - en
- schema:
- "$ref": "#/components/schemas/Cart"
- "/api/v3/store/wishlists":
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ gift_card_total: '0.0'
+ display_gift_card_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ fee_total: '0.0'
+ display_fee_total: "$0.00"
+ store_credit_total: '0.0'
+ display_store_credit_total: "$0.00"
+ covered_by_store_credit: false
+ discounts: []
+ fees: []
+ items:
+ - id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ seller_id:
+ preorder: false
+ preorder_ships_at:
+ quantity: 1
+ currency: USD
+ name: Product 1875649
+ slug: product-1875649
+ options_text: ''
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ pre_tax_amount: '10.0'
+ display_pre_tax_amount: "$10.00"
+ discounted_amount: '10.0'
+ display_discounted_amount: "$10.00"
+ display_compare_at_amount: "$0.00"
+ compare_at_amount:
+ thumbnail_url:
+ option_values: []
+ digital_links: []
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ tracking: U10000
+ tracking_url:
+ pickup_point_data:
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ cost: '100.0'
+ display_cost: "$100.00"
+ total: '100.0'
+ display_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ status: unfulfilled
+ fulfillment_type: shipping
+ fulfilled_at:
+ delivered_at:
+ items:
+ - item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ quantity: 1
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ stock_location:
+ id: sloc_UkLWZg9DAJ
+ name: Kali Pacocha
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ delivery_method_id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ additional_tax_total: '0.0'
+ included_tax_total: '0.0'
+ tax_total: '0.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ display_additional_tax_total: "$0.00"
+ display_included_tax_total: "$0.00"
+ display_tax_total: "$0.00"
+ delivery_method:
+ id: dm_UkLWZg9DAJ
+ name: UPS Ground
+ code: UPS_GROUND
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: false
+ pickup_point: false
+ payments: []
+ billing_address:
+ id: addr_EfhxLZ9ck8
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 214 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
+ shipping_address:
+ id: addr_VqXmZF31wY
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 215 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
+ gift_card:
+ market:
+ id: mkt_UkLWZg9DAJ
+ name: United States
+ currency: USD
+ default_locale: en
+ tax_inclusive: false
+ default: true
+ country_codes:
+ - US
+ supported_locales:
+ - en
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/store/company_invitations/{token}":
+ parameters:
+ - name: token
+ in: path
+ required: true
+ description: Plaintext invitation token from the invite email
+ schema:
+ type: string
get:
- summary: List wishlists
+ summary: Look up an invitation
tags:
- - Wishlists
+ - Companies
security:
- api_key: []
- bearer_auth: []
- description: Returns all wishlists for the authenticated customer
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const wishlists = await client.wishlists.list(
- {},
- {
- token: '<token>',
- },
- )
+ description: |
+ Shows what is being joined, so the acceptance page can render before the invitee
+ has an account. Deliberately unauthenticated — the token from the email is the
+ credential. Spent, revoked and expired tokens are not found.
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
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
- schema:
- type: string
responses:
'200':
- description: wishlists found
+ description: invitation found
content:
application/json:
example:
- data:
- - id: wl_UkLWZg9DAJ
- name: My Wishlist
- token: Po2FxovL4CYgapsDQCvBKmwP
- is_default: false
- is_private: true
- 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/Wishlist"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- '401':
- description: unauthorized
+ id: cinv_UkLWZg9DAJ
+ expires_at: '2026-02-14T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ status: pending
+ company_name: Acme Industrial
+ store_name: Spree Test Store
+ '404':
+ description: token spent, revoked or expired
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ code: record_not_found
+ message: Company invitation not found
+ "/api/v3/store/company_invitations/{token}/accept":
+ parameters:
+ - name: token
+ in: path
+ required: true
+ description: Plaintext invitation token from the invite email
+ schema:
+ type: string
post:
- summary: Create a wishlist
+ summary: Accept an invitation
tags:
- - Wishlists
+ - Companies
security:
- api_key: []
- bearer_auth: []
- description: Creates a new wishlist for the customer
+ description: |
+ Turns the invitation into a membership. Send a registration payload to create the
+ account — it is always created with the invited email — or call it authenticated as
+ the customer who owns that email to bind the invitation to the existing account.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -9703,77 +10907,56 @@ paths:
publishableKey: '<api-key>',
})
- const wishlist = await client.wishlists.create(
- {
- name: 'Birthday Ideas',
- is_private: true,
- },
- {
- token: '<token>',
- },
- )
- 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: wishlist created
- content:
- application/json:
- example:
- id: wl_gbHJdmfrXB
- name: Birthday Ideas
- token: 9QwEwKPqhv9b6g6vN3mSu4Pm
- is_default: false
- is_private: true
- schema:
- "$ref": "#/components/schemas/Wishlist"
- '422':
- description: validation error
+ // Unauthenticated: the token from the invite email is the credential, and the
+ // registration payload creates the account with the invited address.
+ const membership = await client.companyInvitations.accept('<invitation-token>', {
+ first_name: 'Ada',
+ password: 'a-strong-password',
+ password_confirmation: 'a-strong-password',
+ })
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: membership created
content:
application/json:
example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ id: cmem_UkLWZg9DAJ
+ company_id: comp_UkLWZg9DAJ
+ customer_id: cust_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
+ first_name:
type: string
- example: Birthday Ideas
- is_private:
- type: boolean
- example: true
- is_default:
- type: boolean
- example: false
- required:
- - name
- "/api/v3/store/wishlists/{id}":
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ password:
+ type: string
+ example: a-strong-password
+ password_confirmation:
+ type: string
+ example: a-strong-password
+ "/api/v3/store/delivery_methods":
get:
- summary: Get a wishlist
+ summary: List delivery methods
tags:
- - Wishlists
+ - Delivery
security:
- api_key: []
- bearer_auth: []
+ description: Storefront-visible delivery methods. Filter by fulfillment_type
+ to discover pickup options.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -9785,75 +10968,56 @@ paths:
publishableKey: '<api-key>',
})
- const wishlist = await client.wishlists.get(
- 'wl_abc123',
- {
- expand: ['items.product'],
- },
- {
- token: '<token>',
- },
- )
+ const { data: pickupMethods } = await client.deliveryMethods.list({
+ fulfillment_type: 'pickup',
+ })
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 (eg items.product to get
- wishlist items with associated products)
- schema:
- type: string
- - name: fields
+ - name: fulfillment_type
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,slug,price).
- id is always included.
+ description: 'Filter: shipping, digital, pickup'
schema:
type: string
responses:
'200':
- description: wishlist found
- content:
- application/json:
- example:
- id: wl_UkLWZg9DAJ
- name: My Wishlist
- token: MScw7Kpbgn8BpAxVkttfKab8
- is_default: false
- is_private: true
- schema:
- "$ref": "#/components/schemas/Wishlist"
- '404':
- description: wishlist not found
+ description: delivery methods found
content:
application/json:
example:
- error:
- code: record_not_found
- message: Wishlist not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a wishlist
+ data:
+ - id: dm_gbHJdmfrXB
+ name: Store pickup
+ code: PICKUP
+ estimated_transit_business_days_min:
+ estimated_transit_business_days_max:
+ digital: false
+ pickup: true
+ pickup_point: false
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ "/api/v3/store/delivery_methods/{id}/pickup_locations":
+ get:
+ summary: List pickup locations
tags:
- - Wishlists
+ - Delivery
security:
- api_key: []
- bearer_auth: []
+ description: Pickup-enabled stock locations for a pickup delivery method. Pass
+ cart_id to keep only locations that can fulfill the whole cart from local
+ stock.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -9865,260 +11029,248 @@ paths:
publishableKey: '<api-key>',
})
- const wishlist = await client.wishlists.update(
- 'wl_abc123',
- {
- name: 'Updated Name',
- },
- {
- token: '<token>',
- },
- )
+ const { data: pickupLocations } = await client.deliveryMethods.pickupLocations('dm_abc123', {
+ cart_id: 'cart_abc123',
+ })
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
+ - name: id
+ in: path
required: true
+ description: Delivery method prefixed ID
schema:
type: string
- - name: id
+ - name: cart_id
+ in: query
+ required: false
+ description: Cart prefixed ID for availability filtering
+ schema:
+ type: string
+ responses:
+ '200':
+ description: pickup locations found
+ content:
+ application/json:
+ example:
+ data:
+ - id: sloc_UkLWZg9DAJ
+ name: Downtown
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ "/api/v3/store/digital_links/{token}":
+ get:
+ summary: Download a digital product
+ tags:
+ - Digital Links
+ description: |
+ Downloads a digital product file using the digital link token.
+ The token is provided via the `download_url` field on digital links
+ returned with order line items. No API key or authentication required —
+ the token itself grants access.
+
+ Responds with a redirect to a short-lived download URL; follow it to
+ fetch the file. Each download increments the access counter. Downloads
+ may be limited by the asset's own settings, falling back to the store's
+ (number of downloads and/or time-based expiration).
+ parameters:
+ - name: token
in: path
required: true
+ description: Digital link token
schema:
type: string
responses:
- '200':
- description: wishlist updated
+ '302':
+ description: redirect to the file download
+ '403':
+ description: download link expired or limit exceeded
content:
application/json:
example:
- id: wl_UkLWZg9DAJ
- name: Updated Name
- token: AMc2ph626mbJo7u5VjvVs9CA
- is_default: false
- is_private: true
+ error:
+ code: digital_link_expired
+ message: Download link expired or invalid
schema:
- "$ref": "#/components/schemas/Wishlist"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Updated Name
- is_private:
- type: boolean
- example: true
- is_default:
- type: boolean
- example: false
- delete:
- summary: Delete a wishlist
+ "$ref": "#/components/schemas/ErrorResponse"
+ '404':
+ description: digital link not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Digital link not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/sellers":
+ get:
+ summary: List sellers
tags:
- - Wishlists
- security:
- - api_key: []
- bearer_auth: []
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
+ - Sellers
+ security:
+ - api_key: []
+ description: |
+ Returns the sellers on this marketplace that a shopper can currently
+ buy from. A seller still onboarding, suspended, or away on holiday is
+ not listed — showing them would advertise a seller whose products
+ cannot be bought.
- await client.wishlists.delete('wl_abc123', {
- token: '<token>',
- })
+ The payload is the seller's public profile only. Nothing about how the
+ marketplace runs them — status, payout schedule, tax handling, contact
+ addresses — is exposed here.
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
- required: true
+ - name: page
+ in: query
+ required: false
schema:
- type: string
- - name: id
- in: path
- required: true
+ type: integer
+ - name: limit
+ in: query
+ required: false
schema:
- type: string
- responses:
- '204':
- description: wishlist deleted
- "/api/v3/store/wishlists/{wishlist_id}/items":
- post:
- summary: Add item to wishlist
- tags:
- - Wishlists
- security:
- - api_key: []
- bearer_auth: []
- description: Adds a variant to the wishlist
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
-
- const item = await client.wishlists.items.create(
- 'wl_abc123',
- {
- variant_id: 'variant_abc123',
- quantity: 1,
- },
- {
- token: '<token>',
- },
- )
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ description: Filter by name
schema:
type: string
- - name: Authorization
- in: header
- required: true
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (`policies`). A seller's
+ policies are their own published legal documents.
schema:
type: string
- - name: wishlist_id
- in: path
- required: true
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
- '201':
- description: item added
+ '200':
+ description: sellers found
content:
application/json:
example:
- id: wi_gbHJdmfrXB
- variant_id: variant_gbHJdmfrXB
- product_id: prod_gbHJdmfrXB
- wishlist_id: wl_UkLWZg9DAJ
- quantity: 1
- variant:
- id: variant_gbHJdmfrXB
- product_id: prod_gbHJdmfrXB
- sku: SKU-198
- 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:
- minimum_order_quantity: 1
- order_multiple: 1
- purchase_unit: unit
- units_per_carton:
- price:
- id: price_gbHJdmfrXB
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id:
- option_values: []
+ data:
+ - id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/WishlistItem"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- variant_id:
- type: string
- example: variant_abc123
- quantity:
- type: integer
- example: 1
- required:
- - variant_id
- "/api/v3/store/wishlists/{wishlist_id}/items/{id}":
- delete:
- summary: Remove item from wishlist
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Seller"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: invalid_token
+ message: Valid API key required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/store/sellers/{id}":
+ get:
+ summary: Get a seller
tags:
- - Wishlists
+ - Sellers
security:
- api_key: []
- bearer_auth: []
- x-codeSamples:
- - lang: javascript
- label: Spree SDK
- source: |-
- import { createClient } from '@spree/sdk'
-
- const client = createClient({
- baseUrl: 'https://your-store.com',
- publishableKey: '<api-key>',
- })
+ description: |
+ Returns a single seller's public profile, by slug or prefixed ID, so a
+ storefront can route `/sellers/sparks-audio` without holding an id.
- await client.wishlists.items.delete('wl_abc123', 'wi_abc123', {
- token: '<token>',
- })
+ A seller who cannot currently sell returns 404 rather than a profile.
parameters:
- name: x-spree-api-key
in: header
required: true
schema:
type: string
- - name: Authorization
- in: header
+ - name: id
+ in: path
required: true
+ description: Seller slug (e.g., sparks-audio) or prefixed ID (e.g., sel_abc123)
schema:
type: string
- - name: wishlist_id
- in: path
- required: true
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (`policies`). A seller's
+ policies are their own published legal documents.
schema:
type: string
- - name: id
- in: path
- required: true
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
- '204':
- description: item removed
+ '200':
+ description: seller found by slug
+ content:
+ application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Sparks Audio
+ slug: sparks-audio
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ schema:
+ "$ref": "#/components/schemas/Seller"
'404':
- description: item not found
+ description: seller not found
content:
application/json:
example:
error:
code: record_not_found
- message: Wishlist item not found
+ message: Seller not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
servers:
- url: http://{defaultHost}
variables:
@@ -13382,6 +14534,9 @@ components:
carrier:
type: string
nullable: true
+ carrier_name:
+ type: string
+ nullable: true
service:
type: string
nullable: true
@@ -13410,9 +14565,6 @@ components:
type: string
owner_type:
type: string
- carrier_name:
- type: string
- nullable: true
cost:
type: string
display_cost:
@@ -13430,6 +14582,7 @@ components:
- source
- status
- carrier
+ - carrier_name
- service
- tracking_number
- currency
@@ -13441,7 +14594,6 @@ components:
- updated_at
- owner_id
- owner_type
- - carrier_name
- cost
- display_cost
- integration_id
diff --git a/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts b/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts
deleted file mode 100644
index c7df8b85a2..0000000000
--- a/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts
+++ /dev/null
@@ -1,21 +0,0 @@
-import { createAdminClient } from '@spree/admin-sdk'
-
-const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
-})
-
-// region:example
-// Deprecated: use client.orders.fulfillments.labels.create() instead, which
-// answers with the label itself. Removed in Spree 6.1.
-const fulfillment = await client.orders.fulfillments.purchaseLabel(
- 'or_UkLWZg9DAJ',
- 'ful_UkLWZg9DAJ',
-)
-
-// The label is ready to print; the parcel is still unfulfilled.
-const label = fulfillment.labels[0]
-
-// endregion:example
-
-export { label }
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index de95cc46e1..1f69262e3c 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -1392,21 +1392,6 @@ export class AdminClient {
body: params,
}),
- // Buys the shipping label for a parcel that has not shipped yet, so the
- // merchant prints it and packs before anything tells the customer it
- // shipped. Only providers that produce labels accept this; failures are
- // loud (422), unlike fulfill's degrade-to-no-label path.
- purchaseLabel: (
- orderId: string,
- id: string,
- options?: RequestOptions,
- ): Promise<Fulfillment> =>
- this.request<Fulfillment>(
- 'PATCH',
- `/orders/${orderId}/fulfillments/${id}/purchase_label`,
- options,
- ),
-
// Confirms the customer received the goods. Staff can record this by
// hand — a merchant with no carrier integration still needs a delivered
// state — and carriers reach the same endpoint through their webhooks.
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index 62670ecc95..15dff81221 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/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"}}],"responses":{"200":{"description":"staff found"}}}},"/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"}}},"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"}},"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.\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/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":"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[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"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"}}],"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"}}],"responses":{"200":{"description":"API keys found"}}},"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"},"422":{"description":"validation error"}},"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"}}},"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"}},"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"}}}},"/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"}}}},"/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/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"}}],"responses":{"200":{"description":"catalogs found"}}},"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"},"422":{"description":"invalid request"}},"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"}},"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":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"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"}},"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"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"get":{"summary":"List catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's per-variant quantity terms. The catalog-wide default is a pair of fields on the catalog itself, so these are strictly the overrides.\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"}}],"responses":{"200":{"description":"quantity rules found"}}},"post":{"summary":"Create a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"States how much of one variant a buyer on this agreement must order. Both fields are optional individually, but a rule must state at least one — a field left out falls through to the catalog default, and then to the 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,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"quantity rule created"},"422":{"description":"invalid request"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"variant_id":{"type":"string"},"minimum_order_quantity":{"type":"integer","nullable":true,"description":"The least a buyer may order."},"order_multiple":{"type":"integer","nullable":true,"description":"Orders must land on a multiple of this, counted from the minimum."}},"required":["variant_id"]}}}}}},"/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"}}],"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"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules/{id}":{"patch":{"summary":"Update a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one variant term. A field sent as null hands that field back to the catalog default; a rule must still state at least one of the two.\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":"quantity rule updated"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}}}},"delete":{"summary":"Delete a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drops one variant's exception, so it falls back to the catalog's own default.\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":"quantity rule deleted"}}}},"/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"}},"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}/product_terms":{"get":{"summary":"List catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's quantity terms at the grain a merchant states them: one entry per product, over rows the database keeps per variant. `mixed` marks a product whose variants carry different terms.\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"}}],"responses":{"200":{"description":"product terms found"}}},"put":{"summary":"Set catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' terms in one request, keyed by prefixed product id. 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 — this is the one catalog-term surface that is not a whole-set replacement, because an agreement may name terms for thousands of SKUs.\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":"product terms 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/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":"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"}}],"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"}}],"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"}},"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"}},"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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"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"}},"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},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_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"}}},"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"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_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/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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"claim reasons found"},"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"},"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"},"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"}},"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/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":"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"}}],"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"}}],"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"}},"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"}},"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"}}}},"/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[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"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 preference_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},"preference_schema":{"type":"array","items":{"type":"object"}},"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).","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"}},"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).","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"}},"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"}}}},"/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).","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"}}],"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/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"}}],"responses":{"200":{"description":"coupon codes found"}}}},"/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]=Spree::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":"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":"definitions returned"}}},"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"}},"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 identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::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"}}},"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"}},"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/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. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue 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/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"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"}}],"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}/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"}}],"responses":{"200":{"description":"addresses found"}}},"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"}},"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"}},"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"}}],"responses":{"200":{"description":"credit cards found"}}}},"/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"}}},"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":"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"}}],"responses":{"200":{"description":"store credits found"}}},"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"}},"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"}},"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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"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"}}],"responses":{"200":{"description":"customers found"}}},"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"}},"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"}}},"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"}},"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/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"}}],"responses":{"200":{"description":"delivery profiles found"}}},"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"},"422":{"description":"validation error"}},"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"}},"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"}},"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"}}],"responses":{"200":{"description":"delivery methods found"}}},"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"}},"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":{"type":"string"},"calculator_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"}}}},"/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"}},"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/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"}}],"responses":{"200":{"description":"exports found"}}},"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"}},"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"]},"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.","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"}}},"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":{"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/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[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"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[user_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":"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[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"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"}}],"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 `user_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},"user_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},"user_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"}}}},"/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"}}],"responses":{"200":{"description":"imports found"}}},"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"},"422":{"description":"unknown import type"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_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":{"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"}}},"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":{"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"}},"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"}}}},"/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[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found"}}}},"/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"}}],"responses":{"200":{"description":"integrations found"}}},"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"}},"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"}}}},"/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"}}}},"/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"}}],"responses":{"200":{"description":"invitations found"}}},"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"}},"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/{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"}}}},"/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"}}}},"/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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"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"}}],"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"}}}},"/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/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":"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"}}],"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/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","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 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"}}],"responses":{"200":{"description":"tax lines found"}}}},"/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"}}],"responses":{"200":{"description":"discounts found"}}},"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"},"422":{"description":"invalid discount"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"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"},"422":{"description":"invalid fee"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"order cancellation reasons found"},"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"},"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"},"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"}},"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/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"}}],"responses":{"200":{"description":"rules found"}}},"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"},"422":{"description":"unknown rule type"}},"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"}},"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"}}}},"/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"}}],"responses":{"200":{"description":"deliveries found"}}},"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"},"422":{"description":"tracking number already recorded on this parcel"}},"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"}},"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"}},"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":{"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"}}],"responses":{"200":{"description":"fulfillments found"}}},"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. 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"},"422":{"description":"order not completed"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"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"}}},"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"}},"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"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":{"patch":{"summary":"Buy the shipping label (deprecated)","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deprecated alias of POST /labels, answering with the fulfillment instead of the label. Removed in Spree 6.1.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","deprecated":true,"parameters":[{"name":"x-spree-api-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":"label purchased"},"422":{"description":"provider does not produce labels"}}}},"/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"},"422":{"description":"fulfillment has not shipped"}},"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"}}}},"/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"}},"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/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"}},"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"}}],"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"}},"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}/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"}}],"responses":{"200":{"description":"labels found"}}},"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"},"422":{"description":"provider does not produce labels"}},"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"}}},"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"},"422":{"description":"uploaded labels cannot be refunded"}}}},"/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"}}],"responses":{"200":{"description":"payments found"}}},"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"}},"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"}}}},"/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"},"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"}}}},"/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"}}],"responses":{"200":{"description":"refunds found"}}},"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"}},"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/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":"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[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","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":"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. Alias: user_id (legacy)."},"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\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/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 must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. 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":"Must match an allowed origin 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/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":"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 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 the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\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/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/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","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":"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/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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"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"}}],"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/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\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"}}],"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 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"}},"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"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"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"}}],"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/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":"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"}}],"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/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"}}],"responses":{"200":{"description":"custom fields found"}}},"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"},"422":{"description":"duplicate definition for the same product"}},"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"}}},"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"}},"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"}}}},"/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"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"}},"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"}},"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"}},"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/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"}}],"responses":{"200":{"description":"actions found"}}},"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`). Fully-qualified Ruby class names are also accepted for backward compatibility.\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"},"422":{"description":"unknown action type"}},"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"}}],"responses":{"200":{"description":"rules found"}}},"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`). Fully-qualified Ruby class names are also accepted for backward compatibility.\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"},"422":{"description":"unknown rule type"}},"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"}},"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"}}],"responses":{"200":{"description":"promotions found"}}},"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"}},"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"}}},"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"}},"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"}}}},"/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"}}}},"/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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"refund reasons found"},"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"},"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"},"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"}},"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"return reasons found"},"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"},"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"},"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"}},"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/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"}}],"responses":{"200":{"description":"roles found"}}},"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"},"422":{"description":"invalid request"}},"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"}},"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"}}}},"/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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"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 `preference_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."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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/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."}}}}}}}},"/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/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"},"422":{"description":"row is missing a level"}},"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_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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"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"}}],"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/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[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","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 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/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"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_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":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found"},"422":{"description":"invalid taggable type"}}}},"/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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 `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`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\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, 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"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"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"}}}},"/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"},"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/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"}}}},"/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":"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"}}],"responses":{"200":{"description":"variants found"}}},"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"},"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"},"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"}},"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":"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[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"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"}}],"responses":{"200":{"description":"deliveries found"},"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"},"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"}}}},"/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"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"}}],"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"},"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"},"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"}}}},"/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"}}}}}}}}},"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 class names, e.g. [\"Spree::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"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"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"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"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"]},"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"},"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}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"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"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_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},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_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":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","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","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","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"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"currency":{"type":"string"},"source":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["currency","source","amount","display_amount"],"x-typelizer":true},"CatalogProduct":{"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":{"type":"string"},"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"},"catalog_price":{"allOf":[{"$ref":"#/components/schemas/CatalogPrice"}],"nullable":true}},"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},"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"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","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"},"display_refund_amount":{"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","display_refund_amount","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":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_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},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"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"},"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"},"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"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_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}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_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"},"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"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","label","description"],"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"},"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"},"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},"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"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"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","type","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"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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"},"display_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","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","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},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"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"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"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"},"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},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"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","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","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"},"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"},"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_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string"},"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_type","provider_settings","created_at","updated_at","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"},"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"},"display_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","display_amount","metadata","created_at","updated_at"],"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_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_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":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_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},"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","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"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":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_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","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"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},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"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"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"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","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","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":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_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","display_amount","display_amount_used","display_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":{"type":"string"},"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},"status":{"type":"string"},"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},"preferred_delimiter":{"type":"string"},"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","preferred_delimiter","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"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"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","acceptance_url","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"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"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},"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","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","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"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"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"},"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},"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"},"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},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","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"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"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},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_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"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"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"},"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},"canceler_id":{"type":"string","nullable":true},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"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"},"approver":{"$ref":"#/components/schemas/AdminUser"},"canceler":{"$ref":"#/components/schemas/AdminUser"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","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","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","canceler_id","cancel_reason_id","cancel_reason_name","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"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":{"type":"object"},"preference_schema":{"type":"object"}},"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","preference_schema"],"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":{"type":"string"},"amount":{"type":"string"},"display_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"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_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},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"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},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"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","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"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_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"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"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","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","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":{"type":"string"},"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":{"type":"string"},"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"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"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","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"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","preference_schema","label","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},"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"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"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"},"display_pre_tax_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"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_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":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_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},"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"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"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},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"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"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"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"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"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"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string"},"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":{"type":"string"},"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":{"type":"string"},"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"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"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}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"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"},"status":{"type":"string"},"carrier":{"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"},"carrier_name":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","carrier_name","cost","display_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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","created_at","updated_at","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":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"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","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},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"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}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id"],"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},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"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},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"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","preferred_storefront_url","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"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":{"type":"string"},"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"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"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"},"rate":{"type":"string"},"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},"amount":{"type":"string"},"display_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"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"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},"amount":{"type":"string"},"amount_percentage":{"type":"number","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","amount","amount_percentage","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},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true},"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_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"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},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","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","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","hs_code","country_of_origin","customs_description","deleted_at","created_at","updated_at","preorderable","tax_category_id","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"},"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}}}}
\ 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 must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. 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":"Must match an allowed origin 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."}}}}}}}},"/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":"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[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"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"}}],"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"}}],"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":"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"}}],"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"}}],"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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"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},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_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"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_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"}}],"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]=Spree::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":"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":"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 identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"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"}}],"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}/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"}}],"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"}}],"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":"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"}}],"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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"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"}}],"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/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"}}],"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"]},"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.","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"}}],"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. 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"},"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[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"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[user_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":"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[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"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"}}],"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 `user_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},"user_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},"user_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"}}],"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"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_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[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"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"}}],"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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","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 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"}}],"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"}}],"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":"number"},"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":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"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"}}],"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":"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[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","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":"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. Alias: user_id (legacy)."},"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\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":"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 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 the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\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"}}],"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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"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"}}],"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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"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"}}],"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"}}],"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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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"}}],"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"}}],"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`). Fully-qualified Ruby class names are also accepted for backward compatibility.\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"}}],"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`). Fully-qualified Ruby class names are also accepted for backward compatibility.\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"}}],"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"}}],"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"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_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":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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 `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`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\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, 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"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"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"}}],"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.\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"}}],"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/{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"}}],"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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"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"}}],"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/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":"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"}}],"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":"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[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"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"}}],"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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"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"}}],"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/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"}}],"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":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"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}/quantity_rules":{"get":{"summary":"List catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's per-variant quantity terms. The catalog-wide default is a pair of fields on the catalog itself, so these are strictly the overrides.\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"}}],"responses":{"200":{"description":"quantity rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"States how much of one variant a buyer on this agreement must order. Both fields are optional individually, but a rule must state at least one — a field left out falls through to the catalog default, and then to the 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,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"quantity rule created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"variant_id":{"type":"string"},"minimum_order_quantity":{"type":"integer","nullable":true,"description":"The least a buyer may order."},"order_multiple":{"type":"integer","nullable":true,"description":"Orders must land on a multiple of this, counted from the minimum."}},"required":["variant_id"]}}}}}},"/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"}}],"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}/quantity_rules/{id}":{"patch":{"summary":"Update a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one variant term. A field sent as null hands that field back to the catalog default; a rule must still state at least one of the two.\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":"quantity rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}}}},"delete":{"summary":"Delete a catalog quantity rule","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drops one variant's exception, so it falls back to the catalog's own default.\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":"quantity rule deleted"}}}},"/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}/product_terms":{"get":{"summary":"List catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's quantity terms at the grain a merchant states them: one entry per product, over rows the database keeps per variant. `mixed` marks a product whose variants carry different terms.\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"}}],"responses":{"200":{"description":"product terms found","content":{"application/json":{}}}}},"put":{"summary":"Set catalog terms by product","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' terms in one request, keyed by prefixed product id. 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 — this is the one catalog-term surface that is not a whole-set replacement, because an agreement may name terms for thousands of SKUs.\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":"product terms set","content":{"application/json":{}}}},"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":"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"}}],"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"}}],"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[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"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 preference_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},"preference_schema":{"type":"array","items":{"type":"object"}},"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).","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).","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).","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"}}],"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. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue 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"}}],"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"}}],"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":{"type":"string"},"calculator_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"}}],"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":"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"}}],"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"}}],"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"}}],"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/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\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"}}],"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 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":"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"}}],"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/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":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"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 `preference_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."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/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":"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[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"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/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[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","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 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"}}}}}}}},"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 class names, e.g. [\"Spree::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"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"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"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"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"]},"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"},"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}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"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"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_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},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_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":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","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","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","order_minimum","order_minimum_shortfall","below_order_minimum","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"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"currency":{"type":"string"},"source":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["currency","source","amount","display_amount"],"x-typelizer":true},"CatalogProduct":{"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":{"type":"string"},"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"},"catalog_price":{"allOf":[{"$ref":"#/components/schemas/CatalogPrice"}],"nullable":true}},"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},"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"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","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"},"display_refund_amount":{"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","display_refund_amount","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":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_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},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"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"},"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"},"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"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_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}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_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"},"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"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","label","description"],"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"},"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"},"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},"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"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"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","type","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"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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"},"display_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","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","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},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"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"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"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"},"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},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"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","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","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"},"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"},"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_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string"},"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_type","provider_settings","created_at","updated_at","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"},"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"},"display_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","display_amount","metadata","created_at","updated_at"],"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_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_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":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_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},"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","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"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":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_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","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"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},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"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"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"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","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","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":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_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","display_amount","display_amount_used","display_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":{"type":"string"},"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},"status":{"type":"string"},"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},"preferred_delimiter":{"type":"string"},"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","preferred_delimiter","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"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"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","acceptance_url","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"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"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},"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","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","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"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"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"},"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},"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"},"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},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","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"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"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},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_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"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"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"},"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},"canceler_id":{"type":"string","nullable":true},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"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"},"approver":{"$ref":"#/components/schemas/AdminUser"},"canceler":{"$ref":"#/components/schemas/AdminUser"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","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","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","canceler_id","cancel_reason_id","cancel_reason_name","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"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":{"type":"object"},"preference_schema":{"type":"object"}},"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","preference_schema"],"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":{"type":"string"},"amount":{"type":"string"},"display_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"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_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},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"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},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"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","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"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_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"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"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","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","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":{"type":"string"},"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":{"type":"string"},"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"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"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","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"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","preference_schema","label","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},"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"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"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"},"display_pre_tax_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"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_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":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_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},"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"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"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},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"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"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"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"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"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"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string"},"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":{"type":"string"},"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":{"type":"string"},"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"},"status":{"type":"string"},"currency":{"type":"string"},"provider":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"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}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"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"},"status":{"type":"string"},"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"},"cost":{"type":"string"},"display_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","display_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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","created_at","updated_at","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":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"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","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},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"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}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id"],"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},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"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},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_tax_using_ship_address":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"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","preferred_storefront_url","default_currency","default_locale","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"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":{"type":"string"},"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"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"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"},"rate":{"type":"string"},"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},"amount":{"type":"string"},"display_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"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"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},"amount":{"type":"string"},"amount_percentage":{"type":"number","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","amount","amount_percentage","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},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true},"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_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"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},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","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","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","hs_code","country_of_origin","customs_description","deleted_at","created_at","updated_at","preorderable","tax_category_id","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"},"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}}}}
\ No newline at end of file
diff --git a/packages/dashboard-ui/src/ui/badge.tsx b/packages/dashboard-ui/src/ui/badge.tsx
index 03c5454afd..aaca60354d 100644
--- a/packages/dashboard-ui/src/ui/badge.tsx
+++ b/packages/dashboard-ui/src/ui/badge.tsx
@@ -1,5 +1,5 @@
import { cva, type VariantProps } from 'class-variance-authority'
-import * as React from 'react'
+import type * as React from 'react'
import { useTranslation } from 'react-i18next'
import { cn } from '../lib/utils'
import { Slot } from './slot'
@@ -102,6 +102,15 @@ const statusToneMap: Record<string, StatusTone> = {
confirm: 'neutral',
resumed: 'neutral',
partial: 'info',
+ // What a carrier reports about a consignment in flight. `pending` and
+ // `delivered` are already above — they mean the same thing here.
+ pre_transit: 'info',
+ in_transit: 'info',
+ out_for_delivery: 'info',
+ available_for_pickup: 'warning',
+ return_to_sender: 'destructive',
+ failure: 'destructive',
+ unknown: 'neutral',
archived: 'neutral',
returned: 'success',
backorder: 'warning',
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-deliveries.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-deliveries.tsx
index 45c82f897b..3968ebf747 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillment-deliveries.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-deliveries.tsx
@@ -1,16 +1,19 @@
import type { Delivery } from '@spree/admin-sdk'
-import { Badge, Button, CardContent, useConfirm } from '@spree/dashboard-ui'
-import { PackageCheckIcon, PencilIcon, TrashIcon } from 'lucide-react'
+import {
+ Button,
+ CardContent,
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuSeparator,
+ DropdownMenuTrigger,
+ StatusBadge,
+ useConfirm,
+} from '@spree/dashboard-ui'
+import { EllipsisVerticalIcon, PackageCheckIcon, PencilIcon, TrashIcon } from 'lucide-react'
import { useTranslation } from 'react-i18next'
import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
-/** How far along the carrier says each consignment is. */
-const STATUS_VARIANT: Record<string, 'secondary' | 'default' | 'destructive'> = {
- delivered: 'default',
- failure: 'destructive',
- return_to_sender: 'destructive',
-}
-
/**
* The tracked consignments of one parcel. A parcel usually has one, but three
* boxes or a freight PRO number covering a pallet are the same shape, and each
@@ -21,13 +24,11 @@ export function FulfillmentDeliveries({
fulfillmentId,
deliveries,
onEdit,
- canMarkDelivered,
}: {
orderId: string
fulfillmentId: string
deliveries: Delivery[]
onEdit: (delivery: Delivery) => void
- canMarkDelivered: boolean
}) {
const { t } = useTranslation()
const confirm = useConfirm()
@@ -55,60 +56,66 @@ export function FulfillmentDeliveries({
) : (
<span className="truncate">{delivery.tracking_number}</span>
)}
- <Badge variant={STATUS_VARIANT[delivery.status] ?? 'secondary'}>
- {t(`admin.orders.detail.fulfillments.carrier_status_${delivery.status}`)}
- </Badge>
+ <StatusBadge
+ status={delivery.status}
+ label={t(`admin.orders.detail.fulfillments.carrier_status_${delivery.status}`)}
+ />
</div>
- <div className="flex items-center gap-1">
- {canMarkDelivered && delivery.status !== 'delivered' && (
- <Button
- type="button"
- size="icon-xs"
- variant="ghost"
- disabled={markDeliveryDelivered.isPending}
- onClick={() =>
- markDeliveryDelivered.mutate({ fulfillmentId, deliveryId: delivery.id })
- }
- >
- <PackageCheckIcon className="size-4" />
- <span className="sr-only">
- {t('admin.orders.detail.fulfillments.mark_delivery_delivered')}
- </span>
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button variant="ghost" size="icon-xs">
+ <EllipsisVerticalIcon className="size-4" />
+ <span className="sr-only">{t('admin.actions.actions_menu')}</span>
</Button>
- )}
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ {delivery.status !== 'delivered' && (
+ <DropdownMenuItem
+ disabled={markDeliveryDelivered.isPending}
+ onClick={() =>
+ markDeliveryDelivered.mutate({ fulfillmentId, deliveryId: delivery.id })
+ }
+ >
+ <PackageCheckIcon className="size-4" />
+ {t('admin.orders.detail.fulfillments.mark_delivery_delivered')}
+ </DropdownMenuItem>
+ )}
- <Button type="button" size="icon-xs" variant="ghost" onClick={() => onEdit(delivery)}>
- <PencilIcon className="size-4" />
- <span className="sr-only">{t('admin.actions.edit')}</span>
- </Button>
+ <DropdownMenuItem onClick={() => onEdit(delivery)}>
+ <PencilIcon className="size-4" />
+ {t('admin.actions.edit')}
+ </DropdownMenuItem>
- {/* A consignment a label minted is not removable on its own — the
- label is the record of what was bought, so the way out is
- refunding it. The server refuses too; this keeps the button
- honest. */}
- {!delivery.shipping_label_id && (
- <Button
- type="button"
- size="icon-xs"
- variant="ghost"
- onClick={async () => {
- if (
- await confirm({
- message: t('admin.orders.detail.fulfillments.confirm_delete_delivery'),
- variant: 'destructive',
- confirmLabel: t('admin.actions.delete'),
- })
- ) {
- deleteDelivery.mutate({ fulfillmentId, deliveryId: delivery.id })
- }
- }}
- >
- <TrashIcon className="size-4" />
- <span className="sr-only">{t('admin.actions.delete')}</span>
- </Button>
- )}
- </div>
+ {/* Two consignments are not removable: one a label minted, since
+ the label is the record of what was bought and refunding it
+ is the way out; and one that arrived, since its arrival is
+ what the returns window counts from. The server refuses
+ both; this keeps the menu honest. */}
+ {!delivery.shipping_label_id && delivery.status !== 'delivered' && (
+ <>
+ <DropdownMenuSeparator />
+ <DropdownMenuItem
+ variant="destructive"
+ onClick={async () => {
+ if (
+ await confirm({
+ message: t('admin.orders.detail.fulfillments.confirm_delete_delivery'),
+ variant: 'destructive',
+ confirmLabel: t('admin.actions.delete'),
+ })
+ ) {
+ deleteDelivery.mutate({ fulfillmentId, deliveryId: delivery.id })
+ }
+ }}
+ >
+ <TrashIcon className="size-4" />
+ {t('admin.actions.delete')}
+ </DropdownMenuItem>
+ </>
+ )}
+ </DropdownMenuContent>
+ </DropdownMenu>
</div>
))}
</CardContent>
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-delivery-dialog.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-delivery-dialog.tsx
index f4b4eeec12..1dd46bc8f2 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillment-delivery-dialog.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-delivery-dialog.tsx
@@ -3,6 +3,15 @@ import type { Delivery } from '@spree/admin-sdk'
import { mapSpreeErrorsToForm } from '@spree/dashboard-core'
import {
Button,
+ Combobox,
+ ComboboxButtonTrigger,
+ ComboboxContent,
+ ComboboxEmpty,
+ ComboboxItem,
+ ComboboxList,
+ ComboboxSearch,
+ ComboboxTriggerPlaceholder,
+ ComboboxValue,
Dialog,
DialogBody,
DialogContent,
@@ -15,7 +24,7 @@ import {
FieldLabel,
Input,
} from '@spree/dashboard-ui'
-import { useForm } from 'react-hook-form'
+import { Controller, useForm } from 'react-hook-form'
import { useTranslation } from 'react-i18next'
import { z } from 'zod'
import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
@@ -26,7 +35,6 @@ const deliverySchema = z.object({
// Free text: a forwarder's own name is as valid as a registered carrier,
// and an empty value asks the server to detect one from the number.
carrier: z.string(),
- tracking_url: z.string(),
})
type DeliveryFormValues = z.infer<typeof deliverySchema>
@@ -53,20 +61,23 @@ export function FulfillmentDeliveryDialog({
const { createDelivery, updateDelivery } = useFulfillmentActions(orderId)
const { data: carriersData } = useTrackingCarriers(open)
- // The datalist suggests display names, but what is stored and submitted is
- // the registry key — seeding the field with the name would rewrite a known
- // carrier to its own label on the next save.
+ // The picker offers what the registry knows, but the value stored is the
+ // carrier's key — seeding it with the display name would rewrite a known
+ // carrier to its own label on the next save. Anything not on the list is
+ // still typeable, because a forwarder's own name has to be enterable.
const carrierOptions = (carriersData?.data ?? []).map((carrier) => ({
value: carrier.id,
label: carrier.name,
}))
+ const carrierLabel = (value: string) =>
+ carrierOptions.find((option) => option.value === value)?.label ?? value
+
const form = useForm<DeliveryFormValues>({
resolver: zodResolver(deliverySchema),
defaultValues: {
tracking_number: delivery?.tracking_number ?? '',
carrier: delivery?.carrier ?? '',
- tracking_url: delivery?.tracking_url ?? '',
},
})
@@ -76,24 +87,21 @@ export function FulfillmentDeliveryDialog({
try {
const tracking_number = values.tracking_number.trim()
const carrier = values.carrier.trim()
- const tracking_url = values.tracking_url.trim()
if (delivery) {
- // Sent even when empty: clearing the carrier is how a merchant asks
+ // Carrier is sent even when empty: clearing it is how a merchant asks
// for it to be detected from the number again.
await updateDelivery.mutateAsync({
fulfillmentId,
deliveryId: delivery.id,
tracking_number,
carrier,
- tracking_url,
})
} else {
await createDelivery.mutateAsync({
fulfillmentId,
tracking_number,
carrier: carrier || undefined,
- tracking_url: tracking_url || undefined,
})
}
onOpenChange(false)
@@ -124,7 +132,7 @@ export function FulfillmentDeliveryDialog({
</DialogDescription>
</DialogHeader>
- <DialogBody>
+ <DialogBody className="flex flex-col gap-4">
{form.formState.errors.root?.message && (
<p className="text-sm text-destructive" role="alert">
{form.formState.errors.root.message}
@@ -149,35 +157,43 @@ export function FulfillmentDeliveryDialog({
<FieldLabel htmlFor="delivery-carrier">
{t('admin.orders.detail.fulfillments.carrier_label')}
</FieldLabel>
- {/* Free text with the registered carriers as suggestions: a
- forwarder's own name has to be enterable, and an empty
- value asks the server to detect one from the number. */}
- <Input
- id="delivery-carrier"
- list="delivery-carrier-options"
- placeholder={t('admin.orders.detail.fulfillments.carrier_auto')}
- {...form.register('carrier')}
+ <Controller
+ control={form.control}
+ name="carrier"
+ render={({ field }) => (
+ <Combobox
+ items={carrierOptions.map((option) => option.value)}
+ value={field.value}
+ onValueChange={(value: string | null) => field.onChange(value ?? '')}
+ itemToStringLabel={carrierLabel}
+ >
+ <ComboboxButtonTrigger id="delivery-carrier" onBlur={field.onBlur}>
+ {field.value ? (
+ <ComboboxValue />
+ ) : (
+ <ComboboxTriggerPlaceholder>
+ {t('admin.orders.detail.fulfillments.carrier_auto')}
+ </ComboboxTriggerPlaceholder>
+ )}
+ </ComboboxButtonTrigger>
+ <ComboboxContent>
+ <ComboboxSearch
+ placeholder={t('admin.orders.detail.fulfillments.carrier_search')}
+ />
+ <ComboboxEmpty>{t('admin.common.no_results')}</ComboboxEmpty>
+ <ComboboxList>
+ {(value: string) => (
+ <ComboboxItem key={value} value={value}>
+ {carrierLabel(value)}
+ </ComboboxItem>
+ )}
+ </ComboboxList>
+ </ComboboxContent>
+ </Combobox>
+ )}
/>
- <datalist id="delivery-carrier-options">
- {carrierOptions.map((option) => (
- <option key={option.value} value={option.value} label={option.label} />
- ))}
- </datalist>
</Field>
</div>
-
- <Field>
- <FieldLabel htmlFor="delivery-tracking-url">
- {t('admin.orders.detail.fulfillments.tracking_url_label')}
- </FieldLabel>
- <Input
- id="delivery-tracking-url"
- placeholder={t('admin.orders.detail.fulfillments.tracking_url_placeholder')}
- aria-invalid={!!form.formState.errors.tracking_url}
- {...form.register('tracking_url')}
- />
- <FieldError errors={[form.formState.errors.tracking_url]} />
- </Field>
</DialogBody>
<DialogFooter>
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx
index dadc048842..1a2e8d5988 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-label-upload-dialog.tsx
@@ -110,7 +110,7 @@ export function FulfillmentLabelUploadDialog({
</DialogDescription>
</DialogHeader>
- <DialogBody>
+ <DialogBody className="flex flex-col gap-4">
{form.formState.errors.root?.message && (
<p className="text-sm text-destructive" role="alert">
{form.formState.errors.root.message}
diff --git a/packages/dashboard/src/components/spree/orders/fulfillment-label.tsx b/packages/dashboard/src/components/spree/orders/fulfillment-label.tsx
index e4ba935b30..ae6776b8ed 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillment-label.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillment-label.tsx
@@ -1,7 +1,16 @@
import type { ShippingLabel } from '@spree/admin-sdk'
import { downloadFromApi, getApiClient, useAuth } from '@spree/dashboard-core'
-import { Badge, Button, CardContent, useConfirm } from '@spree/dashboard-ui'
-import { PrinterIcon, ReceiptIcon, TrashIcon } from 'lucide-react'
+import {
+ Badge,
+ Button,
+ CardContent,
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+ useConfirm,
+} from '@spree/dashboard-ui'
+import { EllipsisVerticalIcon, PrinterIcon, ReceiptIcon, TrashIcon } from 'lucide-react'
import { useTranslation } from 'react-i18next'
import { useFulfillmentActions } from '../../../hooks/use-fulfillments'
@@ -94,25 +103,33 @@ export function FulfillmentLabel({
)}
{deletable && (
- <Button
- type="button"
- size="icon-xs"
- variant="ghost"
- onClick={async () => {
- if (
- await confirm({
- message: t('admin.orders.detail.fulfillments.confirm_delete_label'),
- variant: 'destructive',
- confirmLabel: t('admin.actions.delete'),
- })
- ) {
- deleteLabel.mutate({ fulfillmentId, labelId: label.id })
- }
- }}
- >
- <TrashIcon className="size-4" />
- <span className="sr-only">{t('admin.orders.detail.fulfillments.delete_label')}</span>
- </Button>
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button type="button" variant="ghost" size="icon-xs">
+ <EllipsisVerticalIcon className="size-4" />
+ <span className="sr-only">{t('admin.actions.actions_menu')}</span>
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ <DropdownMenuItem
+ variant="destructive"
+ onClick={async () => {
+ if (
+ await confirm({
+ message: t('admin.orders.detail.fulfillments.confirm_delete_label'),
+ variant: 'destructive',
+ confirmLabel: t('admin.actions.delete'),
+ })
+ ) {
+ deleteLabel.mutate({ fulfillmentId, labelId: label.id })
+ }
+ }}
+ >
+ <TrashIcon className="size-4" />
+ {t('admin.orders.detail.fulfillments.delete_label')}
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
)}
</div>
</CardContent>
diff --git a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
index cc0b2afbad..8f4e7fe7ae 100644
--- a/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
+++ b/packages/dashboard/src/components/spree/orders/fulfillments-card.tsx
@@ -442,7 +442,7 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
<span className="text-muted-foreground text-xs">
<RelativeTime
iso={fulfillment.fulfilled_at}
- prefix={t('admin.orders.detail.tracking.shipped_prefix')}
+ prefix={t('admin.orders.detail.tracking.fulfilled_prefix')}
fallback=""
/>
</span>
@@ -543,7 +543,6 @@ function FulfillmentRow({ order, fulfillment }: { order: Order; fulfillment: Ful
orderId={orderId}
fulfillmentId={fulfillment.id}
deliveries={deliveries}
- canMarkDelivered={deliverable}
onEdit={(delivery) => {
setEditingDelivery(delivery)
setDeliveryOpen(true)
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index c6b53a9ca5..99e5826cc9 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -2727,6 +2727,7 @@
"buy_label_pending_file": "لا تزال نسخة شركة الشحن قيد التنزيل؛ ستفتح الطباعة رابط شركة الشحن نفسه.",
"carrier_auto": "اكتشاف تلقائي",
"carrier_label": "شركة الشحن",
+ "carrier_search": "البحث عن شركة شحن",
"carrier_status_available_for_pickup": "جاهز للاستلام",
"carrier_status_delivered": "تم التسليم",
"carrier_status_failure": "فشل التسليم",
@@ -2775,8 +2776,6 @@
"split_title": "تقسيم الشحنة",
"split_would_empty": "اترك وحدة واحدة على الأقل، أو غيّر مصدر الشحنة بالكامل بدلاً من ذلك.",
"tracking_description": "رقم تتبع شركة الشحن، أو رابط تتبع كامل.",
- "tracking_url_label": "رابط التتبع",
- "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_other": "غير مُنفَّذ ({{count}})",
"upload_label": "رفع ملصق",
"upload_label_cost": "تكلفة أجرة الشحن",
@@ -2803,7 +2802,6 @@
"captured": "القبض على الدفع",
"completed": "اكتمل الطلب",
"confirmation_sent": "تم إرسال التأكيد",
- "shipped": "Fulfillment تم الشحن",
"voided": "تم إلغاء الدفع"
},
"no_customer": "لا توجد معلومات العميل",
@@ -2854,8 +2852,8 @@
"tax_included": "الضريبة (متضمنة)"
},
"tracking": {
- "prefix": "Tracking",
- "shipped_prefix": "تم الشحن"
+ "fulfilled_prefix": "تم التنفيذ",
+ "prefix": "Tracking"
},
"variant_search": {
"description": "ابحث عن متغير منتج لإضافته إلى هذا الطلب.",
@@ -2910,7 +2908,7 @@
},
"fulfill": {
"action": "وضع علامة كمشحون",
- "empty": "لا تحتوي هذه الشحنة على عناصر قابلة للشحن.",
+ "empty": "لا يحتوي هذا التنفيذ على عناصر يمكن تنفيذها.",
"include_item": "شحن {{name}}",
"notify_customer": "إرسال إشعار الشحن إلى العميل",
"of_units": "من {{count}}",
@@ -3107,7 +3105,6 @@
"capture": "يأسر",
"mark_paid": "وضع علامة على أنه مدفوع",
"refund": "استرداد",
- "ship": "وضع علامة على أنه تم الشحن",
"void": "Void"
},
"claims": {
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index 4d78d9e45f..3d784dab18 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -2709,6 +2709,7 @@
"buy_label_pending_file": "Die Kopie des Transportunternehmens wird noch geladen; beim Drucken öffnet sich dessen eigener Link.",
"carrier_auto": "Automatisch erkennen",
"carrier_label": "Versanddienstleister",
+ "carrier_search": "Transportunternehmen suchen",
"carrier_status_available_for_pickup": "Zur Abholung bereit",
"carrier_status_delivered": "Zugestellt",
"carrier_status_failure": "Zustellung fehlgeschlagen",
@@ -2757,8 +2758,6 @@
"split_title": "Sendung aufteilen",
"split_would_empty": "Lassen Sie mindestens eine Einheit zurück oder ändern Sie stattdessen den Ursprung der gesamten Sendung.",
"tracking_description": "Die Sendungsnummer des Zustellers oder ein vollständiger Tracking-Link.",
- "tracking_url_label": "Sendungsverfolgungs-Link",
- "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_one": "Nicht versandt ({{count}})",
"unfulfilled_other": "Nicht versandt ({{count}})",
"upload_label": "Etikett hochladen",
@@ -2786,7 +2785,6 @@
"captured": "Zahlung eingezogen",
"completed": "Auftrag abgeschlossen",
"confirmation_sent": "Bestätigung gesendet",
- "shipped": "Lieferung versendet",
"voided": "Zahlung storniert"
},
"no_customer": "Keine Kundeninformationen",
@@ -2837,8 +2835,8 @@
"tax_included": "Steuer (inklusive)"
},
"tracking": {
- "prefix": "Tracking",
- "shipped_prefix": "Versendet"
+ "fulfilled_prefix": "Erfüllt",
+ "prefix": "Tracking"
},
"variant_search": {
"description": "Suchen Sie nach einer Produktvariante, die diesem Auftrag hinzugefügt werden soll.",
@@ -2893,7 +2891,7 @@
},
"fulfill": {
"action": "Als versendet markieren",
- "empty": "Diese Sendung enthält keine versandfähigen Artikel.",
+ "empty": "Diese Erfüllung enthält keine Artikel, die erfüllt werden können.",
"include_item": "{{name}} versenden",
"notify_customer": "Versandbenachrichtigung an Kundin oder Kunden senden",
"of_units": "von {{count}}",
@@ -3090,7 +3088,6 @@
"capture": "Einziehen",
"mark_paid": "Als bezahlt markieren",
"refund": "Erstatten",
- "ship": "Als versendet markieren",
"void": "Stornieren"
},
"claims": {
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index 474ac8dadf..d755df85a9 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -2709,6 +2709,7 @@
"buy_label_pending_file": "The carrier's copy is still downloading; printing opens the carrier's own link.",
"carrier_auto": "Detect automatically",
"carrier_label": "Shipping carrier",
+ "carrier_search": "Search carriers",
"carrier_status_available_for_pickup": "Available for pickup",
"carrier_status_delivered": "Delivered",
"carrier_status_failure": "Delivery failed",
@@ -2757,8 +2758,6 @@
"split_title": "Split fulfillment",
"split_would_empty": "Leave at least one unit behind, or change the origin of the whole fulfillment instead.",
"tracking_description": "The carrier tracking number, or a full tracking link.",
- "tracking_url_label": "Tracking link",
- "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_one": "Unfulfilled ({{count}})",
"unfulfilled_other": "Unfulfilled ({{count}})",
"upload_label": "Upload label",
@@ -2786,7 +2785,6 @@
"captured": "Payment captured",
"completed": "Order completed",
"confirmation_sent": "Confirmation sent",
- "shipped": "Fulfillment shipped",
"voided": "Payment voided"
},
"no_customer": "No customer information",
@@ -2837,8 +2835,8 @@
"tax_included": "Tax (included)"
},
"tracking": {
- "prefix": "Tracking",
- "shipped_prefix": "Shipped"
+ "fulfilled_prefix": "Fulfilled",
+ "prefix": "Tracking"
},
"variant_search": {
"description": "Search for a product variant to add to this order.",
@@ -2893,7 +2891,7 @@
},
"fulfill": {
"action": "Mark as fulfilled",
- "empty": "This fulfillment holds no items that can be shipped.",
+ "empty": "This fulfillment holds no items that can be fulfilled.",
"include_item": "Ship {{name}}",
"notify_customer": "Send shipment notification to customer",
"of_units": "of {{count}}",
@@ -3090,7 +3088,6 @@
"capture": "Capture",
"mark_paid": "Mark as paid",
"refund": "Refund",
- "ship": "Mark as shipped",
"void": "Void"
},
"claims": {
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index 227471a167..baeb94adba 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -2709,6 +2709,7 @@
"buy_label_pending_file": "La copie du transporteur est en cours de téléchargement ; l'impression ouvre son propre lien.",
"carrier_auto": "Détecter automatiquement",
"carrier_label": "Transporteur",
+ "carrier_search": "Rechercher un transporteur",
"carrier_status_available_for_pickup": "Disponible au retrait",
"carrier_status_delivered": "Livré",
"carrier_status_failure": "Échec de la livraison",
@@ -2757,8 +2758,6 @@
"split_title": "Diviser l'expédition",
"split_would_empty": "Laissez au moins une unité, ou modifiez plutôt l'origine de toute l'expédition.",
"tracking_description": "Le numéro de suivi du transporteur, ou un lien de suivi complet.",
- "tracking_url_label": "Lien de suivi",
- "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_one": "Non expédié ({{count}})",
"unfulfilled_other": "Non expédiés ({{count}})",
"upload_label": "Téléverser une étiquette",
@@ -2786,7 +2785,6 @@
"captured": "Paiement capturé",
"completed": "Commande finalisée",
"confirmation_sent": "Confirmation envoyée",
- "shipped": "Envoi expédié",
"voided": "Paiement annulé"
},
"no_customer": "Aucune information client",
@@ -2837,8 +2835,8 @@
"tax_included": "Taxe (incluse)"
},
"tracking": {
- "prefix": "Suivi",
- "shipped_prefix": "Expédié"
+ "fulfilled_prefix": "Traité",
+ "prefix": "Suivi"
},
"variant_search": {
"description": "Recherchez une variante de produit à ajouter à cette commande.",
@@ -2893,7 +2891,7 @@
},
"fulfill": {
"action": "Marquer comme expédié",
- "empty": "Cette expédition ne contient aucun article expédiable.",
+ "empty": "Ce traitement ne contient aucun article pouvant être traité.",
"include_item": "Expédier {{name}}",
"notify_customer": "Envoyer la notification d'expédition au client",
"of_units": "sur {{count}}",
@@ -3090,7 +3088,6 @@
"capture": "Capturer",
"mark_paid": "Marquer comme payée",
"refund": "Rembourser",
- "ship": "Marquer comme expédiée",
"void": "Annuler"
},
"claims": {
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index 8bf22c9659..9c2dba6a2a 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -2729,6 +2729,7 @@
"buy_label_pending_file": "Kopia przewoźnika jest jeszcze pobierana; drukowanie otworzy jego własny link.",
"carrier_auto": "Wykryj automatycznie",
"carrier_label": "Przewoźnik",
+ "carrier_search": "Szukaj przewoźnika",
"carrier_status_available_for_pickup": "Gotowa do odbioru",
"carrier_status_delivered": "Dostarczona",
"carrier_status_failure": "Doręczenie nieudane",
@@ -2777,8 +2778,6 @@
"split_title": "Podziel przesyłkę",
"split_would_empty": "Pozostaw co najmniej jedną sztukę albo zmień miejsce wysyłki całej przesyłki.",
"tracking_description": "Numer przesyłki od przewoźnika lub pełny link do śledzenia.",
- "tracking_url_label": "Link do śledzenia",
- "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_few": "Niezrealizowane ({{count}})",
"unfulfilled_many": "Niezrealizowane ({{count}})",
"unfulfilled_one": "Niezrealizowane ({{count}})",
@@ -2808,7 +2807,6 @@
"captured": "Płatność pobrana",
"completed": "Zamówienie sfinalizowane",
"confirmation_sent": "Potwierdzenie wysłane",
- "shipped": "Realizacja wysłana",
"voided": "Płatność unieważniona"
},
"no_customer": "Brak informacji o kliencie",
@@ -2859,8 +2857,8 @@
"tax_included": "Podatek (wliczony)"
},
"tracking": {
- "prefix": "Śledzenie",
- "shipped_prefix": "Wysłano"
+ "fulfilled_prefix": "Zrealizowano",
+ "prefix": "Śledzenie"
},
"variant_search": {
"description": "Wyszukaj wariant produktu, aby dodać go do tego zamówienia.",
@@ -2919,7 +2917,7 @@
},
"fulfill": {
"action": "Oznacz jako wysłane",
- "empty": "Ta przesyłka nie zawiera pozycji, które można wysłać.",
+ "empty": "Ta realizacja nie zawiera pozycji, które można zrealizować.",
"include_item": "Wyślij: {{name}}",
"notify_customer": "Wyślij klientowi powiadomienie o wysyłce",
"of_units": "z {{count}}",
@@ -3118,7 +3116,6 @@
"capture": "Pobierz",
"mark_paid": "Oznacz jako opłacone",
"refund": "Zwrot środków",
- "ship": "Oznacz jako wysłane",
"void": "Unieważnij"
},
"claims": {
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index 4e93a8a433..9ca0048458 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -2702,6 +2702,7 @@
"buy_label_pending_file": "承运商的副本仍在下载中;打印将打开承运商自己的链接。",
"carrier_auto": "自动识别",
"carrier_label": "承运商",
+ "carrier_search": "搜索承运商",
"carrier_status_available_for_pickup": "可自提",
"carrier_status_delivered": "已送达",
"carrier_status_failure": "投递失败",
@@ -2750,8 +2751,6 @@
"split_title": "拆分发货单",
"split_would_empty": "请至少保留一件,或改为修改整个发货单的发货地。",
"tracking_description": "承运商的物流单号,或完整的跟踪链接。",
- "tracking_url_label": "跟踪链接",
- "tracking_url_placeholder": "https://carrier.example/track/...",
"unfulfilled_other": "未发货({{count}})",
"upload_label": "上传面单",
"upload_label_cost": "邮资费用",
@@ -2778,7 +2777,6 @@
"captured": "付款已收取",
"completed": "订单已完成",
"confirmation_sent": "确认信息已发送",
- "shipped": "发货已发出",
"voided": "付款已作废"
},
"no_customer": "无客户信息",
@@ -2829,8 +2827,8 @@
"tax_included": "税(含)"
},
"tracking": {
- "prefix": "物流",
- "shipped_prefix": "已发货"
+ "fulfilled_prefix": "已履行",
+ "prefix": "物流"
},
"variant_search": {
"description": "搜索要添加到此订单的商品变体。",
@@ -2885,7 +2883,7 @@
},
"fulfill": {
"action": "标记为已发货",
- "empty": "此发货单中没有可发货的商品。",
+ "empty": "此履行项中没有可履行的商品。",
"include_item": "发货 {{name}}",
"notify_customer": "向客户发送发货通知",
"of_units": "共 {{count}}",
@@ -3082,7 +3080,6 @@
"capture": "扣款",
"mark_paid": "标记为已付款",
"refund": "退款",
- "ship": "标记为已发货",
"void": "作废"
},
"claims": {
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb
index 8fce128464..7b1f6422af 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders/fulfillments_controller.rb
@@ -6,7 +6,7 @@ module Spree
class FulfillmentsController < BaseController
scoped_resource :fulfillments
- before_action :set_resource, only: [:show, :update, :fulfill, :purchase_label, :mark_delivered, :cancel, :split]
+ before_action :set_resource, only: [:show, :update, :fulfill, :mark_delivered, :cancel, :split]
# POST /api/v3/admin/orders/:order_id/fulfillments
#
@@ -79,25 +79,6 @@ module Spree
end
end
- # PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/purchase_label
- #
- # @deprecated Labels are a nested resource since 6.0 —
- # POST .../fulfillments/:id/labels buys one and answers with the
- # label. This alias answers with the fulfillment for one release
- # and is removed in 6.1.
- def purchase_label
- response.headers['Deprecation'] = 'true'
- with_order_lock do
- result = Spree.fulfillment_purchase_label_workflow.call(fulfillment: @resource)
-
- if result.success?
- render json: serialize_resource(result.value)
- else
- render_result_error(result)
- end
- end
- end
-
# PATCH /api/v3/admin/orders/:order_id/fulfillments/:id/mark_delivered
#
# Confirms the customer received the goods. Staff can record this
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 9295f68fe9..5ee278bf75 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -722,8 +722,6 @@ Spree::Core::Engine.add_routes do
resources :fulfillments, controller: 'orders/fulfillments', only: [:index, :show, :create, :update] do
member do
patch :fulfill
- # Deprecated alias of POST .../labels — removed in 6.1.
- patch :purchase_label
patch :mark_delivered
patch :cancel
patch :split
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/deliveries_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/deliveries_controller_spec.rb
index e279179b55..b163b44552 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/deliveries_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/deliveries_controller_spec.rb
@@ -95,6 +95,18 @@ RSpec.describe Spree::Api::V3::Admin::Orders::DeliveriesController, type: :contr
expect(response).to have_http_status(:unprocessable_content)
end
+ it 'refuses one that already arrived' do
+ delivery = fulfillment.deliveries.first
+ delivery.update_columns(status: 'delivered', delivered_at: Time.current)
+
+ delete :destroy, params: {
+ order_id: order.prefixed_id, fulfillment_id: fulfillment.prefixed_id, id: delivery.prefixed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(Spree::Delivery.exists?(delivery.id)).to be(true)
+ end
+
end
describe 'PATCH #mark_delivered' do
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb
index 1b393333fa..499e011ce5 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/orders/fulfillments_controller_spec.rb
@@ -302,33 +302,6 @@ RSpec.describe Spree::Api::V3::Admin::Orders::FulfillmentsController, type: :con
end
end
- describe 'PATCH #purchase_label (deprecated alias of POST labels)' do
- before do
- Spree::TestingSupport::LabelProvider.reset!
- allow_any_instance_of(Spree::Fulfillment).to receive(:provider).and_return(Spree::TestingSupport::LabelProvider.new)
- allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
- shipment.deliveries.destroy_all
- end
-
- it 'buys the label without fulfilling and answers with the fulfillment' do
- patch :purchase_label, params: { order_id: order.prefixed_id, id: shipment.prefixed_id }, as: :json
-
- expect(response).to have_http_status(:ok)
- expect(response.headers['Deprecation']).to eq('true')
- expect(json_response['status']).to eq('unfulfilled')
- expect(json_response['tracking']).to eq('1Z879E930346834440')
- expect(json_response['labels'].first['source']).to eq('purchased')
- end
-
- it 'fails loudly when the provider cannot produce a label' do
- allow_any_instance_of(Spree::TestingSupport::LabelProvider).to receive(:purchase_label).and_return(nil)
-
- patch :purchase_label, params: { order_id: order.prefixed_id, id: shipment.prefixed_id }, as: :json
-
- expect(response).to have_http_status(:unprocessable_content)
- end
- end
-
describe 'PATCH #mark_delivered' do
before do
Spree.fulfillment_fulfill_workflow.call(fulfillment: shipment)
diff --git a/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb
index 666f68b3a3..0a991b4d0e 100644
--- a/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb
+++ b/spree/api/spec/integration/spree/api/v3/admin/orders/fulfillments_spec.rb
@@ -234,54 +234,6 @@ RSpec.describe 'Admin Order Fulfillments API', type: :request, swagger_doc: 'api
end
end
- path '/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label' do
- patch 'Buy the shipping label (deprecated)' do
- tags 'Fulfillments'
- produces 'application/json'
- security [{ api_key: [], bearer_auth: [] }]
- description 'Deprecated alias of POST /labels, answering with the fulfillment instead of the label. Removed in Spree 6.1.'
- deprecated true
- admin_scope :write, :fulfillments
-
- admin_sdk_example 'order-fulfillments/purchase-label'
-
- 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: :order_id, in: :path, type: :string, required: true,
- description: 'Order ID'
- parameter name: :id, in: :path, type: :string, required: true,
- description: 'Fulfillment ID'
-
- response '200', 'label purchased' do
- let(:'x-spree-api-key') { secret_api_key.plaintext_token }
- let(:order_id) { order.prefixed_id }
- let(:id) { shipment.prefixed_id }
-
- before do
- shipment.deliveries.destroy_all
- allow(SsrfFilter).to receive(:get).and_raise(SocketError.new('offline'))
- allow_any_instance_of(Spree::Fulfillment).to receive(:provider).
- and_return(Spree::TestingSupport::LabelProvider.new)
- end
-
- run_test! do |response|
- data = JSON.parse(response.body)
- expect(data['status']).to eq('unfulfilled')
- expect(data['labels'].first['source']).to eq('purchased')
- end
- end
-
- response '422', 'provider does not produce labels' do
- let(:'x-spree-api-key') { secret_api_key.plaintext_token }
- let(:order_id) { order.prefixed_id }
- let(:id) { shipment.prefixed_id }
-
- run_test!
- end
- end
- end
-
path '/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered' do
patch 'Mark a fulfillment delivered' do
tags 'Fulfillments'
diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rb
index 2be9216b7f..490c902b30 100644
--- a/spree/core/app/models/spree/fulfillment.rb
+++ b/spree/core/app/models/spree/fulfillment.rb
@@ -125,9 +125,6 @@ module Spree
include Spree::HasStatus
has_status :unfulfilled, :fulfilled, :delivered, :canceled, default: :unfulfilled
- # @deprecated The carrier vocabulary lives on {Spree::Delivery::STATUSES}; removed in 6.1.
- TRACKING_STATUSES = Spree::Delivery::STATUSES
-
# @deprecated Use {Spree::Fulfillments::Fulfill}; removed in 6.1.
def ship(*args)
Spree::Deprecation.warn('Spree::Fulfillment#ship is deprecated and will be removed in Spree 6.1. Use Spree::Fulfillments::Fulfill instead.')
diff --git a/spree/core/app/models/spree/integration.rb b/spree/core/app/models/spree/integration.rb
index d797f31d88..647f703d3d 100644
--- a/spree/core/app/models/spree/integration.rb
+++ b/spree/core/app/models/spree/integration.rb
@@ -141,7 +141,7 @@ module Spree
# webhooks overrides this, verifies the signature against its own secret
# (raising {WebhookSignatureError} when it is missing or wrong), and
# returns the event translated into vocabulary core understands. Carrier
- # integrations return {Spree::Fulfillments::UpdateTracking} keyword
+ # integrations return {Spree::Deliveries::UpdateTracking} keyword
# arguments plus +tracking_code+; +nil+ means "not an event we act on",
# which the endpoint acknowledges without doing anything.
#
diff --git a/spree/core/app/services/spree/deliveries/destroy.rb b/spree/core/app/services/spree/deliveries/destroy.rb
index aab731498f..90eb124c52 100644
--- a/spree/core/app/services/spree/deliveries/destroy.rb
+++ b/spree/core/app/services/spree/deliveries/destroy.rb
@@ -1,9 +1,13 @@
module Spree
module Deliveries
- # Removes a hand-entered consignment. A delivery minted by a label is not
- # removable on its own — the label is the record of what was bought, so
- # the way out is refunding it, which removes the delivery when the parcel
- # never moved.
+ # Removes a hand-entered consignment that never went anywhere.
+ #
+ # Two things are not removable. A delivery minted by a label is the
+ # label's own record of what was bought, so the way out is refunding it,
+ # which drops the delivery when the parcel never moved. And a delivery
+ # that arrived is a fact about what happened — its arrival is what the
+ # returns window and the withdrawal period count from — so it stays, and
+ # a mistake is corrected by fixing the row rather than erasing it.
class Destroy
prepend Spree::ServiceModule::Base
@@ -15,6 +19,11 @@ module Spree
return failure(delivery)
end
+ if delivery.delivered?
+ delivery.errors.add(:base, Spree.t('deliveries.errors.delivered'))
+ return failure(delivery)
+ end
+
delivery.destroy ? success(delivery) : failure(delivery)
end
end
diff --git a/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb b/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb
index aefba9b57c..3216b0c910 100644
--- a/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb
+++ b/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb
@@ -4,7 +4,7 @@ module Spree
# which used to stop at handover.
#
# Three things reach it: a carrier reporting delivery (through
- # {Spree::Fulfillments::UpdateTracking}), a staff member pressing a button
+ # {Spree::Deliveries::UpdateTracking}), a staff member pressing a button
# because they know the parcel arrived, and — for pickup — the customer
# collecting it. Merchants without any carrier integration still get a
# usable delivered state that way.
diff --git a/spree/core/app/workflows/spree/fulfillments/update_tracking.rb b/spree/core/app/workflows/spree/fulfillments/update_tracking.rb
deleted file mode 100644
index eb8969de4e..0000000000
--- a/spree/core/app/workflows/spree/fulfillments/update_tracking.rb
+++ /dev/null
@@ -1,29 +0,0 @@
-module Spree
- module Fulfillments
- # @deprecated Tracking is a Spree::Delivery since 6.0 — use
- # Spree::Deliveries::UpdateTracking with +delivery:+. This shell resolves
- # the fulfillment's primary delivery for one release; removed in 6.1.
- class UpdateTracking < Spree::Workflow
- hooks :validate, :after_update_tracking
-
- # @param fulfillment [Spree::Fulfillment]
- # @return [Spree::ServiceModule::Result] the fulfillment on success
- def perform(fulfillment:, **arguments)
- super(fulfillment: fulfillment)
-
- Spree::Deprecation.warn(
- 'Spree::Fulfillments::UpdateTracking is deprecated and will be removed in Spree 6.1. ' \
- 'Use Spree::Deliveries::UpdateTracking with delivery: instead.'
- )
-
- delivery = fulfillment.primary_delivery
- failure(fulfillment, Spree.t('deliveries.errors.not_found')) if delivery.nil?
-
- result = Spree.delivery_update_tracking_workflow.call(delivery: delivery, **arguments)
- failure(fulfillment, result.error.to_s) if result.failure?
-
- success(fulfillment.reload)
- end
- end
- end
-end
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 0fa73f9935..992e807492 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -900,6 +900,7 @@ en:
deleted: Deleted
deliveries:
errors:
+ delivered: This consignment has already arrived — its arrival is what the returns window counts from, so it cannot be deleted
has_label: This delivery was created by a shipping label — refund the label instead of deleting the delivery
not_found: This fulfillment has no delivery to track yet
delivery: Delivery
diff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rb
index 8a8fd906df..8c43cade20 100644
--- a/spree/core/lib/spree/core/dependencies.rb
+++ b/spree/core/lib/spree/core/dependencies.rb
@@ -81,10 +81,6 @@ module Spree
fulfillment_cancel_workflow: 'Spree::Fulfillments::Cancel',
fulfillment_mark_delivered_workflow: 'Spree::Fulfillments::MarkDelivered',
fulfillment_purchase_label_workflow: 'Spree::Fulfillments::PurchaseLabel',
- # @deprecated Tracking is a delivery since 6.0 — see
- # delivery_update_tracking_workflow. The shell resolves the primary
- # delivery one release; removed in 6.1.
- fulfillment_update_tracking_workflow: 'Spree::Fulfillments::UpdateTracking',
# shipping labels + deliveries
shipping_label_purchase_workflow: 'Spree::ShippingLabels::Purchase',
diff --git a/spree/core/spec/services/spree/deliveries/destroy_spec.rb b/spree/core/spec/services/spree/deliveries/destroy_spec.rb
index 62d5bef342..84cc8d41fb 100644
--- a/spree/core/spec/services/spree/deliveries/destroy_spec.rb
+++ b/spree/core/spec/services/spree/deliveries/destroy_spec.rb
@@ -22,4 +22,16 @@ RSpec.describe Spree::Deliveries::Destroy do
expect(result.error.to_s).to eq(Spree.t('deliveries.errors.has_label'))
expect(label.reload.delivery).to be_present
end
+ # Arrival is what the returns window and the withdrawal period count from,
+ # so it is a fact to correct rather than erase.
+ it 'refuses one that already arrived' do
+ delivery = fulfillment.deliveries.first
+ delivery.update_columns(status: 'delivered', delivered_at: Time.current)
+
+ result = service.call(delivery: delivery)
+
+ expect(result).to be_failure
+ expect(result.error.to_s).to eq(Spree.t('deliveries.errors.delivered'))
+ expect(Spree::Delivery.exists?(delivery.id)).to be(true)
+ end
end
diff --git a/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb b/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb
deleted file mode 100644
index 4dd07c7ddc..0000000000
--- a/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb
+++ /dev/null
@@ -1,27 +0,0 @@
-require 'spec_helper'
-
-module Spree
- describe Fulfillments::UpdateTracking do
- subject { described_class }
-
- let(:fulfillment) { create(:order_ready_to_ship, store: @default_store).fulfillments.first }
-
- before { Spree.fulfillment_fulfill_workflow.call(fulfillment: fulfillment) }
-
- it 'resolves the primary delivery for legacy callers, with a warning' do
- expect(Spree::Deprecation).to receive(:warn).with(/Deliveries::UpdateTracking/)
-
- result = subject.call(fulfillment: fulfillment, tracking_status: 'in_transit')
-
- expect(result).to be_success
- expect(fulfillment.primary_delivery.reload.status).to eq('in_transit')
- end
-
- it 'fails for a fulfillment with no delivery' do
- allow(Spree::Deprecation).to receive(:warn)
- fulfillment.deliveries.destroy_all
-
- expect(subject.call(fulfillment: fulfillment, tracking_status: 'in_transit')).to be_failure
- end
- end
-end
diff --git a/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb b/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
index 01dc3157e9..dea1592b91 100644
--- a/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
+++ b/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb
@@ -105,14 +105,6 @@ module SpreeEasyPost
# @param delivery [Spree::Delivery]
# @return [String, nil]
def tracking_url(delivery)
- if delivery.is_a?(Spree::Fulfillment)
- Spree::Deprecation.warn(
- 'SpreeEasyPost::FulfillmentProvider#tracking_url takes a Spree::Delivery since 6.0; ' \
- 'passing a fulfillment will be removed in Spree 6.1.'
- )
- delivery = delivery.primary_delivery
- end
-
delivery&.shipping_label&.metadata&.dig('easypost_tracker_url')
end
diff --git a/spree/providers/easypost/app/models/spree_easypost/tracker_event.rb b/spree/providers/easypost/app/models/spree_easypost/tracker_event.rb
index 90ecb4b092..23c376e705 100644
--- a/spree/providers/easypost/app/models/spree_easypost/tracker_event.rb
+++ b/spree/providers/easypost/app/models/spree_easypost/tracker_event.rb
@@ -1,6 +1,6 @@
module SpreeEasyPost
# One `tracker.updated` webhook, translated into the vocabulary
- # Spree::Fulfillments::UpdateTracking speaks.
+ # Spree::Deliveries::UpdateTracking speaks.
#
# Translating carrier status names is the provider's job precisely so core
# never learns any one carrier's spelling — EasyPost's own vocabulary happens
@@ -54,7 +54,7 @@ module SpreeEasyPost
)
end
- # The shape {Spree::Fulfillments::UpdateTracking} takes, plus the
+ # The shape {Spree::Deliveries::UpdateTracking} takes, plus the
# tracking code the endpoint matches the fulfillment on.
#
# @return [Hash]
diff --git a/spree/providers/easypost/spec/models/spree_easypost/tracker_event_spec.rb b/spree/providers/easypost/spec/models/spree_easypost/tracker_event_spec.rb
index d02b36bc04..f7d42368ab 100644
--- a/spree/providers/easypost/spec/models/spree_easypost/tracker_event_spec.rb
+++ b/spree/providers/easypost/spec/models/spree_easypost/tracker_event_spec.rb
@@ -20,7 +20,7 @@ RSpec.describe SpreeEasyPost::TrackerEvent do
expect(event.tracking_code).to eq('EZ1000000001')
expect(event.status).to eq('out_for_delivery')
- expect(Spree::Fulfillment::TRACKING_STATUSES).to include(event.status)
+ expect(Spree::Delivery::STATUSES).to include(event.status)
end
# EasyPost spells a few of its own states differently from ours; the point