Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
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.yamlindex 3cd728c33c..ae44fce91d 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -39,18 +39,28 @@ info:```version: v3paths:- "/api/v3/admin/admin_users":- get:- summary: List staff+ "/api/v3/admin/auth/login":+ post:+ summary: Logintags:- - Staff+ - Authenticationsecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: stringresponses:'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+ email: [email protected]+ 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:+ default: email+ email:+ type: string+ format: email+ example: [email protected]+ password:+ type: string+ example: password123+ required:+ - 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:+ required:+ - provider+ additionalProperties: true+ "/api/v3/admin/auth/refresh":+ post:+ summary: Refresh tokentags:- - Staff+ - Authenticationsecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /admin_users/{id}+ source: spree api post /auth/refreshparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: stringresponses:'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+ email: [email protected]+ 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: Logouttags:- - Staff+ - Authenticationsecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api patch /admin_users/{id} -d '{"first_name":"Ada","role_ids":["role_xxx"]}'+ source: spree api post /auth/logoutparameters:- name: x-spree-api-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: stringresponses:- '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 permissionstags:- - Staff+ - Authenticationsecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /admin_users/{id}+ source: spree api get /meparameters:- name: x-spree-api-keyin: header@@ -222,33 +308,112 @@ paths:- name: Authorizationin: headerrequired: true- schema:- type: string- - name: id- in: path- required: true+ description: Bearer token for admin authenticationschema:type: stringresponses:- '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+ email: [email protected]+ 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 profiletags:- - Allowed Origins+ - Authenticationsecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /allowed_origins+ source: spree api patch /me -d '{"selected_locale":"de"}'parameters:- name: x-spree-api-keyin: header@@ -276,73 +444,122 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:'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 updatedcontent:application/json:+ example:+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ 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_dashboardschema:- "$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 resettags:- - Allowed Origins+ - Authenticationsecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: stringresponses:- '201':- description: allowed origin created- content:- application/json:- schema:- "$ref": "#/components/schemas/AllowedOrigin"- '422':- description: validation error+ '202':+ description: reset requestedcontent: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: objectproperties:- origin:+ email:type: string- example: https://admin.example.com+ format: email+ example: [email protected]+ 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+ "/api/v3/admin/auth/password_resets/{id}":+ patch:+ summary: Reset passwordtags:- - Allowed Origins+ - Authenticationsecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header+ - name: id+ in: path+ description: The reset token from the emailed linkrequired: 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: stringresponses:'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 resetcontent:application/json:+ example:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjBiZTdhM2RmLWEyYzYtNDZkOC1hNTZiLWE4NDg4MGIyZGZiNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Vo2RzprqsH2XBa8DaSQ6awyXqlBA5QDFA5R7ygTezXY+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ 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_1schema:- "$ref": "#/components/schemas/AllowedOrigin"+ "$ref": "#/components/schemas/AuthResponse"'422':- description: validation error+ description: invalid or expired tokencontent: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: objectproperties:- 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 availabilitytags:- - 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: truepost:- summary: Create an API key+ summary: Complete first-run setuptags:- - 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+ email: [email protected]+ 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 availablerequestBody:content:application/json:schema:type: objectrequired:- - name- - key_type+ - setup_token+ - password+ - country_codeproperties:- 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+ example: [email protected]+ 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 setuptags:- - 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:- default: email- email:- type: string- format: email- example: [email protected]- password:- type: string- example: password123- required:- - 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:- 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: countriescontent: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 Samoacurrency: 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- email: [email protected]- 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- example: [email protected]- 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:- properties:- email:- type: string- example: [email protected]- 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:- - role_id- properties:- email:- type: string- example: [email protected]- 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 originstags:- - Deliveries+ - Allowed Originssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered- -d '{ ... }'+ source: spree api get /allowed_originsparameters:- name: x-spree-api-keyin: header@@ -12284,115 +2187,93 @@ paths:description: Bearer token for admin authenticationschema: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 numberschema:- 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 pageschema:- 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: sortin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'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 origintags:- - Fulfillments+ - Allowed Originssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -12426,84 +2303,61 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: order_id- in: path- required: true- description: Order ID- schema:- type: stringresponses:'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_idproperties:- 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: stringget:- summary: Show a shipment+ summary: Get an allowed origintags:- - Fulfillments+ - Allowed Originssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /orders/{order_id}/fulfillments/{id}+ source: spree api get /allowed_origins/{id}parameters:- name: x-spree-api-keyin: header@@ -12531,47 +2385,45 @@ paths:description: Bearer token for admin authenticationschema: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: fieldsin: queryrequired: 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: stringresponses:'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 origintags:- - Fulfillments+ - Allowed Originssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -12601,47 +2453,55 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:'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: objectproperties:- 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 origintags:- - Fulfillments+ - Allowed Originssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -12670,34 +2529,21 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:- '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 keystags:- - Fulfillments+ - API Keyssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/fulfillments/{id}/purchase_label- -d '{ ... }'+ source: spree api get /api_keysparameters:- name: x-spree-api-keyin: header@@ -12731,38 +2568,74 @@ paths:- name: Authorizationin: headerrequired: 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 IDschema:type: stringresponses:'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 keytags:- - Fulfillments+ - API Keyssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -12792,107 +2666,73 @@ paths:- name: Authorizationin: headerrequired: 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 IDschema:type: stringresponses:- '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 blankrequestBody:content:application/json:schema:type: object+ required:+ - name+ - key_typeproperties:- 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 keytags:- - Fulfillments+ - API Keyssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -12928,54 +2757,42 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order IDschema:type: string- name: idin: pathrequired: true- description: Fulfillment IDschema:type: stringresponses:'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 keytags:- - Orders+ - API Keyssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -13002,42 +2818,49 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- - name: order_id+ - name: idin: pathrequired: true- description: Order IDschema:type: stringresponses:- '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:- - codeproperties:- 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 keytags:- - Orders+ - API Keyssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /orders/{order_id}/gift_cards/{id}+ source: spree api delete /api_keys/{id}parameters:- name: x-spree-api-keyin: header@@ -13062,36 +2885,27 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order IDschema:type: string- name: idin: pathrequired: true- description: Gift card IDschema:type: stringresponses:'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 keytags:- - Orders+ - API Keyssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /orders/{order_id}/items+ source: spree api get /api_keys/currentparameters:- name: x-spree-api-keyin: headerrequired: trueschema: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: stringresponses:'200':- description: items found+ description: current API keycontent: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 keytags:- - Orders+ - API Keyssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -13244,112 +2983,44 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- - name: order_id+ - name: idin: pathrequired: true- description: Order IDschema:type: stringresponses:- '201':- description: item added+ '200':+ description: API key revokedcontent: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_allcreated_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 categoriestags:- - Orders+ - Categoriessecurity:- 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-keyin: header@@ -13362,116 +3033,90 @@ paths:description: Bearer token for admin authenticationschema: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 numberschema:- type: string- - name: expand+ type: integer+ - name: limitin: queryrequired: 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 pageschema:- type: string- - name: fields+ type: integer+ - name: expandin: queryrequired: 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: stringresponses:'200':- description: item found+ description: categories foundcontent: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: 0created_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 categorytags:- - Orders+ - Categoriessecurity:- 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-keyin: header@@ -13484,112 +3129,89 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:- '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: objectproperties:- 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 categorytags:- - Shipping Labels+ - Categoriessecurity:- 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-keyin: header@@ -13602,52 +3224,73 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: order_id+ - name: idin: pathrequired: true- description: Order ID+ description: Category IDschema: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: stringresponses:'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 categorytags:- - Shipping Labels+ - Categoriessecurity:- 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-keyin: header@@ -13660,70 +3303,78 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: order_id- in: path- required: true- description: Order ID- schema:- type: string- - name: fulfillment_id+ - name: idin: pathrequired: true- description: Fulfillment ID+ description: Category IDschema:type: stringresponses:- '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: objectproperties:- 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:- - 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 categorytags:- - Shipping Labels+ - Categoriessecurity:- 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-keyin: header@@ -13736,38 +3387,27 @@ paths:description: Bearer token for admin authenticationschema: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: idin: pathrequired: true- description: Shipping label ID+ description: Category IDschema:type: stringresponses:- '200':- description: label found- delete:- summary: Delete an uploaded label+ '204':+ description: category deleted+ "/api/v3/admin/categories/{id}/reposition":+ patch:+ summary: Reposition a categorytags:- - Shipping Labels+ - Categoriessecurity:- 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-keyin: header@@ -13780,63 +3420,71 @@ paths:description: Bearer token for admin authenticationschema: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: idin: pathrequired: true- description: Shipping label ID+ description: Category IDschema:type: stringresponses:- '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 productstags:- - Shipping Labels+ - Categoriessecurity:- 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-keyin: header@@ -13849,56 +3497,52 @@ paths:description: Bearer token for admin authenticationschema: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_idin: pathrequired: true- description: Shipping label ID+ description: Category IDschema:type: stringresponses:'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 categorytags:- - Payments+ - Categoriessecurity:- 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-keyin: header@@ -13911,59 +3555,44 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: order_id+ - name: category_idin: pathrequired: 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 IDschema:type: stringresponses:- '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 categorytags:- - Payments+ - Categoriessecurity:- 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-keyin: header@@ -13976,59 +3605,45 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: order_id+ - name: category_idin: pathrequired: true- description: Order ID+ description: Category IDschema:type: stringresponses:- '201':- description: payment created+ '200':+ description: products removed+ content:+ application/json:+ example:+ removed_count: 1requestBody:content:application/json:schema:type: object- required:- - payment_method_idproperties:- 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 producttags:- - Payments+ - Categoriessecurity:- 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-keyin: header@@ -14041,47 +3656,44 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: order_id+ - name: category_idin: pathrequired: true- description: Order ID+ description: Category IDschema:type: string- name: idin: 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 IDschema:type: stringresponses:- '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 channelstags:- - Payments+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/payments/{id}/capture -d '{ ...- }'+ source: spree api get /channelsparameters:- name: x-spree-api-keyin: header@@ -14107,42 +3718,89 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- - name: order_id- in: path- required: true- description: Order ID+ - name: page+ in: query+ required: falseschema:- type: string- - name: id- in: path- required: true- description: Payment ID+ type: integer+ - name: limit+ in: query+ required: falseschema:- type: string+ type: integerresponses:'200':- description: payment captured- '422':- description: capture failed+ description: channels foundcontent: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 channeltags:- - Payments+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -14167,36 +3831,83 @@ paths:- name: Authorizationin: headerrequired: 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 IDschema:type: stringresponses:- '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: stringget:- summary: List refunds+ summary: Get a channeltags:- - Refunds+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /orders/{order_id}/refunds+ source: spree api get /channels/{id}parameters:- name: x-spree-api-keyin: header@@ -14221,43 +3932,36 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'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 channeltags:- - Refunds+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -14286,48 +3989,69 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order IDschema:type: stringresponses:- '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- - amountproperties:- 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 channeltags:- - Orders+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -14354,128 +4076,32 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order IDschema:type: stringresponses:- '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- email: [email protected]- 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 channeltags:- - Orders+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -14500,30 +4132,60 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order IDschema:type: stringresponses:- '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 channeltags:- - Orders+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -14553,187 +4212,50 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'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- email: [email protected]- 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 unpublishedcontent:application/json:example:- error:- code: authentication_required- message: Authentication required+ product_count: 1schema:- "$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 channeltags:- - Orders+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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_rulesparameters:- name: x-spree-api-keyin: header@@ -14841,221 +4280,71 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:- '201':- description: order created with preferred_stock_location_id+ '200':+ description: rules foundcontent: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- email: [email protected]- 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- example: [email protected]- 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 channeltags:- - Orders+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -15082,143 +4371,74 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:- '200':- description: order found+ '201':+ description: rule createdcontent: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- email: [email protected]- 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: truecreated_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 typecontent: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: stringpatch:- summary: Update an order+ summary: Update an order routing ruletags:- - Orders+ - Channelssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -15247,191 +4467,238 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: id- in: path- required: true- description: Order IDschema:type: stringresponses:'200':- description: order updated+ description: rule updatedcontent: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- email: [email protected]- 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: falsecreated_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 setrequestBody:content:application/json:schema:type: objectproperties:- 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: truedelete:- 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 definitiontags:- - Orders+ - Custom Fieldssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -15456,33 +4731,72 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: id- in: path- required: true- description: Order IDschema:type: stringresponses:- '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 definitiontags:- - Orders+ - Custom Fieldssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -15509,157 +4821,53 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- name: idin: pathrequired: 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: stringresponses:'200':- description: order completed+ description: definition foundcontent: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- email: [email protected]- 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_fabriccreated_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 definitiontags:- - Orders+ - Custom Fieldssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -15692,145 +4896,56 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- name: idin: pathrequired: true- description: Order IDschema:type: stringresponses:'200':- description: order canceled+ description: definition updatedcontent: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- email: [email protected]- 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_fabriccreated_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_UkLWZg9DAJrequestBody:content:application/json:schema:type: objectproperties:- 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 definitiontags:- - Orders+ - Custom Fieldssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api patch /orders/{id}/approve -d '{ ... }'+ source: spree api delete /custom_field_definitions/{id}parameters:- name: x-spree-api-keyin: header@@ -15855,119 +4970,34 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- name: idin: pathrequired: true- description: Order IDschema:type: stringresponses:- '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- email: [email protected]- 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 groupstags:- - Orders+ - Customer Groupssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -15995,121 +5025,102 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:'200':- description: confirmation resent+ description: customer groups foundcontent: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- email: [email protected]- 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 grouptags:- - Authentication+ - Customer Groupssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: headerrequired: trueschema:type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: stringresponses:- '202':- description: reset requested+ '201':+ description: customer group createdcontent: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:+ - nameproperties:- email:+ name:type: string- format: email- example: [email protected]- 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:- "/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 grouptags:- - Authentication+ - Customer Groupssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: headerrequired: trueschema:type: string- - name: id- in: path- description: The reset token from the emailed link+ - name: Authorization+ in: headerrequired: trueschema: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: stringresponses:'200':- description: password reset+ description: customer group with embedded customerscontent:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjBiZTdhM2RmLWEyYzYtNDZkOC1hNTZiLWE4NDg4MGIyZGZiNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Vo2RzprqsH2XBa8DaSQ6awyXqlBA5QDFA5R7ygTezXY- user:- id: adm_UkLWZg9DAJ- email: [email protected]- 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+ email: [email protected]+ 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_UkLWZg9DAJschema:- "$ref": "#/components/schemas/AuthResponse"- '422':- description: invalid or expired token+ "$ref": "#/components/schemas/CustomerGroup"+ '404':+ description: customer group not foundcontent: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 foundschema:"$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 grouptags:- - Payment Methods+ - Customer Groupssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -16295,66 +5357,63 @@ paths:required: trueschema: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: stringresponses:'200':- description: payment methods found+ description: customer group updatedcontent: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 grouptags:- - Payment Methods+ - Customer Groupssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /payment_methods/types+ source: spree api delete /customer_groups/{id}parameters:- name: x-spree-api-keyin: header@@ -16382,38 +5441,20 @@ paths:schema:type: stringresponses:- '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 addressestags:- - Payment Methods+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /payment_methods/{id}+ source: spree api get /customers/{customer_id}/addressesparameters:- name: x-spree-api-keyin: header@@ -16440,7 +5481,7 @@ paths:required: trueschema:type: string- - name: id+ - name: customer_idin: pathrequired: trueschema:@@ -16448,52 +5489,74 @@ paths:- name: expandin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: payment method found+ description: addresses foundcontent: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 addresstags:- - Staff+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -16520,391 +5596,239 @@ paths:required: trueschema:type: string+ - name: customer_id+ in: path+ required: true+ schema:+ type: stringresponses:- '200':- description: catalog returned+ '201':+ description: address createdcontent: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 addresstags:- - Policies+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /policies+ source: spree api get /customers/{customer_id}/credit_cardsparameters:- name: x-spree-api-keyin: header@@ -16929,124 +5853,69 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema: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: trueschema:- type: integer- - name: q[name_cont]+ type: string+ - name: expandin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: policies listed+ description: credit cards foundcontent: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: 1limit: 25- count: 5+ count: 1pages: 1from: 1- to: 5- in: 5+ to: 1+ in: 1previous: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 cardtags:- - Policies+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17075,73 +5940,113 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:- '201':- description: policy created+ '200':+ description: credit card foundcontent: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 creditstags:- - Policies+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /policies/{id}+ source: spree api get /customers/{customer_id}/store_creditsparameters:- name: x-spree-api-keyin: header@@ -17167,45 +6071,154 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'200':- description: policy found+ description: store credits foundcontent: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 createdcontent: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 credittags:- - Policies+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17233,49 +6246,60 @@ paths:- name: Authorizationin: headerrequired: 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: trueschema:type: stringresponses:'200':- description: policy updated+ description: store credit updatedcontent: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_UkLWZg9DAJrequestBody:content:application/json:schema:type: objectproperties:- name:- type: string- slug:+ amount:type: string- body:+ example: '50.00'+ memo:type: stringdelete:- summary: Delete a policy+ summary: Delete a store credittags:- - Policies+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /policies/{id}+ source: spree api delete /customers/{customer_id}/store_credits/{id}parameters:- name: x-spree-api-keyin: header@@ -17300,24 +6324,33 @@ paths:- name: Authorizationin: headerrequired: 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: trueschema:type: stringresponses:'204':- description: policy deleted- "/api/v3/admin/price_lists":+ description: store credit deleted+ "/api/v3/admin/customers":get:- summary: List price lists+ summary: List customerstags:- - Pricing+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17342,6 +6379,7 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- name: page@@ -17354,101 +6392,77 @@ paths:required: falseschema:type: integer- - name: q[name_cont]- in: query- required: false- schema:- type: string- - name: q[status_eq]+ - name: q[search]in: queryrequired: false+ description: Email + name full-text-ish searchschema:type: string- - name: sort+ - name: expandin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: price lists found+ description: customers foundcontent: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+ email: [email protected]+ 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: 1limit: 25- count: 2+ count: 1pages: 1from: 1- to: 2- in: 2+ to: 1+ in: 1previous:next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/PriceList"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - metapost:- summary: Create a price list+ summary: Create a customertags:- - Pricing+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17512,131 +6499,72 @@ paths:type: stringresponses:'201':- description: price list created (server-to-server — rules + prices)+ description: customer createdcontent: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+ email: [email protected]+ 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: objectrequired:- - nameproperties:- name:+ email:type: string- example: EU wholesale- description:+ example: [email protected]+ 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 customertags:- - Pricing+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17663,61 +6593,66 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ description: Customer ID+ schema:+ type: string- name: expandin: queryrequired: 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: stringresponses:'200':- description: price list found+ description: customer foundcontent: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+ email: [email protected]+ 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 customertags:- - Pricing+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17746,113 +6682,75 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: price list updated with nested rules+ description: customer updatedcontent: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+ email: [email protected]+ 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: objectproperties:- 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: objectdelete:- summary: Delete a price list+ summary: Delete a customertags:- - Pricing+ - Customerssecurity:- 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: javascriptlabel: Spree Admin SDK@@ -17864,10 +6762,10 @@ paths:secretKey: 'sk_xxx',})- await client.priceLists.delete('pl_xxx')+ await client.customers.delete('cus_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /price_lists/{id}+ source: spree api delete /customers/{id}parameters:- name: x-spree-api-keyin: header@@ -17879,30 +6777,30 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'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 groupstags:- - Pricing+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17931,26 +6832,55 @@ paths:type: stringresponses:'200':- description: price list activated+ description: customers added to groupscontent:application/json:+ example:+ customer_count: 1+ customer_group_count: 1schema:- "$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 groupstags:- - Pricing+ - Customerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -17979,27 +6912,72 @@ paths:type: stringresponses:'200':- description: price list deactivated+ description: customers removed from groupscontent:application/json:example:- error:- code: record_not_found- message: Price list not found+ customer_count: 1+ customer_group_count: 1schema:- "$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 customerstags:- - Price Lists+ - Customerssecurity:- 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-keyin: header@@ -18011,87 +6989,75 @@ paths:required: trueschema:type: string- - name: price_list_id- in: path- required: true- schema:- type: stringresponses:'200':- description: products found+ description: tags addedcontent:application/json:example:- error:- code: record_not_found- message: Price list not found+ customer_count: 1+ tag_count: 2schema:type: objectproperties:- 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: integerrequestBody:content:application/json:schema:type: object+ required:+ - ids+ - tagsproperties:- product_ids:+ ids:type: arrayitems:type: stringexample:- - 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 customerstags:- - Price Lists+ - Customerssecurity:- 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-keyin: header@@ -18103,46 +7069,54 @@ paths:required: trueschema:type: string- - name: price_list_id- in: path- required: true- schema:- type: stringresponses:'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: integerrequestBody:content:application/json:schema:type: object+ required:+ - ids+ - tagsproperties:- product_ids:+ ids:type: arrayitems:type: stringexample:- - 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 exportstags:- - Pricing+ - Exportssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /prices -d '{"price_list_id_eq":"pl_xxx","currency_eq":"USD","expand":["variant"]}'+ source: spree api get /exportsparameters:- name: x-spree-api-keyin: header@@ -18173,126 +7143,55 @@ paths:required: trueschema: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: stringresponses:'200':- description: prices found+ description: exports foundcontent: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: csvcreated_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: 1limit: 25- count: 3+ count: 1pages: 1from: 1- to: 3- in: 3+ to: 1+ in: 1previous:next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Price"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - metapost:- summary: Create a price+ summary: Create an exporttags:- - Pricing+ - Exportssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -18325,53 +7223,76 @@ paths:type: stringresponses:'201':- description: price created+ description: export queuedcontent: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: objectrequired:- - variant_id- - currency+ - typeproperties:- 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 exporttags:- - Pricing+ - Exportssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /prices/{id}+ source: spree api get /exports/{id}parameters:- name: x-spree-api-keyin: header@@ -18398,27 +7319,42 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: price found- content:- application/json:- schema:- "$ref": "#/components/schemas/Price"- '404':- description: price not found+ description: export foundcontent: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 exporttags:- - Pricing+ - Exportssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api patch /prices/{id} -d '{"amount":"12.34"}'+ source: spree api delete /exports/{id}parameters:- name: x-spree-api-keyin: header@@ -18447,36 +7381,26 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:- '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 exporttags:- - Pricing+ - Exportssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /prices/{id}+ source: spree api get /exports/{id}/downloadparameters:- name: x-spree-api-keyin: header@@ -18503,31 +7438,32 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:- '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 fulfillmentstags:- - Pricing+ - Fulfillmentssecurity:- 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: javascriptlabel: 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: bashlabel: 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}/fulfillmentsparameters:- name: x-spree-api-keyin: header@@ -18567,74 +7488,108 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'200':- description: prices upserted- content:- application/json:- schema:- type: object- properties:- price_count:- type: integer- '422':- description: missing prices key+ description: fulfillments foundcontent: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 fulfillmenttags:- - Pricing+ - Fulfillmentssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -18661,47 +7620,162 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order IDschema:type: stringresponses:- '200':- description: prices deleted+ '201':+ description: fulfillment createdcontent: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+ ordersrequestBody:content:application/json:schema:type: objectrequired:- - ids+ - stock_location_idproperties:- 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 shipmenttags:- - Product Types+ - Fulfillmentssecurity:- 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-keyin: header@@ -18714,58 +7788,117 @@ paths:description: Bearer token for admin authenticationschema: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: expandin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'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 foundcontent: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 shipmenttags:- - Product Types+ - Fulfillmentssecurity:- 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-keyin: header@@ -18778,78 +7911,116 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:- '201':- description: product type created- content:- application/json:- schema:- "$ref": "#/components/schemas/ProductType"- '422':- description: unprocessable entity+ '200':+ description: shipment updatedcontent: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: falserequestBody:content:application/json:schema:type: objectproperties:- 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 fulfillmenttags:- - Product Types+ - Fulfillmentssecurity:- 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-keyin: header@@ -18862,34 +8033,106 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:'200':- description: product type found- content:- application/json:- schema:- "$ref": "#/components/schemas/ProductType"- '404':- description: product type not found+ description: fulfillment fulfilledcontent: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 deliveredtags:- - Product Types+ - Fulfillmentssecurity:- 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-keyin: header@@ -18902,55 +8145,124 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:'200':- description: product type updated+ description: fulfillment deliveredcontent: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 deliveredrequestBody:content:application/json:schema:type: objectproperties:- 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 fulfillmenttags:- - Product Types+ - Fulfillmentssecurity:- 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-keyin: header@@ -18963,34 +8275,112 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:- '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 fulfillmenttags:- - Product Types+ - Fulfillmentssecurity:- 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-keyin: header@@ -19003,28 +8393,96 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:- '202':- description: backfill accepted+ '200':+ description: fulfillment splitcontent: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 batchestags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19049,41 +8507,87 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- - name: product_id- in: path- required: true+ - name: page+ in: query+ required: false+ description: Page numberschema:- type: string- - name: expand+ type: integer+ - name: limitin: queryrequired: 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: sortin: queryrequired: 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: stringresponses:'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+ - metapost:- summary: Create a product custom field+ summary: Create a gift card batchtags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19113,39 +8620,85 @@ paths:required: trueschema:type: string- - name: product_id- in: path- required: true- schema:- type: stringresponses:'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: objectrequired:- - custom_field_definition_id- - value+ - prefix+ - amount+ - codes_countproperties:- 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: stringget:- summary: Show a product custom field+ summary: Get a gift card batchtags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19172,44 +8725,48 @@ paths:required: trueschema: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: stringresponses:'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 cardstags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19236,39 +8795,137 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema: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: stringresponses:'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 cardtags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19331,26 +8957,96 @@ paths:required: trueschema:type: string- - name: product_id- in: path- required: true- schema:- type: stringresponses:- '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: stringget:- summary: List products+ summary: Get a gift cardtags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19380,91 +9073,64 @@ paths:- name: Authorizationin: headerrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: products found+ description: gift card foundcontent: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 foundcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Gift card not foundschema:"$ref": "#/components/schemas/ErrorResponse"- post:- summary: Create a product+ patch:+ summary: Update a gift cardtags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19519,154 +9157,65 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:- '201':- description: product created- content:- application/json:- schema:- "$ref": "#/components/schemas/Product"- '422':- description: validation error+ '200':+ description: gift card updatedcontent: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: objectproperties:- 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 cardtags:- - Products+ - Gift Cardssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -19693,72 +9240,223 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema: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: headerrequired: 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: trueschema:type: stringresponses:'200':- description: product found- content:- application/json:- schema:- "$ref": "#/components/schemas/Product"- '404':- description: product not found+ description: imports foundcontent: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 importtags:- - Products+ - Importssecurity:- 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-keyin: header@@ -19768,172 +9466,454 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: id- in: path- required: true- description: Product IDschema:type: stringresponses:- '200':- description: product updated+ '201':+ description: import created in mapping statecontent: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 typecontent:application/json:- schema:- "$ref": "#/components/schemas/ErrorResponse"+ example:+ error:+ code: validation_error+ message: Type can't be blank+ details:+ type:+ - can't be blankrequestBody:content:application/json:schema:type: object+ required:+ - type+ - attachmentproperties:- 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: stringenum:- - 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 filetags:- - Products+ - Importssecurity:- 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-keyin: header@@ -19943,56 +9923,174 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- name: idin: pathrequired: true- description: Product IDschema:type: stringresponses:- '204':- description: product deleted- '422':- description: deletion refused by a store rule+ '200':+ description: import foundcontent: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 importtags:- - Products+ - Importssecurity:- 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-keyin: header@@ -20004,78 +10102,26 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:- '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 filetags:- - Products+ - Importssecurity:- 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-keyin: header@@ -20087,65 +10133,36 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: products added to categories+ description: CSV filecontent:- 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 processingtags:- - Products+ - Importssecurity:- 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-keyin: header@@ -20157,40 +10174,355 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'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: falserequestBody:content:application/json:schema:type: object- required:- - ids- - category_idsproperties:- 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 rowstags:- - Products+ - Importssecurity:- 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-keyin: header@@ -20202,47 +10534,173 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: products added to collections+ description: retry queuedcontent: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 rowstags:- - Products+ - Importssecurity:- 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-keyin: header@@ -20254,41 +10712,62 @@ paths:required: trueschema: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: stringresponses:'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 marketstags:- - Products+ - Marketssecurity:- 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: javascriptlabel: 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: bashlabel: 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 /marketsparameters:- name: x-spree-api-keyin: header@@ -20318,47 +10794,107 @@ paths:required: trueschema: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: stringresponses:'200':- description: products published on channels+ description: markets foundcontent: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+ - metapost:- summary: Bulk-remove products from channels+ summary: Create a markettags:- - Products+ - Marketssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -20389,48 +10929,113 @@ paths:schema:type: stringresponses:- '200':- description: products unpublished from channels+ '201':+ description: market createdcontent: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_idsproperties:- 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: arrayitems: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: arrayitems: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 markettags:- - Products+ - Marketssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -20460,50 +11062,59 @@ paths:required: trueschema:type: string+ - name: expand+ in: query+ required: false+ schema:+ type: stringresponses:'200':- description: tags added+ description: market foundcontent: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 markettags:- - Products+ - Marketssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -20535,36 +11150,78 @@ paths:type: stringresponses:'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- - tagsproperties:- ids:+ name:+ type: string+ currency:+ type: string+ default_locale:+ type: string+ supported_locales:type: arrayitems:type: string- tags:+ tax_inclusive:+ type: boolean+ default:+ type: boolean+ position:+ type: integer+ country_codes:type: arrayitems:type: string- "/api/v3/admin/products/bulk_destroy":delete:- summary: Bulk-delete products+ summary: Delete a markettags:- - Products+ - Marketssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -20594,42 +11251,28 @@ paths:schema:type: stringresponses:- '200':- description: products deleted+ '204':+ description: market deleted+ '422':+ description: cannot delete default or last marketcontent: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 typestags:- - Promotions+ - Option Typessecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /promotions/{promotion_id}/promotion_actions+ source: spree api get /option_typesparameters:- name: x-spree-api-keyin: header@@ -20654,22 +11297,103 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'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 typetags:- - Promotions+ - Option Typessecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -20696,47 +11425,87 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: stringresponses:'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: objectproperties:- 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: integerrequired:- - 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 typetags:- - Promotions+ - Option Typessecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /promotions/{promotion_id}/promotion_actions/{id}+ source: spree api get /option_types/{id}parameters:- name: x-spree-api-keyin: header@@ -20761,66 +11530,67 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema: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: pathrequired: true+ description: Option type IDschema: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: stringresponses:'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 typetags:- - Promotions+ - Option Typessecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -20848,47 +11618,90 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Option type IDschema:type: stringresponses:- '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: objectproperties:- 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 typetags:- - Promotions+ - Option Typessecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -20916,28 +11726,30 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Option type IDschema:type: stringresponses:- '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 linestags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /promotions/{promotion_id}/promotion_rules/{id}+ source: spree api get /orders/{order_id}/tax_linesparameters:- name: x-spree-api-keyin: header@@ -20964,21 +11776,59 @@ paths:required: trueschema:type: string+ - name: order_id+ in: path+ required: true+ description: Order prefixed ID+ schema:+ type: stringresponses:- '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 discountstags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /promotions+ source: spree api get /orders/{order_id}/discountsparameters:- name: x-spree-api-keyin: header@@ -21005,26 +11855,54 @@ paths:required: trueschema:type: string+ - name: order_id+ in: path+ required: true+ description: Order prefixed ID+ schema:+ type: stringresponses:'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 discounttags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -21092,137 +11936,79 @@ paths:required: trueschema:type: string+ - name: order_id+ in: path+ required: true+ description: Order prefixed ID+ schema:+ type: stringresponses:'201':- description: promotion created with rules and actions+ description: discount createdcontent: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 numberrequestBody:content:application/json:schema:type: objectproperties:- 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: stringenum:- - 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: stringnullable: 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-levelrequired:- - name- "/api/v3/admin/promotions/{id}":- get:- summary: Show a promotion+ - label+ - value+ "/api/v3/admin/orders/{order_id}/fees":+ post:+ summary: Create feetags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -21249,29 +12039,83 @@ paths:required: trueschema:type: string- - name: id+ - name: order_idin: pathrequired: true+ description: Order prefixed IDschema:type: stringresponses:- '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 ordertags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -21334,117 +12142,64 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- - name: id+ - name: order_idin: pathrequired: true+ description: Order IDschema:type: stringresponses:- '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:+ - codeproperties:- name:- type: string- description:- type: string- nullable: truecode: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 ordertags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /promotions/{id}+ source: spree api delete /orders/{order_id}/gift_cards/{id}parameters:- name: x-spree-api-keyin: header@@ -21469,28 +12224,36 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order IDschema:type: string- name: idin: pathrequired: true+ description: Gift card IDschema:type: stringresponses:'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 itemstags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /promotion_actions/types+ source: spree api get /orders/{order_id}/itemsparameters:- name: x-spree-api-keyin: header@@ -21515,23 +12278,107 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'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 itemtags:- - Promotions+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -21556,28 +12406,97 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order IDschema:type: stringresponses:- '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 itemtags:- - Reasons+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /refund_reasons+ source: spree api get /orders/{order_id}/items/{id}parameters:- name: x-spree-api-keyin: header@@ -21605,56 +12524,99 @@ paths:description: Bearer token for admin authenticationschema: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 IDschema:- 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 IDschema:type: string- - name: q[active_eq]+ - name: expandin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: refund reasons found- '401':- description: unauthorized+ description: item foundcontent:- 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 itemtags:- - Reasons+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -21684,50 +12646,93 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:- '201':- description: refund reason created- '422':- description: validation error+ '200':+ description: item updatedcontent: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_UkLWZg9DAJrequestBody:content:application/json:schema:type: object- required:- - nameproperties:- 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 itemtags:- - Reasons+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /refund_reasons/{id}+ source: spree api delete /orders/{order_id}/items/{id}parameters:- name: x-spree-api-keyin: header@@ -21755,28 +12760,33 @@ paths:description: Bearer token for admin authenticationschema: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: stringresponses:- '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 ordertags:- - Reasons+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -21806,33 +12816,125 @@ paths:description: Bearer token for admin authenticationschema:type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: stringresponses:- '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+ email: [email protected]+ 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_UkLWZg9DAJrequestBody:content:application/json:schema:type: objectproperties:- name:+ amount:type: string- active:- type: boolean+ description: Optional explicit amount; defaults to order outstanding+ balancedelete:- summary: Delete a refund reason+ summary: Remove store credit from an ordertags:- - Reasons+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /refund_reasons/{id}+ source: spree api delete /orders/{order_id}/store_creditsparameters:- name: x-spree-api-keyin: header@@ -21860,26 +12962,27 @@ paths:description: Bearer token for admin authenticationschema:type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: stringresponses:'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 orderstags:- - Reasons+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -21919,117 +13027,172 @@ paths:description: Number of records per pageschema:type: integer- - name: q[name_cont]+ - name: sortin: queryrequired: 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: queryrequired: 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: queryrequired: 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 numberschema: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: stringresponses:- '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+ email: [email protected]+ 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: unauthorizedcontent:application/json:+ example:+ error:+ code: authentication_required+ message: Authentication requiredschema:"$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 ordertags:- - Reasons+ - Orderssecurity:- api_key: []bearer_auth: []- description: |-- Returns a single return reason by prefixed ID.-- **Required scope:** `read_settings` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -22109,32 +13304,217 @@ paths:schema:type: stringresponses:- '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+ email: [email protected]+ 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: objectproperties:- name:+ email:type: string- active:+ example: [email protected]+ 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 ordertags:- - Reasons+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -22162,61 +13544,140 @@ paths:description: Bearer token for admin authenticationschema: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: pathrequired: 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: stringresponses:'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+ email: [email protected]+ 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 ordertags:- - Staff+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -22246,110 +13706,191 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema: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: pathrequired: true+ description: Order IDschema:type: stringresponses:'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+ email: [email protected]+ 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_UkLWZg9DAJrequestBody:content:application/json:schema:type: objectproperties:- 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: arrayitems:- type: string+ type: object+ required:+ - variant_id+ properties:+ variant_id:+ type: string+ description: Variant ID+ quantity:+ type: integer+ example: 1+ metadata:+ type: objectdelete:- summary: Delete a role+ summary: Delete a draft ordertags:- - Staff+ - Orderssecurity:- 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: javascriptlabel: Spree Admin SDK@@ -22361,10 +13902,10 @@ paths:secretKey: 'sk_xxx',})- await client.roles.delete('role_abc123')+ await client.orders.delete('or_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /roles/{id}+ source: spree api delete /orders/{id}parameters:- name: x-spree-api-keyin: header@@ -22374,32 +13915,33 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Order IDschema:type: stringresponses:'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 ordertags:- - Seller Requirements+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -22426,55 +13968,157 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema: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 IDschema:- type: integer+ type: stringresponses:'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+ email: [email protected]+ 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 completedcontent:application/json:+ example:+ error:+ code: order_cannot_complete+ message: No payment found+ details:+ base:+ - No payment foundschema:- 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 ordertags:- - Seller Requirements+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -22509,81 +14151,145 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Order IDschema:type: stringresponses:- '201':- description: seller requirement created- content:- application/json:- schema:- "$ref": "#/components/schemas/SellerRequirement"- '422':- description: kind is not registered+ '200':+ description: order canceledcontent: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+ email: [email protected]+ 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_UkLWZg9DAJrequestBody:content:application/json:schema:type: object- required:- - typeproperties:- 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 ordertags:- - Seller Requirements+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /seller_requirements/types+ source: spree api patch /orders/{id}/approve -d '{ ... }'parameters:- name: x-spree-api-keyin: header@@ -22610,75 +14314,119 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Order IDschema:type: stringresponses:'200':- description: kinds found+ description: order approvedcontent: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+ email: [email protected]+ 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 emailtags:- - Seller Requirements+ - Orderssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -22707,54 +14451,119 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Order IDschema:type: stringresponses:'200':- description: seller requirement updated+ description: confirmation resentcontent: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+ email: [email protected]+ 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 methodstags:- - Seller Requirements+ - Payment Methodssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /seller_requirements/{id}+ source: spree api get /payment_methodsparameters:- name: x-spree-api-keyin: header@@ -22783,25 +14590,66 @@ paths:required: trueschema: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: stringresponses:- '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 typestags:- - Sellers+ - Payment Methodssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /sellers -d '{"page":1,"limit":25}'+ source: spree api get /payment_methods/typesparameters:- name: x-spree-api-keyin: header@@ -22828,79 +14674,41 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'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 foundcontent: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 methodtags:- - Sellers+ - Payment Methodssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -22932,84 +14735,60 @@ paths:required: trueschema: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: stringresponses:- '201':- description: seller created- content:- application/json:- schema:- "$ref": "#/components/schemas/Seller"- '422':- description: validation error+ '200':+ description: payment method foundcontent: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- example: [email protected]- nullable: true- billing_email:- type: string- example: [email protected]- 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 paymentstags:- - Sellers+ - Paymentssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /sellers/{id}+ source: spree api get /orders/{order_id}/paymentsparameters:- name: x-spree-api-keyin: header@@ -23034,35 +14813,88 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'200':- description: seller found- content:- application/json:- schema:- "$ref": "#/components/schemas/Seller"- '404':- description: seller not found+ description: payments foundcontent: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 paymenttags:- - Sellers+ - Paymentssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -23093,161 +14923,68 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order IDschema:type: stringresponses:- '200':- description: seller address written inline- content:- application/json:- schema:- "$ref": "#/components/schemas/Seller"- '422':- description: validation error+ '201':+ description: payment createdcontent: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_gbHJdmfrXBrequestBody:content:application/json:schema:type: object+ required:+ - payment_method_idproperties:- name:- type: string- example: Sparks Audio Ltd- billing_email:- type: string- example: [email protected]- 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 paymenttags:- - Sellers+ - Paymentssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /sellers/{id}+ source: spree api get /orders/{order_id}/payments/{id}parameters:- name: x-spree-api-keyin: header@@ -23274,37 +15009,84 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:- '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 paymenttags:- - Sellers+ - Paymentssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -23333,52 +15112,80 @@ paths:- name: Authorizationin: headerrequired: 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 IDschema:type: stringresponses:- '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 failedcontent: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:- properties:- email:- type: string- example: [email protected]- 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 paymenttags:- - Sellers+ - Paymentssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -23405,44 +15210,70 @@ paths:- name: Authorizationin: headerrequired: 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 IDschema:type: stringresponses:'200':- description: seller approved- content:- application/json:- schema:- "$ref": "#/components/schemas/Seller"- '422':- description: seller cannot be approved from its current status+ description: payment voidedcontent: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 liststags:- - Sellers+ - Pricingsecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api patch /sellers/{id}/suspend -d '{"reason":"Counterfeit goods"}'+ source: spree api get /price_listsparameters:- name: x-spree-api-keyin: header@@ -23473,43 +15300,111 @@ paths:required: trueschema: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: stringresponses:'200':- description: seller suspended+ description: price lists foundcontent: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 listtags:- - Sellers+ - Pricingsecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -23541,1485 +15467,17964 @@ paths:schema:type: stringresponses:- '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- - password- - country_code- properties:- setup_token:- type: string- description: One-time token from the install output.- email:- type: string- format: email- example: [email protected]- 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: enlocales:- - 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+ email: [email protected]+ 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+ email: [email protected]+ 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+ email: [email protected]+ 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+ email: [email protected]+ 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+ email: [email protected]+ 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:+ - role_id+ properties:+ email:+ type: string+ example: [email protected]+ 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+ email: [email protected]+ 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_UkLWZg9DAJcurrency: 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: percentagecurrency: 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+ email: [email protected]+ 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+ email: [email protected]+ 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+ example: [email protected]+ 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: 1Z879E930346830001currency: 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:+ - 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 productstags:- - Stock+ - Price Listssecurity:- 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-keyin: header@@ -25031,81 +33436,49 @@ paths:required: trueschema:type: string+ - name: price_list_id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: stock levels updated- '422':- description: row is missing a level+ description: products removed+ content:+ application/json:+ example:+ removed_count: 1requestBody:content:application/json:schema:type: object- required:- - stock_levelsproperties:- stock_levels:+ product_ids:type: arrayitems:- 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 typestags:- - Stock Locations+ - Product Typessecurity:- 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-keyin: header@@ -25130,54 +33503,39 @@ paths:description: Number of records per pageschema: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: stringresponses:'200':- description: stock locations found+ description: product types foundcontent: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: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/StockLocation"+ "$ref": "#/components/schemas/ProductType"meta:"$ref": "#/components/schemas/PaginationMeta"required:@@ -25187,48 +33545,29 @@ paths:description: unauthorizedcontent:application/json:+ example:+ error:+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"post:- summary: Create a stock location+ summary: Create a product typetags:- - Stock Locations+ - Product Typessecurity:- 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-keyin: header@@ -25243,15 +33582,32 @@ paths:type: stringresponses:'201':- description: stock location created+ description: product type createdcontent: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 entitycontent:application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blankschema:"$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: stringnullable: 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: integerrequired:- name- "/api/v3/admin/stock_locations/{id}":+ "/api/v3/admin/product_types/{id}":parameters:- name: idin: path+ description: Product type IDrequired: true- description: Stock location IDschema:type: stringget:- summary: Get a stock location+ summary: Retrieve a product typetags:- - Stock Locations+ - Product Typessecurity:- 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-keyin: header@@ -25380,60 +33681,48 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: fields- in: query- required: false- description: Comma-separated list of fields to include. id is always included.- schema:- type: stringresponses:'200':- description: stock location found+ description: product type foundcontent: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 foundcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Product type not foundschema:"$ref": "#/components/schemas/ErrorResponse"patch:- summary: Update a stock location+ summary: Update a product typetags:- - Stock Locations+ - Product Typessecurity:- 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-keyin: header@@ -25448,17 +33737,21 @@ paths:type: stringresponses:'200':- description: stock location updated- content:- application/json:- schema:- "$ref": "#/components/schemas/StockLocation"- '422':- description: validation error+ description: product type updatedcontent: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: stringnullable: 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: integerdelete:- summary: Delete a stock location+ summary: Delete a product typetags:- - Stock Locations+ - Product Typessecurity:- 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-keyin: header@@ -25568,38 +33808,75 @@ paths:type: stringresponses:'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 productstags:- - Stock Movements+ - Product Typessecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -25626,82 +33903,84 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- name: pagein: queryrequired: false- description: Page numberschema:type: integer- name: limitin: queryrequired: false- description: Number of records per pageschema: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: stringresponses:'200':- description: stock movements found+ description: seller requirements foundcontent: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: objectproperties:data:type: arrayitems:- "$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 requirementtags:- - Stock Movements+ - Seller Requirementssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -25726,40 +34015,101 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:- '200':- description: stock movement found+ '201':+ description: seller requirement createdcontent: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: trueschema:- "$ref": "#/components/schemas/StockMovement"- '404':- description: stock movement not found+ "$ref": "#/components/schemas/SellerRequirement"+ '422':+ description: kind is not registeredcontent:application/json:+ example:+ error:+ code: unknown_seller_requirement_type+ message: Unknown typeschema:"$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 kindstags:- - Settings+ - Seller Requirementssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /store+ source: spree api get /seller_requirements/typesparameters:- name: x-spree-api-keyin: header@@ -25784,33 +34136,239 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:'200':- description: current store- content:- application/json:- schema:- "$ref": "#/components/schemas/Store"- '401':- description: unauthorized+ description: kinds foundcontent: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: stringpatch:- summary: Update the current store+ summary: Update a seller requirementtags:- - Settings+ - Seller Requirementssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -25837,22 +34397,32 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:'200':- description: store updated- content:- application/json:- schema:- "$ref": "#/components/schemas/Store"- '422':- description: validation error+ description: seller requirement updatedcontent: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: falseschema:- "$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 requirementtags:- - Settings+ - Seller Requirementssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -25913,43 +34490,42 @@ paths:required: trueschema: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: stringresponses:- '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 sellerstags:- - Settings+ - Sellerssecurity:- 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-keyin: 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: queryrequired: false- description: Only rates included in the product price+ description: Filter by statusschema:- type: boolean+ type: string- name: sortin: queryrequired: false@@ -25994,16 +34570,58 @@ paths:type: stringresponses:'200':- description: tax rates found+ description: sellers foundcontent: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: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/TaxRate"+ "$ref": "#/components/schemas/Seller"meta:"$ref": "#/components/schemas/PaginationMeta"required:@@ -26013,380 +34631,178 @@ paths:description: unauthorizedcontent:application/json:+ example:+ error:+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"post:- summary: Create a tax rate+ summary: Create a sellertags:- - Settings+ - Sellerssecurity:- 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-keyin: headerrequired: trueschema: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: trueschema:type: stringresponses:- '200':- description: coverage found+ '201':+ description: seller createdcontent: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+ example: [email protected]+ nullable: true+ billing_email:+ type: string+ example: [email protected]+ 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: stringget:- summary: List product variants+ summary: Get a sellertags:- - Variants+ - Sellerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -26413,60 +34827,70 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'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 sellertags:- - Variants+ - Sellerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -26502,22 +34921,87 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: product_id- in: path- required: true- description: Product IDschema:type: stringresponses:- '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 errorcontent:application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blankschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -26526,100 +35010,140 @@ paths:schema:type: objectproperties:- sku:+ name:type: string- example: SKU-001- cost_price:+ example: Sparks Audio Ltd+ billing_email:type: string- example: '10.00'- cost_currency:+ example: [email protected]+ 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 sellertags:- - Variants+ - Sellerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -26646,56 +35170,37 @@ paths:- name: Authorizationin: headerrequired: 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 sellertags:- - Variants+ - Sellerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -26723,123 +35229,83 @@ paths:- name: Authorizationin: headerrequired: 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 IDschema:type: stringresponses:- '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: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:+ example: [email protected]+ 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 sellertags:- - Variants+ - Sellerssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api delete /products/{product_id}/variants/{id}+ source: spree api patch /sellers/{id}/approve -d '{ ... }'parameters:- name: x-spree-api-keyin: header@@ -26864,48 +35332,79 @@ paths:- name: Authorizationin: headerrequired: 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 IDschema:type: stringresponses:- '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: idin: pathrequired: true- description: Parent webhook endpoint ID+ description: Seller prefixed IDschema:type: string- get:- summary: List webhook deliveries+ patch:+ summary: Suspend a sellertags:- - Webhooks+ - Sellerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -26930,82 +35433,77 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'200':- description: deliveries found- '404':- description: parent webhook endpoint not found+ description: seller suspendedcontent: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: idin: pathrequired: true- description: Webhook delivery ID+ description: Seller prefixed IDschema:type: string- get:- summary: Get a webhook delivery+ patch:+ summary: Reject a sellertags:- - Webhooks+ - Sellerssecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -27030,55 +35532,80 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'200':- description: delivery found- '404':- description: delivery not found+ description: seller rejectedcontent: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 levelstags:- - Webhooks+ - Stocksecurity:- 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: javascriptlabel: 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: bashlabel: 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-keyin: header@@ -27106,28 +35638,93 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:- '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 movementstags:- - Webhooks+ - Stock Movementssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /webhook_endpoints+ source: spree api get /stock_movements -d '{"q":{"kind_eq":"allocated"}}'parameters:- name: x-spree-api-keyin: header@@ -27167,22 +35766,17 @@ paths:description: Number of records per pageschema: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: queryrequired: 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: queryrequired: false- description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).+ description: Filter by stock level, e.g. sl_1234567890schema:type: string- name: fields@@ -27193,30 +35787,23 @@ paths:type: stringresponses:'200':- description: webhook endpoints found+ description: stock movements foundcontent: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 countcreated_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: 1limit: 25@@ -27227,117 +35814,47 @@ paths:in: 1previous:next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/StockMovement"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta'401':description: unauthorizedcontent:application/json:+ example:+ error:+ code: authentication_required+ message: Authentication requiredschema:"$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: idin: pathrequired: true- description: Webhook endpoint ID+ description: Stock movement IDschema:type: stringget:- summary: Get a webhook endpoint+ summary: Get a stock movementtags:- - Webhooks+ - Stock Movementssecurity:- 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: javascriptlabel: 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: bashlabel: Spree CLI- source: spree api get /webhook_endpoints/{id}+ source: spree api get /stock_movements/{id}parameters:- name: x-spree-api-keyin: header@@ -27373,363 +35890,34 @@ paths:type: stringresponses:'200':- description: webhook endpoint found+ description: stock movement foundcontent: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 countcreated_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 foundcontent: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 foundschema:"$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 rateservers:- url: http://{defaultHost}variables:@@ -33946,6 +42134,9 @@ components:carrier:type: stringnullable: true+ carrier_name:+ type: string+ nullable: trueservice:type: stringnullable: true@@ -33974,9 +42165,6 @@ components:type: stringowner_type:type: string- carrier_name:- type: string- nullable: truecost:type: stringdisplay_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_iddiff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yamlindex 08fabb316e..accce17d1d 100644--- a/docs/api-reference/seller.yaml+++ b/docs/api-reference/seller.yaml@@ -81,12 +81,30 @@ paths:description: login successfulcontent:application/json:+ example:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjE5NWY4OTE2LWI3NGQtNDg2MS1hMTQ3LTJmMDhiMzhiMWIzNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.e2XwsDONtD0x4j9jfjnHhDhAJpzhXBQ2LuIjWS1kY1k+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ 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: approvedschema:"$ref": "#/components/schemas/AuthResponse"'401':description: invalid credentialscontent:application/json:+ example:+ error:+ code: authentication_failed+ message: Invalid email or passwordschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -129,12 +147,30 @@ paths:description: refresh successfulcontent:application/json:+ example:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjdjODEzNjdjLTBlYWEtNGUzOC1hNmRjLTJjMTYzOTIxY2Q1MiIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.N2ttey6pvsPoOdx0F9pdUNbdT1j25ejAzpghXTbB8zo+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ 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: approvedschema:"$ref": "#/components/schemas/AuthResponse"'401':description: missing or invalid refresh-token cookiecontent:application/json:+ example:+ error:+ code: invalid_refresh_token+ message: Refresh token cookie missingschema:"$ref": "#/components/schemas/ErrorResponse""/api/v3/seller/auth/logout":@@ -160,131 +196,242 @@ paths:description: providers listedcontent:application/json:+ example:+ providers:+ - key: email+ kind: passwordschema:"$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: stringget:- summary: List countries+ summary: Look up an invitationtags:- - Countries- security:- - bearer_auth: []+ - Authenticationdescription: |- 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: queryrequired: true+ description: The token from the emailed linkschema:type: stringresponses:'200':- description: countries listed+ description: invitation foundcontent:application/json:+ example:+ id: inv_UkLWZg9DAJ+ email: [email protected]+ 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 invitationtags:- - Delivery Methods- security:- - bearer_auth: []+ - Authenticationdescription: |- 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: queryrequired: true+ description: The token from the emailed linkschema: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: integerresponses:'200':- description: delivery methods listed+ description: invitation accepted, session issuedcontent:application/json:+ example:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs+ user:+ id: adm_gbHJdmfrXB+ email: [email protected]+ 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: approvedschema:- 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 resettags:- - Delivery Methods- security:- - bearer_auth: []+ - Authenticationdescription: |- 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+ example: [email protected]+ redirect_url:+ type: string+ example: https://sellers.your-store.com/reset-password+ description: Must match an allowed origin of the store; ignored+ otherwise.+ required:+ "/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 linkrequired: trueschema:type: stringresponses:- '201':- description: delivery method created+ '200':+ description: password resetcontent:application/json:+ example:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImJjMDM3NTNhLTEzN2MtNGM1Zi1hMzM2LWUzMjBlZTNiMjQ5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.EASrzbGpJVyAl10SJyzs8na68Wmvedkm7G66wTBq_0k+ user:+ id: adm_UkLWZg9DAJ+ email: [email protected]+ 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: approvedschema:- "$ref": "#/components/schemas/DeliveryMethod"+ "$ref": "#/components/schemas/AuthResponse"'422':- description: invalid request+ description: invalid or expired tokencontent: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: objectproperties:- 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+ email: [email protected]+ 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 shipsstorefront_visible:type: booleantracking_url:@@ -359,6 +12532,29 @@ paths:description: delivery method foundcontent: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 updatedcontent: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 listedcontent: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: objectproperties:@@ -493,6 +12736,80 @@ paths:description: calculators listedcontent: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: objectproperties:@@ -549,6 +12866,26 @@ paths:description: delivery profiles listedcontent: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: objectproperties:@@ -604,6 +12941,23 @@ paths:description: delivery zones listedcontent: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: objectproperties:@@ -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 checklisttags:- - Uploads+ - Onboardingsecurity:- 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-Idin: header@@ -644,58 +12998,43 @@ paths:schema:type: stringresponses:- '201':- description: upload target created+ '200':+ description: checklist returnedcontent: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 reviewtags:- - Exports+ - Onboardingsecurity:- 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-Idin: header@@ -703,65 +13042,56 @@ paths:schema:type: stringresponses:- '201':- description: export queued+ '200':+ description: submitted for reviewcontent: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 outstandingcontent:application/json:+ example:+ error:+ code: processing_error+ message: Requirements Accept terms is not completeschema:"$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_idin: path- description: Export ID+ description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`required: trueschema:type: string- get:- summary: Get an export+ post:+ summary: Submit against a requirementtags:- - Exports+ - Onboardingsecurity:- 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-Idin: header@@ -769,37 +13099,70 @@ paths:schema:type: stringresponses:- '200':- description: export found+ '201':+ description: submission recordedcontent: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 marketplacecontent:application/json:+ example:+ error:+ code: record_not_found+ message: Seller requirement not foundschema:"$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: idin: path- description: Export ID+ description: Submission IDrequired: trueschema:type: stringget:- summary: Download an export+ summary: Download a submitted documenttags:- - Exports+ - Onboardingsecurity:- 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-Idin: header@@ -807,87 +13170,97 @@ paths:schema:type: stringresponses:- '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 submissioncontent:- 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 policiestags:- - Fulfillments+ - Policiessecurity:- 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-Idin: headerrequired: trueschema: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: integerresponses:'200':- description: fulfillments listed+ description: policies listedcontent: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: objectproperties:data:type: arrayitems:- "$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 policytags:- - Fulfillments+ - Policiessecurity:- 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-Idin: header@@ -895,309 +13268,509 @@ paths:schema:type: stringresponses:- '200':- description: parcel shipped+ '201':+ description: policy createdcontent: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: objectproperties:- 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: idin: path- description: Invitation ID from the emailed linkrequired: true+ description: Policy prefixed ID or slugschema:type: stringget:- summary: Look up an invitation+ summary: Get a policytags:- - 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: headerrequired: true- description: The token from the emailed linkschema:type: stringresponses:'200':- description: invitation found+ description: policy foundcontent: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 foundcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Policy not foundschema:"$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 policytags:- - 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: headerrequired: true- description: The token from the emailed linkschema:type: stringresponses:'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 updatedcontent: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: objectproperties:- 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 typestags:- - Team+ - Product Typessecurity:- 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-Idin: headerrequired: trueschema: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: integerresponses:'200':- description: invitations listed+ description: product types listedcontent: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: objectproperties:data:type: arrayitems:- "$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 typetags:- - Team+ - Product Typessecurity:- 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-Idin: headerrequired: trueschema:type: string+ - name: id+ in: path+ required: true+ description: Product type ID+ schema:+ type: stringresponses:'200':- description: invitation resent- content:- application/json:- schema:- "$ref": "#/components/schemas/Invitation"- '404':- description: another seller's invitation+ description: product type foundcontent: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 productstags:- - Team+ - Productssecurity:- 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: headerrequired: trueschema: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: stringresponses:- '204':- description: invitation revoked- '404':- description: another seller's invitation+ '200':+ description: products listedcontent: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 producttags:- - Account+ - Productssecurity:- 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-Idin: header- required: false- description: The seller to report capability for. Omit to list sellers without- narrowing permissions.+ required: trueschema:type: stringresponses:- '200':- description: current user returned+ '201':+ description: product createdcontent: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_UkLWZg9DAJschema:- "$ref": "#/components/schemas/SellerMeResponse"- '401':- description: missing or invalid token+ "$ref": "#/components/schemas/Product"+ '422':+ description: validation failedcontent:application/json:example:error:- code: authentication_required- message: Authentication required+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blankschema:"$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: stringget:- summary: Get onboarding checklist+ summary: Get a producttags:- - Onboarding+ - Productssecurity:- 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-Idin: header@@ -1206,32 +13779,77 @@ paths:type: stringresponses:'200':- description: checklist returned+ description: product returnedcontent: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_UkLWZg9DAJschema:- "$ref": "#/components/schemas/SellerOnboardingResponse"- '403':- description: no seller named, or not a member of it+ "$ref": "#/components/schemas/Product"+ '404':+ description: another seller's productcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Product not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/seller/onboarding/submit_for_review":- post:- summary: Submit for review+ patch:+ summary: Update a producttags:- - Onboarding+ - Productssecurity:- 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-Idin: header@@ -1240,95 +13858,112 @@ paths:type: stringresponses:'200':- description: submitted for review- content:- application/json:- schema:- "$ref": "#/components/schemas/SellerOnboardingResponse"- '422':- description: something required is still outstanding+ description: product updatedcontent: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_UkLWZg9DAJschema:- "$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 producttags:- - Orders+ - Productssecurity:- 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-Idin: headerrequired: trueschema: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: stringresponses:- '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 profiletags:- - Orders+ - Profilesecurity:- 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-Idin: header@@ -1337,135 +13972,122 @@ paths:type: stringresponses:'200':- description: order found+ description: profile returnedcontent: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: 0schema:- "$ref": "#/components/schemas/Order"- '404':- description: another seller's order+ "$ref": "#/components/schemas/Profile"+ '403':+ description: no seller named, or not a member of itcontent: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: stringpatch:- summary: Cancel an order+ summary: Update profiletags:- - Orders+ - Profilesecurity:- 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- example: [email protected]- redirect_url:- type: string- example: https://sellers.your-store.com/reset-password- description: Must match an allowed origin of the store; ignored- otherwise.- required:- "/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: headerrequired: trueschema:type: stringresponses:'200':- description: password reset+ description: profile updatedcontent: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: 0schema:- "$ref": "#/components/schemas/AuthResponse"+ "$ref": "#/components/schemas/Profile"'422':- description: invalid or expired token+ description: validation failedcontent: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 blankschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -1474,29 +14096,68 @@ paths:schema:type: objectproperties:- 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+ example: [email protected]+ billing_email:+ type: string+ format: email+ nullable: true+ example: [email protected]+ 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 locationstags:- - Policies+ - Stock Locationssecurity:- 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-Idin: 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: stringresponses:'200':- description: policies listed+ description: stock locations listedcontent: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: objectproperties:data:type: arrayitems:- "$ref": "#/components/schemas/Policy"+ "$ref": "#/components/schemas/StockLocation"meta:"$ref": "#/components/schemas/PaginationMeta"required:- data- metapost:- summary: Create a policy+ summary: Create a stock locationtags:- - Policies+ - Stock Locationssecurity:- 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-Idin: header@@ -1552,11 +14250,45 @@ paths:type: stringresponses:'201':- description: policy created+ description: stock location createdcontent: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: warehouserequired:- name- "/api/v3/seller/policies/{id}":+ "/api/v3/seller/stock_locations/{id}":parameters:- name: idin: path+ description: Stock location IDrequired: true- description: Policy prefixed ID or slugschema:type: stringget:- summary: Get a policy+ summary: Get a stock locationtags:- - Policies+ - Stock Locationssecurity:- 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-Idin: header@@ -1597,24 +14365,54 @@ paths:type: stringresponses:'200':- description: policy found+ description: stock location returnedcontent: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 locationcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Stock location not foundschema:"$ref": "#/components/schemas/ErrorResponse"patch:- summary: Update a policy+ summary: Update a stock locationtags:- - Policies+ - Stock Locationssecurity:- 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-Idin: header@@ -1623,11 +14421,32 @@ paths:type: stringresponses:'200':- description: policy updated+ description: stock location updatedcontent: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 invitationstags:- - Products+ - Teamsecurity:- 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-Idin: headerrequired: trueschema: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: stringresponses:'200':- description: products listed+ description: invitations listedcontent:application/json:+ example:+ data:+ - id: inv_UkLWZg9DAJ+ email: [email protected]+ 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: objectproperties:data:type: arrayitems:- "$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 invitationtags:- - Products+ - Teamsecurity:- 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-Idin: header@@ -1807,95 +14547,76 @@ paths:schema:type: stringresponses:- '201':- description: product created+ '200':+ description: invitation resentcontent:application/json:+ example:+ id: inv_UkLWZg9DAJ+ email: [email protected]+ 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 invitationcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Invitation not foundschema:"$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: idin: path- description: Product ID+ description: Invitation IDrequired: trueschema: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 memberstags:- - Products+ - Teamsecurity:- 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-Idin: header@@ -1904,24 +14625,43 @@ paths:type: stringresponses:'200':- description: product returned- content:- application/json:- schema:- "$ref": "#/components/schemas/Product"- '404':- description: another seller's product+ description: team members listedcontent:application/json:+ example:+ data:+ - id: adm_UkLWZg9DAJ+ email: [email protected]+ 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 membertags:- - Products+ - Teamsecurity:- 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-Idin: header@@ -1929,46 +14669,66 @@ paths:schema:type: stringresponses:- '200':- description: product updated+ '201':+ description: invitation sentcontent:application/json:+ example:+ id: inv_UkLWZg9DAJ+ email: [email protected]+ 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+ example: [email protected]+ required:+ "/api/v3/seller/team/{id}":+ parameters:+ - name: id+ in: path+ description: Team member (user) ID+ required: true+ schema:+ type: stringdelete:- summary: Delete a product+ summary: Remove a team membertags:- - Products+ - Teamsecurity:- 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-Idin: header@@ -1977,20 +14737,49 @@ paths:type: stringresponses:'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 uploadtags:- - Profile+ - Uploadssecurity:- 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-Idin: header@@ -1998,39 +14787,64 @@ paths:schema:type: stringresponses:- '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 createdcontent:application/json:+ example:+ direct_upload:+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--e33ffe2f2fc04d65ca4ba6c757dd23060ca71420+ headers:+ Content-Type: application/pdf+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--ee384b06b9035e678160c88fe35ccc8036485072schema:- "$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 exporttags:- - Profile+ - Exportssecurity:- 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-Idin: header@@ -2038,16 +14852,32 @@ paths:schema:type: stringresponses:- '200':- description: profile updated+ '201':+ description: export queuedcontent: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 sellercontent: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: objectproperties:- name:- type: string- example: Acme Supplies- contact_email:- type: string- format: email- nullable: true- example: [email protected]- billing_email:- type: string- format: email- nullable: true- example: [email protected]- 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: idin: path- description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`+ description: Export IDrequired: trueschema:type: string- post:- summary: Submit against a requirement+ get:+ summary: Get an exporttags:- - Onboarding+ - Exportssecurity:- 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-Idin: headerrequired: trueschema:type: string- responses:- '201':- description: submission recorded+ responses:+ '200':+ description: export foundcontent: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 exportcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Export not foundschema:"$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: idin: path- description: Submission ID+ description: Export IDrequired: trueschema:type: stringget:- summary: Download a submitted document+ summary: Download an exporttags:- - Onboarding+ - Exportssecurity:- 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-Idin: header@@ -2197,76 +14988,132 @@ paths:schema:type: stringresponses:+ '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 exportcontent:- 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: stringget:- summary: List stock locations+ summary: List fulfillmentstags:- - Stock Locations+ - Fulfillmentssecurity:- 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-Idin: headerrequired: trueschema: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: stringresponses:'200':- description: stock locations listed+ description: fulfillments listedcontent: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: objectproperties:data:type: arrayitems:- "$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 parceltags:- - Stock Locations+ - Fulfillmentssecurity:- 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-Idin: header@@ -2274,86 +15121,273 @@ paths:schema:type: stringresponses:- '201':- description: stock location created- content:- application/json:- schema:- "$ref": "#/components/schemas/StockLocation"- '422':- description: validation failed+ '200':+ description: parcel shippedcontent: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: objectproperties:- 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: idin: path- description: Stock location ID+ description: Prefixed order IDrequired: trueschema:type: stringget:- summary: Get a stock location+ summary: Get an ordertags:- - Stock Locations+ - Orderssecurity:- 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-Idin: header@@ -2362,50 +15396,149 @@ paths:type: stringresponses:'200':- description: stock location returned+ description: order foundcontent: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 Yorkschema:- "$ref": "#/components/schemas/StockLocation"+ "$ref": "#/components/schemas/Order"'404':- description: another seller's stock location+ description: another seller's ordercontent:application/json:+ example:+ error:+ code: order_not_found+ message: Order not foundschema:"$ref": "#/components/schemas/ErrorResponse"+ "/api/v3/seller/orders/{id}/cancel":+ parameters:+ - name: id+ in: path+ description: Prefixed order ID+ required: true+ schema:+ type: stringpatch:- summary: Update a stock location+ summary: Cancel an ordertags:- - Stock Locations+ - Orderssecurity:- 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-Idin: header@@ -2414,42 +15547,129 @@ paths:type: stringresponses:'200':- description: stock location updated+ description: order canceledcontent: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 Yorkschema:- "$ref": "#/components/schemas/StockLocation"+ "$ref": "#/components/schemas/Order"requestBody:content:application/json:schema:type: objectproperties:- 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 registrationtags:@@ -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 registrationrequestBody: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- example: [email protected]- required:- "/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 sellercontent: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: stringnullable: true+ carrier_name:+ type: string+ nullable: trueservice:type: stringnullable: true@@ -4752,9 +17906,6 @@ components:type: stringowner_type:type: string- carrier_name:- type: string- nullable: truecost:type: stringdisplay_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_iddiff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 49e1b2edf2..875d691dc8 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -40,15 +40,26 @@ info:```version: v3paths:- "/api/v3/store/customers/me/addresses":- get:- summary: List customer addresses+ "/api/v3/store/auth/login":+ post:+ summary: Logintags:- - Customers+ - Authenticationsecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema: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: stringresponses:'200':- description: addresses found+ description: login successfulcontent:application/json:+ example:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImRlZmM5YWZhLTUzOTYtNDEwYy1hZDY4LTE4YTBiN2M5MmMwMyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.ha-8UOgpGEgYAVWjEqzhLZ9LPtI6uTlsDB3We7qbrdU+ refresh_token: CxKP3VYWQzkXqrfxTmPLB446+ user:+ id: cust_UkLWZg9DAJ+ email: [email protected]+ 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 keycontent:application/json:+ example:+ error:+ code: invalid_token+ message: Valid API key requiredschema:"$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:+ default: email+ email:+ type: string+ format: email+ example: [email protected]+ password:+ type: string+ example: password123+ required:+ - 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:+ required:+ - provider+ additionalProperties: true+ "/api/v3/store/auth/refresh":post:- summary: Create an address+ summary: Refresh tokentags:- - Customers+ - Authenticationsecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: stringresponses:- '201':- description: address created+ '200':+ description: token refreshedcontent:application/json:+ example:+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFmMzM5OGY2LTczZDgtNDdjNi1hNDk4LTUxNDc3MGUxYTUyNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.Zpvl-ISrctLW34O3zJFteOf3wMDNvlymVKsbkCIfeew+ refresh_token: mWbQ77onTSsXQta8Z4SAVaTU+ user:+ id: cust_UkLWZg9DAJ+ email: [email protected]+ 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 tokencontent:application/json:+ example:+ error:+ code: invalid_refresh_token+ message: Invalid or expired refresh tokenschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -178,66 +229,21 @@ paths:schema:type: objectproperties:- 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 responserequired:- - 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: Logouttags:- - Customers+ - Authenticationsecurity:- 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: javascriptlabel: 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: trueschema: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: stringresponses:- '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 resettags:- - Customers+ - Authenticationsecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: stringresponses:- '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: objectproperties:- first_name:- type: string- example: John- last_name:- type: string- example: Doe- address1:+ email:type: string- example: 456 Oak Ave- city:+ format: email+ example: [email protected]+ 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:+ "/api/v3/store/password_resets/{token}":+ patch:+ summary: Reset password with tokentags:- - Customers+ - Authenticationsecurity:- 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: javascriptlabel: 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: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id+ - name: tokenin: pathrequired: true+ description: Password reset token from the emailschema:type: stringresponses:- '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+ email: [email protected]+ 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 mismatchcontent:application/json:+ example:+ error:+ code: validation_error+ message: Password confirmation doesn't match Password+ details:+ password_confirmation:+ - doesn't match Passwordschema:"$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 categoriestags:- - Authentication+ - Product Catalogsecurity:- 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 storex-codeSamples:- lang: javascriptlabel: 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: trueschema: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:- default: email- email:- type: string- format: email- example: [email protected]- password:- type: string- example: password123- required:- - 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:- 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: stringresponses:'200':- description: token refreshed+ description: categories foundcontent: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: unauthorizedcontent:application/json:+ example:+ error:+ code: invalid_token+ message: Valid API key requiredschema:"$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 categorytags:- - Authentication+ - Product Catalogsecurity:- 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 IDx-codeSamples:- lang: javascriptlabel: 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: trueschema: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: stringresponses:- '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 collectionstags:- - Carts+ - Product Catalogsecurity:- 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true- schema:- type: string- name: pagein: queryrequired: false- description: 'Page number (default: 1)'schema:type: integer- name: limitin: queryrequired: 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: queryrequired: false- description: Filter by created after date (ISO 8601)+ description: Filter by nameschema:type: string- - name: q[updated_at_gt]+ - name: fieldsin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'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 foundcontent: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: 1999compare_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: 1limit: 25- count: 2+ count: 1pages: 1from: 1- to: 2- in: 2+ to: 1+ in: 1previous:next:- '401':- description: unauthorized- content:- application/json:- example:- error:- code: authentication_required- message: Authentication requiredschema:- "$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 productstags:- - Carts+ - Product Catalogsecurity:- 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 storex-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: true+ description: Publishable API keyschema:type: string- - name: Authorization- in: header+ - name: page+ in: queryrequired: 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: queryrequired: 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: stringresponses:- '201':- description: cart created+ '200':+ description: products foundcontent: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 producttags:- - Carts+ - Product Catalogsecurity:- 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 IDx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: true- schema:- type: string- - name: Authorization- in: header- required: false- schema:- type: string- - name: x-spree-token- in: header- required: false+ description: Publishable API keyschema:type: string- name: idin: pathrequired: 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: expandin: queryrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: cart with out-of-stock item removed (warnings returned)+ description: product without prior_price expanded does not include fieldcontent: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 visiblecontent:application/json:+ example:+ error:+ code: record_not_found+ message: Product not foundschema:"$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update a cart+ "/api/v3/store/products/filters":+ get:+ summary: Get product filterstags:- - Carts+ - Product Catalogsecurity:- 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: javascriptlabel: 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-keyin: headerrequired: true+ description: Publishable API keyschema:type: string- - name: Authorization- in: header- required: false- schema:- type: string- - name: x-spree-token- in: header+ - name: category_id+ in: queryrequired: false+ description: Scope filters to products in this category (prefix ID)schema:type: string- - name: Idempotency-Key- in: header+ - name: q[name_cont]+ in: queryrequired: false- schema:- type: string- - name: id- in: path- required: true- description: Cart prefixed ID+ description: Filter by name containing stringschema:type: stringresponses:'200':- description: cart updated+ description: filters scoped to categorycontent: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- example: [email protected]- 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 cartstags:- Cartssecurity:- api_key: []bearer_auth: []- description: Deletes/abandons the cart.+ description: Returns all active (incomplete) carts for the authenticated user.x-codeSamples:- lang: javascriptlabel: 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: Authorizationin: 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: queryrequired: 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: queryrequired: 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: stringresponses:- '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: javascriptlabel: 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: Authorizationin: header- required: true+ required: false+ description: Bearer JWT token (optional - for authenticated customers)schema:type: string- - name: x-spree-token+ - name: Idempotency-Keyin: 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 createdcontent: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:+ - enschema:- "$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 carttags:- Cartssecurity:- 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: javascriptlabel: 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: idin: pathrequired: 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: stringresponses:'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:+ - enschema:- "$ref": "#/components/schemas/Order"- '422':- description: cannot complete+ "$ref": "#/components/schemas/Cart"+ '404':+ description: cart not foundcontent:application/json:+ example:+ error:+ code: record_not_found+ message: Cart not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/categories":- get:- summary: List categories+ patch:+ summary: Update a carttags:- - Product Catalog+ - Cartssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: page- in: query+ - name: Authorization+ in: headerrequired: falseschema:- type: integer- - name: limit- in: query+ type: string+ - name: x-spree-token+ in: headerrequired: falseschema:- type: integer- - name: q[name_cont]- in: query+ type: string+ - name: Idempotency-Key+ in: headerrequired: false- description: Filter by nameschema: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 IDschema:type: stringresponses:'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 updatedcontent: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:+ - enschema:- "$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+ example: [email protected]+ 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 carttags:- - Product Catalog+ - Cartssecurity:- api_key: []- description: Returns a single category by permalink or prefix ID+ bearer_auth: []+ description: Deletes/abandons the cart.x-codeSamples:- lang: javascriptlabel: 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: trueschema: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: headerrequired: false- description: Expand associations (children, parent, ancestors, custom_fields)schema:type: string- - name: fields- in: query+ - name: x-spree-token+ in: headerrequired: 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 IDschema:type: stringresponses:- '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 usertags:- - Channel+ - Cartssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: X-Spree-Channel+ - name: Authorizationin: 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 IDschema:type: stringresponses:'200':- description: channel found+ description: cart associated successfullycontent: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+ email: [email protected]+ 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:+ - enschema:- "$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 matchcontent: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 carttags:- - Product Catalog+ - Cartssecurity:- 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-keyin: headerrequired: trueschema:type: string- - name: page- in: query- required: false- schema:- type: integer- - name: limit- in: query+ - name: Authorization+ in: headerrequired: falseschema:- type: integer- - name: q[name_cont]- in: query+ type: string+ - name: x-spree-token+ in: headerrequired: false- description: Filter by nameschema: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 IDschema:type: stringresponses:'200':- description: collections found+ description: cart completedcontent: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+ email: [email protected]+ 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 completecontent: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 codetags:- - Product Catalog+ - Cartssecurity:- 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-keyin: headerrequired: trueschema: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: headerrequired: false- description: Comma-separated list of fields to include. id is always included.+ description: Bearer token for authenticated customersschema: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-tokenin: header- required: true+ required: false+ description: Order token for guest accessschema:type: string- - name: collection_id+ - name: cart_idin: pathrequired: 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: headerrequired: 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: integerresponses:- '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 codecontent: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 codetags:- - Companies+ - Cartssecurity:- 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: javascriptlabel: 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-keyin: header@@ -1797,134 +3148,191 @@ paths:type: string- name: Authorizationin: 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 customersschema:type: string- - name: Authorization- in: header+ - name: cart_id+ in: pathrequired: true+ description: Cart prefixed IDschema: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: pathrequired: true+ description: The discount code string to remove (e.g., SAVE10)schema:type: string- - name: Authorization+ - name: x-spree-tokenin: header- required: true+ required: false+ description: Order token for guest accessschema:type: stringresponses:'200':- description: company updated+ description: discount code removedcontent: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 fulfillmenttags:- - Companies+ - Cartssecurity:- 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-keyin: header@@ -1933,41 +3341,274 @@ paths:type: string- name: Authorizationin: header+ required: false+ schema:+ type: string+ - name: cart_id+ in: path+ required: true+ description: Cart prefixed ID+ schema:+ type: string+ - name: id+ in: pathrequired: true+ description: Fulfillment ID+ schema:+ type: string+ - name: x-spree-token+ in: header+ required: false+ description: Order token for guest accessschema:type: stringresponses:'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+ email: [email protected]+ 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 foundcontent:application/json:example:- data:- - id: cmem_UkLWZg9DAJ- company_id: comp_UkLWZg9DAJ- customer_id: cust_UkLWZg9DAJ- email: [email protected]- 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 cardtags:- - Companies+ - Cartssecurity:- 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: javascriptlabel: 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-keyin: header@@ -1994,154 +3631,247 @@ paths:type: string- name: Authorizationin: header- required: true+ required: false+ description: Bearer token for authenticated customersschema: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- email: [email protected]- requestBody:- content:- application/json:- schema:- type: object- properties:- customer_email:- type: string- example: [email protected]- 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-tokenin: header+ required: false+ description: Order token for guest access+ schema:+ type: string+ - name: cart_id+ in: pathrequired: true+ description: Cart prefixed ID (e.g., cart_abc123)schema:type: string- - name: Authorization+ - name: Idempotency-Keyin: header- required: true+ required: false+ description: Unique key for request idempotency.schema:type: stringresponses:- '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 foundcontent: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: objectproperties:- 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 cardtags:- - Companies+ - Cartssecurity:- 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-keyin: header@@ -2150,438 +3880,449 @@ paths:type: string- name: Authorizationin: 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 customersschema:type: string- - name: Authorization- in: header+ - name: cart_id+ in: pathrequired: true+ description: Cart prefixed IDschema: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: pathrequired: true+ description: Gift card prefixed ID (e.g., gc_abc123)schema:type: string- - name: Authorization+ - name: x-spree-tokenin: header- required: true+ required: false+ description: Order token for guest accessschema:type: stringresponses:'200':- description: orders listed+ description: gift card removedcontent: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- email: [email protected]- 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: 1currency: 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 carttags:- - Companies+ - Cartssecurity:- 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-keyin: headerrequired: trueschema: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: stringresponses:- '200':- description: invitation found+ '201':+ description: item added with metadatacontent:application/json:example:- id: cinv_UkLWZg9DAJ- email: [email protected]- 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 foundcontent: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 rulecontent:application/json:example:- id: cmem_UkLWZg9DAJ- company_id: comp_UkLWZg9DAJ- customer_id: cust_UkLWZg9DAJ- email: [email protected]+ 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: objectproperties:- 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 quantitytags:- - Markets+ - Cartssecurity:- 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 cartx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema: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: Authorizationin: 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: queryrequired: 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 warningscontent: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:+ - enschema:- "$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 carttags:- - Customers+ - Cartssecurity:- 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 cartx-codeSamples:- lang: javascriptlabel: 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-keyin: header@@ -2758,79 +4544,133 @@ paths:type: string- name: Authorizationin: header- required: true+ required: falseschema:type: string- - name: page- in: query- required: false+ - name: cart_id+ in: path+ required: true+ description: Cart prefixed IDschema:- type: integer- - name: limit- in: query- required: false+ type: string+ - name: id+ in: path+ required: trueschema:- type: integer- - name: fields- in: query+ type: string+ - name: x-spree-token+ in: headerrequired: false- description: Comma-separated list of fields to include (e.g., name,slug,price).- id is always included.schema:type: stringresponses:'200':- description: credit cards found+ description: line item removed, returns updated cartcontent: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:+ - enschema:- 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 foundcontent:application/json:example:error:- code: authentication_required- message: Authentication required+ code: line_item_not_found+ message: Line item not foundschema:"$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 sessiontags:- - Customers+ - Cartssecurity:- 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: javascriptlabel: 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-keyin: header@@ -2853,55 +4699,115 @@ paths:type: string- name: Authorizationin: header- required: true+ required: false+ description: Bearer token for authenticated customersschema:type: string- - name: id+ - name: cart_idin: pathrequired: true+ description: Cart prefixed ID (e.g., cart_abc123)schema:type: string- - name: fields- in: query+ - name: x-spree-token+ in: headerrequired: 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: stringresponses:- '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 createdcontent: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: trueschema:- "$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 sessiontags:- - Customers+ - Cartssecurity:- 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: javascriptlabel: 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: stringresponses:- '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 foundcontent:application/json:example:error:code: record_not_found- message: Credit card not found+ message: Payment session not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/currencies":- get:- summary: List supported currencies+ patch:+ summary: Update payment sessiontags:- - Markets+ - Cartssecurity:- 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: javascriptlabel: 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 updatedcontent: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: trueschema:- "$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 sessiontags:- - Authentication+ - Cartssecurity:- 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: javascriptlabel: 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-Keyin: header- required: true+ required: false+ description: Unique key for request idempotency.schema:type: stringresponses:- '202':- description: email not found (same response to prevent enumeration)+ '200':+ description: payment session completedcontent: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: trueschema:- type: object- properties:- message:- type: string- '401':- description: missing API key+ "$ref": "#/components/schemas/PaymentSession"+ '404':+ description: payment session not foundcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: record_not_found+ message: Payment session not foundschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -3072,28 +5041,23 @@ paths:schema:type: objectproperties:- email:- type: string- format: email- example: [email protected]- 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:- "/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 paymenttags:- - Authentication+ - Cartssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: token+ - name: Authorization+ in: header+ required: false+ schema:+ type: string+ - name: cart_idin: pathrequired: 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 accessschema:type: stringresponses:- '200':- description: password reset successful+ '201':+ description: payment createdcontent:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjdlOGI2Njc5LTBjNzYtNDQ1Mi1hMWMyLWJhY2U0MWNhN2IyMCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzY4NDgyMDAwfQ.grC4diUECUp8b3p6jJBHAZp_MyiSUQwA4rdQLel_zuM- refresh_token: JNJKeT5cELhdSfb2tWHj3ctp- user:- id: cust_UkLWZg9DAJ- email: [email protected]- 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: falseschema:- "$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 methodcontent: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: objectproperties:- 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 paymentrequired:- - 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 credittags:- - Customers+ - Cartssecurity:- 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: javascriptlabel: 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-keyin: header@@ -3224,351 +5191,200 @@ paths:required: trueschema: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: headerrequired: 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: headerrequired: 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: stringresponses:'200':- description: orders listed+ description: store credit appliedcontent: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- email: [email protected]- 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: 1currency: 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:+ - enschema:- 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 availablecontent:application/json:example:error:- code: authentication_required- message: Authentication required+ code: processing_error+ message: User does not have any Store Credits availableschema:"$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 credittags:- - Customers+ - Cartssecurity:- api_key: []bearer_auth: []- description: Returns a single completed order for the authenticated customer.+ description: Removes store credit from the cart.x-codeSamples:- lang: javascriptlabel: 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-keyin: header@@ -3598,52 +5410,42 @@ paths:required: trueschema:type: string- - name: id+ - name: cart_idin: pathrequired: 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 IDschema:type: string- - name: fields- in: query+ - name: x-spree-token+ in: headerrequired: false- description: Comma-separated list of fields to include (e.g., total,amount_due,item_count).- id is always included.schema:type: stringresponses:'200':- description: order found+ description: store credit removedcontent:application/json:example:- id: or_UkLWZg9DAJ+ id: cart_UkLWZg9DAJmarket_id: mkt_UkLWZg9DAJ- cart_id:channel_id: ch_UkLWZg9DAJ+ preferred_stock_location_id:company_id:company_name:+ po_number_required: falsepo_document_filename:po_document_byte_size:- number: R1001- email: [email protected]+ number: cart_UkLWZg9DAJ+ token: BHWevnp2PQxC1jSWU3ZFLejT+ email:customer_note:po_number:currency: USDlocale: entotal_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: truediscounts: []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 Yorkshipping_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:- enschema:- "$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- email: [email protected]- 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- email: [email protected]- 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- example: [email protected]- 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:- - password- "/api/v3/store/customers/me":+ "$ref": "#/components/schemas/Cart"+ "/api/v3/store/orders/{id}":get:- summary: Get current customer profile+ summary: Get an ordertags:- - Customers+ - Orderssecurity:- 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: javascriptlabel: 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-keyin: header@@ -4004,39 +5579,214 @@ paths:type: string- name: Authorizationin: header+ required: false+ description: Bearer token for authenticated customers+ schema:+ type: string+ - name: id+ in: pathrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: profile found+ description: order found (guest via order token)content:application/json:example:- id: cust_UkLWZg9DAJ- email: [email protected]- 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+ email: [email protected]+ 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_UkLWZg9DAJlabel:first_name: Johnlast_name: Doefull_name: John Doe- address1: 75 Lovely Street+ address1: 326 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4048,60 +5798,17 @@ paths:state_code: NYquick_checkout: falseis_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: trueis_default_shipping: falsestate_abbr: NYcountry_iso: USstate_name: New York- default_billing_address:+ shipping_address:id: addr_gbHJdmfrXBlabel:first_name: Johnlast_name: Doefull_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 Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4113,32 +5820,43 @@ paths:state_code: NYquick_checkout: falseis_default_billing: false- is_default_shipping: true+ is_default_shipping: falsestate_abbr: NYcountry_iso: USstate_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:+ - enschema:- "$ref": "#/components/schemas/Customer"- '401':- description: unauthorized - invalid token+ "$ref": "#/components/schemas/Order"+ '404':+ description: incomplete order not accessiblecontent:application/json:example:error:- code: authentication_required- message: Authentication required+ code: order_not_found+ message: Order not foundschema:"$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update current customer profile+ "/api/v3/store/customers/me/addresses":+ get:+ summary: List customer addressestags:- Customerssecurity:- api_key: []bearer_auth: []- description: Updates the profile of the currently authenticated customer+ description: Returns all addresses in the customer address bookx-codeSamples:- lang: javascriptlabel: 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: headerrequired: trueschema:- 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: stringresponses:'200':- description: profile updated+ description: addresses foundcontent:application/json:example:- id: cust_UkLWZg9DAJ- email: [email protected]- 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_UkLWZg9DAJlabel:first_name: Johnlast_name: Doefull_name: John Doe- address1: 77 Lovely Street+ address1: 144 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4213,29 +5935,7 @@ paths:first_name: Johnlast_name: Doefull_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 Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4251,13 +5951,12 @@ paths:state_abbr: NYcountry_iso: USstate_name: New York- default_shipping_address:- id: addr_UkLWZg9DAJ+ - id: addr_EfhxLZ9ck8label:first_name: Johnlast_name: Doefull_name: John Doe- address1: 77 Lovely Street+ address1: 146 Lovely Streetaddress2: Northwestpostal_code: '10118'city: New York@@ -4269,129 +5968,47 @@ paths:state_code: NYquick_checkout: falseis_default_billing: false- is_default_shipping: true+ is_default_shipping: falsestate_abbr: NYcountry_iso: USstate_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- example: [email protected]- 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: falsemeta:page: 1limit: 25- count: 1+ count: 3pages: 1from: 1- to: 1- in: 1+ to: 3+ in: 3previous: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 addresstags:- - Delivery+ - Customerssecurity:- 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 bookx-codeSamples:- lang: javascriptlabel: 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: headerrequired: true- description: Digital link tokenschema:type: stringresponses:- '302':- description: redirect to the file download- '403':- description: download link expired or limit exceeded+ '201':+ description: address createdcontent: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 Yorkschema:- "$ref": "#/components/schemas/ErrorResponse"- '404':- description: digital link not found+ "$ref": "#/components/schemas/Address"+ '422':+ description: validation errorcontent: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 blankschema:"$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 addresstags:- - Carts+ - Customerssecurity:- 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: javascriptlabel: 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: Authorizationin: 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: pathrequired: 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 Yorkschema:- "$ref": "#/components/schemas/Cart"- '422':- description: invalid discount code+ "$ref": "#/components/schemas/Address"+ '404':+ description: address not foundcontent: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 foundschema:"$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: objectproperties:- 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 addressdelete:- summary: Remove discount code+ summary: Delete an addresstags:- - Carts+ - Customerssecurity:- 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: javascriptlabel: 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: Authorizationin: header- required: false- description: Bearer token for authenticated customers- schema:- type: string- - name: cart_id- in: pathrequired: true- description: Cart prefixed IDschema:type: string- name: idin: pathrequired: 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 accessschema:type: stringresponses:- '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 foundcontent: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 foundschema:"$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 cardstags:- - Carts+ - Customerssecurity:- 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 methodsx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: header- required: false- schema:- type: string- - name: cart_id- in: pathrequired: true- description: Cart prefixed IDschema:type: string- - name: id- in: path- required: true- description: Fulfillment ID+ - name: page+ in: query+ required: falseschema:- type: string- - name: x-spree-token- in: header+ type: integer+ - name: limit+ in: queryrequired: 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: stringresponses:'200':- description: delivery rate selected, returns updated cart+ description: credit cards foundcontent: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- email: [email protected]- 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: unauthorizedcontent:application/json:example:error:- code: record_not_found- message: Delivery rate not found+ code: authentication_required+ message: Authentication requiredschema:"$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 cardtags:- - Carts+ - Customerssecurity:- 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 IDx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: header+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ - name: fields+ in: queryrequired: 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-keyin: header- required: false- description: Order token for guest access+ required: trueschema:type: string- - name: cart_id+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ - name: idin: pathrequired: 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: Authorizationin: 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: queryrequired: 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: stringresponses:- '201':- description: gift card applied+ '200':+ description: orders listedcontent: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+ email: [email protected]+ 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 Statescurrency: 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: unauthorizedcontent:application/json:example:error:- code: gift_card_already_redeemed- message: The Gift Card has already been redeemed.+ code: authentication_required+ message: Authentication requiredschema:"$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 ordertags:- - Carts+ - Customerssecurity:- 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: javascriptlabel: 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-keyin: header@@ -5454,53 +7022,55 @@ paths:type: string- name: Authorizationin: header- required: false- description: Bearer token for authenticated customers- schema:- type: string- - name: cart_id- in: pathrequired: true- description: Cart prefixed IDschema:type: string- name: idin: pathrequired: true- description: Gift card prefixed ID (e.g., gc_abc123)+ description: Order prefixed IDschema:type: string- - name: x-spree-token- in: header+ - name: expand+ in: queryrequired: 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: stringresponses:'200':- description: gift card removed+ description: order foundcontent:application/json:example:- id: cart_UkLWZg9DAJ+ id: or_UkLWZg9DAJmarket_id: mkt_UkLWZg9DAJ+ cart_id:channel_id: ch_UkLWZg9DAJ- preferred_stock_location_id:company_id:company_name:- po_number_required: falsepo_document_filename:po_document_byte_size:- number: cart_UkLWZg9DAJ- token: Wgq8NrLX3TUQLroJRYWFdQd5- email:+ number: R1001+ email: [email protected]customer_note:po_number:currency: USDlocale: entotal_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: falsediscounts: []fees: []items:@@ -5555,8 +7106,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 939569- slug: product-939569+ name: Product 1905633+ slug: product-1905633options_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 Yorkshipping_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 Yorkgift_card:market:id: mkt_UkLWZg9DAJ@@ -5622,16 +7273,25 @@ paths:supported_locales:- enschema:- "$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 customertags:- Customerssecurity:- api_key: []- bearer_auth: []- description: Returns all gift cards for the authenticated customer+ description: Creates a new customer account and returns a JWT tokenx-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema: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: stringresponses:- '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+ email: [email protected]+ 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+ email: [email protected]+ 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 takencontent:application/json:example:error:- code: authentication_required- message: Authentication required+ code: validation_error+ message: Email has already been taken+ details:+ email:+ - has already been takenschema:"$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+ example: [email protected]+ 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:+ - password+ "/api/v3/store/customers/me":get:- summary: Get a gift card+ summary: Get current customer profiletags:- Customerssecurity:- api_key: []bearer_auth: []- description: Returns a gift card by its ID+ description: Returns the profile of the currently authenticated customerx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: headerrequired: true- schema:- type: string- - name: id- in: path- required: true+ description: Bearer JWT tokenschema:type: string- name: fields@@ -5776,47 +7444,128 @@ paths:type: stringresponses:'200':- description: gift card found+ description: profile foundcontent: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+ email: [email protected]+ 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 tokencontent:application/json:example:error:- code: record_not_found- message: Gift card not found+ code: authentication_required+ message: Authentication requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/carts/{cart_id}/items":- post:- summary: Add item to cart+ patch:+ summary: Update current customer profiletags:- - Carts+ - Customerssecurity:- 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 customerx-codeSamples:- lang: javascriptlabel: 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: trueschema: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: Authorizationin: header- required: false- description: Unique key for request idempotency.+ required: trueschema:type: stringresponses:- '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 updatedcontent:application/json:example:- error:- code: variant_not_found- message: Variant not found+ id: cust_UkLWZg9DAJ+ email: [email protected]+ 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 errorcontent:application/json:example:error:code: validation_error- message: Quantity You can order at most 10 of this item.+ message: Email can't be blankdetails:- quantity:- - You can order at most 10 of this item.+ email:+ - can't be blankschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -6056,31 +7723,41 @@ paths:schema:type: objectproperties:- 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+ example: [email protected]+ 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 metadataexample:- 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 cardstags:- - Carts+ - Customerssecurity:- api_key: []bearer_auth: []- description: Updates the quantity of a line item in the cart+ description: Returns all gift cards for the authenticated customerx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: header- required: false- schema:- type: string- - name: cart_id- in: pathrequired: true- description: Cart prefixed IDschema:type: string- - name: id- in: path- required: true- description: Line item ID+ - name: page+ in: query+ required: falseschema:- type: string- - name: x-spree-token- in: header+ type: integer+ - name: limit+ in: query+ required: false+ schema:+ type: integer+ - name: fields+ in: queryrequired: false+ description: Comma-separated list of fields to include (e.g., name,slug,price).+ id is always included.schema:type: stringresponses:'200':- description: quantity change rejected, reported in warnings+ description: gift cards foundcontent: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: activecurrency: 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 cardtags:- - Carts+ - Customerssecurity:- api_key: []bearer_auth: []- description: Removes a line item from the cart+ description: Returns a gift card by its IDx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: header- required: false- schema:- type: string- - name: cart_id- in: pathrequired: true- description: Cart prefixed IDschema:type: string- name: id@@ -6316,116 +7893,57 @@ paths:required: trueschema:type: string- - name: x-spree-token- in: header+ - name: fields+ in: queryrequired: false+ description: Comma-separated list of fields to include (e.g., name,slug,price).+ id is always included.schema:type: stringresponses:'200':- description: line item removed, returns updated cart+ description: gift card foundcontent: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: activecurrency: 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: trueschema:- "$ref": "#/components/schemas/Cart"+ "$ref": "#/components/schemas/GiftCard"'404':- description: line item not found+ description: gift card not foundcontent:application/json:example:error:- code: line_item_not_found- message: Line item not found+ code: record_not_found+ message: Gift card not foundschema:"$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 sessiontags:- - Markets+ - Customerssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema: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: trueschema: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 foundcontent: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: trueschema:- 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 foundcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: record_not_found+ message: Payment setup session not foundschema:"$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 sessiontags:- - Markets+ - Customerssecurity:- 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: javascriptlabel: 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 completedcontent: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: trueschema:- type: object- properties:- data:- type: array- required:- - data- '401':- description: unauthorized+ "$ref": "#/components/schemas/PaymentSetupSession"+ '404':+ description: payment setup session not foundcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: record_not_found+ message: Payment setup session not foundschema:"$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 creditstags:- - Markets+ - Customerssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: id- in: path+ - name: Authorization+ in: headerrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: market found+ description: store credits foundcontent: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: unauthorizedcontent:application/json:example:error:- code: record_not_found- message: Market not found+ code: authentication_required+ message: Authentication requiredschema:"$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 credittags:- - Markets+ - Customerssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: country- in: query+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ - name: id+ in: pathrequired: true- description: Country ISO 3166-1 alpha-2 code (e.g., "DE", "US")schema:type: string- name: fieldsin: queryrequired: 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: stringresponses:'200':- description: market resolved+ description: store credit foundcontent: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: USDschema:- type: object+ "$ref": "#/components/schemas/StoreCredit"'404':- description: no market for country+ description: store credit not foundcontent:application/json:example:error:code: record_not_found- message: record not found+ message: Store credit not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/markets/{market_id}/countries":+ "/api/v3/store/countries":get:- summary: List countries in a market+ summary: List countriestags:- Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: market_id- in: path- required: true- description: Market prefixed ID- schema:- type: string- name: fieldsin: queryrequired: false@@ -6796,32 +8410,44 @@ paths:application/json:example:data:- - iso: FR- iso3: FRA- name: France- states_required: false- zipcode_required: true- iso: DEiso3: DEUname: Germanystates_required: falsezipcode_required: true+ - iso: US+ iso3: USA+ name: United States+ states_required: true+ zipcode_required: trueschema:type: objectproperties: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 countrytags:- Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: market_id- in: path- required: true- description: Market prefixed ID- schema:- type: string- - name: id+ - name: isoin: pathrequired: 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: trueschema: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 foundcontent:application/json:example:@@ -6882,41 +8519,14 @@ paths:message: record not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/newsletter_subscribers":- post:- summary: Subscribe to the newsletter+ "/api/v3/store/currencies":+ get:+ summary: List supported currenciestags:- - Newsletter Subscribers+ - Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header+ - name: fields+ in: queryrequired: 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: stringresponses:- '201':- description: auto-verified when JWT matches subscribed email+ '200':+ description: currencies foundcontent:application/json:example:- id: sub_UkLWZg9DAJ- email: [email protected]- 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: unauthorizedcontent:application/json:example:error:- code: validation_error- message: Email is invalid- details:- email:- - is invalid+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- email:- type: string- format: email- example: [email protected]- 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:- "/api/v3/store/newsletter_subscribers/verify":- post:- summary: Verify a newsletter subscription+ "/api/v3/store/locales":+ get:+ summary: List supported localestags:- - Newsletter Subscribers+ - Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema: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: stringresponses:'200':- description: subscription verified+ description: locales foundcontent:application/json:example:- id: sub_UkLWZg9DAJ- email: [email protected]- 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: falseschema:- "$ref": "#/components/schemas/NewsletterSubscriber"- '422':- description: missing token+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Locale"+ required:+ - data+ '401':+ description: unauthorizedcontent:application/json:example:error:- code: parameter_missing- message: token is required+ code: invalid_token+ message: Valid API key requiredschema:"$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 marketstags:- - Newsletter Subscribers+ - Marketssecurity:- 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: false- description: Optional Bearer JWT — alternative to the `token` query param- schema:- type: string- - name: token+ - name: fieldsin: queryrequired: 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: stringresponses:- '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: unauthorizedcontent:application/json:example:error:code: invalid_token- message: Newsletter unsubscribe token is invalid or has expired.+ message: Valid API key requiredschema:"$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- example: [email protected]- 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 markettags:- - Orders+ - Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: false- description: Bearer token for authenticated customers- schema:- type: string- name: idin: pathrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: order found (guest via order token)+ description: market foundcontent: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- email: [email protected]- 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: trueschema:- "$ref": "#/components/schemas/Order"+ type: object'404':- description: incomplete order not accessible+ description: market not foundcontent:application/json:example:error:- code: order_not_found- message: Order not found+ code: record_not_found+ message: Market not foundschema:"$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 countrytags:- - Carts+ - Marketssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema: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: queryrequired: 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: headerrequired: 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 IDschema:type: string- - name: Idempotency-Key- in: header+ - name: fields+ in: queryrequired: 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: stringresponses:- '201':- description: payment session created+ '200':+ description: countries foundcontent: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: trueschema:- "$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 markettags:- - 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: javascriptlabel: 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: stringresponses:'200':- description: payment session found+ description: country foundcontent: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: trueschema:- "$ref": "#/components/schemas/PaymentSession"+ type: object'404':- description: payment session not found+ description: country not in marketcontent:application/json:example:error:code: record_not_found- message: Payment session not found+ message: record not foundschema:"$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 wishliststags:- - Carts+ - Wishlistssecurity:- 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 customerx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: header+ required: true+ schema:+ type: string+ - name: page+ in: queryrequired: 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: stringresponses:'200':- description: payment session completed+ description: wishlists foundcontent: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: unauthorizedcontent:application/json:example:error:- code: record_not_found- message: Payment session not found+ code: authentication_required+ message: Authentication requiredschema:"$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 wishlisttags:- - Customers+ - Wishlistssecurity:- 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 customerx-codeSamples:- lang: javascriptlabel: 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: stringresponses:'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 createdcontent:application/json:example:- error:- code: authentication_required- message: Authentication required+ id: wl_gbHJdmfrXB+ name: Birthday Ideas+ token: 9QwEwKPqhv9b6g6vN3mSu4Pm+ is_default: false+ is_private: trueschema:- "$ref": "#/components/schemas/ErrorResponse"- '404':- description: payment method not found+ "$ref": "#/components/schemas/Wishlist"+ '422':+ description: validation errorcontent: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 blankschema:"$ref": "#/components/schemas/ErrorResponse"requestBody:@@ -7942,42 +9217,25 @@ paths:schema:type: objectproperties:- 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: falserequired:- - 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 wishlisttags:- - Customers+ - Wishlistssecurity:- api_key: []bearer_auth: []- description: Returns a payment setup session with its current status and provider- data.x-codeSamples:- lang: javascriptlabel: 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: stringresponses:'200':- description: payment setup session found+ description: wishlist foundcontent: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: trueschema:- "$ref": "#/components/schemas/PaymentSetupSession"+ "$ref": "#/components/schemas/Wishlist"'404':- description: payment setup session not found+ description: wishlist not foundcontent:application/json:example:error:code: record_not_found- message: Payment setup session not found+ message: Wishlist not foundschema:"$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: stringpatch:- 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 wishlisttags:- - Customers+ - Wishlistssecurity:- 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: javascriptlabel: 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: stringresponses:- '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 wishlisttags:- - Carts+ - Wishlistssecurity:- 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 wishlistx-codeSamples:- lang: javascriptlabel: 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: Authorizationin: header- required: false+ required: trueschema:type: string- - name: cart_id+ - name: wishlist_idin: pathrequired: true- description: Cart prefixed ID- schema:- type: string- - name: x-spree-token- in: header- required: false- description: Order token for guest accessschema:type: stringresponses:'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 addedcontent: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: objectproperties:- 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: 1required:- - 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 newslettertags:- - Policies+ - Newsletter Subscriberssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: fields- in: query+ - name: Authorization+ in: headerrequired: 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 customerschema:type: stringresponses:- '200':- description: policies listed+ '201':+ description: auto-verified when JWT matches subscribed emailcontent: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+ email: [email protected]+ 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_UkLWZg9DAJschema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Policy"- required:- - data- '401':- description: unauthorized+ "$ref": "#/components/schemas/NewsletterSubscriber"+ '422':+ description: invalid email formatcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: validation_error+ message: Email is invalid+ details:+ email:+ - is invalidschema:"$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+ example: [email protected]+ 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:+ "/api/v3/store/newsletter_subscribers/verify":+ post:+ summary: Verify a newsletter subscriptiontags:- - Policies+ - Newsletter Subscriberssecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema: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: stringresponses:'200':- description: policy found+ description: subscription verifiedcontent: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+ email: [email protected]+ 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 tokencontent:application/json:example:error:- code: record_not_found- message: Policy not found+ code: parameter_missing+ message: token is requiredschema:"$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-keyin: headerrequired: 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: headerrequired: false- description: Comma-separated associations to expand (variants, media, categories,- option_types, seller, seller.policies)+ description: Optional Bearer JWT — alternative to the `token` query paramschema:type: string- - name: fields+ - name: tokenin: queryrequired: 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: stringresponses:- '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 storecontent: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+ example: [email protected]+ 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 policiestags:- - Product Catalog+ - Policiessecurity:- 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: javascriptlabel: 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-keyin: headerrequired: 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: fieldsin: queryrequired: 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: stringresponses:'200':- description: product without prior_price expanded does not include field+ description: policies listedcontent: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: unauthorizedcontent:application/json:example:error:- code: record_not_found- message: Product not found+ code: invalid_token+ message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/products/filters":+ "/api/v3/store/policies/{id}":get:- summary: Get product filters+ summary: Get a policytags:- - Product Catalog+ - Policiessecurity:- 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: javascriptlabel: 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-keyin: headerrequired: true- description: Publishable API keyschema: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: fieldsin: queryrequired: false- description: Filter by name containing string+ description: Comma-separated list of fields to include. id is always included.schema:type: stringresponses:'200':- description: filters scoped to category+ description: policy foundcontent: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 foundcontent:application/json:example:error:- code: invalid_token- message: Valid API key required+ code: record_not_found+ message: Policy not foundschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/sellers":+ "/api/v3/store/channel":get:- summary: List sellers+ summary: Get the current channeltags:- - Sellers+ - Channelsecurity:- 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-keyin: headerrequired: trueschema: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: headerrequired: 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: stringresponses:'200':- description: sellers found+ description: channel foundcontent: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: falseschema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Seller"- meta:- "$ref": "#/components/schemas/PaginationMeta"+ "$ref": "#/components/schemas/Channel"'401':description: unauthorizedcontent:@@ -8970,96 +10094,188 @@ paths:message: Valid API key requiredschema:"$ref": "#/components/schemas/ErrorResponse"- "/api/v3/store/sellers/{id}":+ "/api/v3/store/account/companies":get:- summary: Get a seller+ summary: List my company membershipstags:- - Sellers+ - Companiessecurity:- 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-keyin: headerrequired: trueschema:type: string- - name: id- in: path+ - name: Authorization+ in: headerrequired: 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+ email: [email protected]+ 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: trueschema: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: trueschema:type: stringresponses:'200':- description: seller found by slug+ description: company foundcontent: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 nodecontent: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: stringget:- summary: List store credits+ summary: List company memberstags:- - Customers+ - Companiessecurity:- 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-keyin: header@@ -9071,38 +10287,17 @@ paths:required: trueschema: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: stringresponses:'200':- description: store credits found+ description: members listedcontent: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+ email: [email protected]meta:page: 1limit: 25@@ -9113,33 +10308,17 @@ paths:in: 1previous: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 emailtags:- - Customers+ - Companiessecurity:- 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: javascriptlabel: 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-keyin: header@@ -9165,67 +10348,44 @@ paths:required: trueschema: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: stringresponses:- '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 sentcontent: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+ email: [email protected]+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ customer_email:+ type: string+ example: [email protected]+ 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 booktags:- - Carts+ - Companiessecurity:- 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-keyin: header@@ -9237,214 +10397,194 @@ paths:required: trueschema: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-keyin: header- required: false+ required: trueschema:type: string- - name: Idempotency-Key+ - name: Authorizationin: header- required: false- description: Unique key for request idempotency.+ required: trueschema:type: stringresponses:'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 updatedcontent: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 YorkrequestBody:content:application/json:schema:type: objectproperties:- 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: truedelete:- summary: Remove store credit+ summary: Remove an address book entrytags:- - Carts+ - Companiessecurity:- 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-keyin: header@@ -9456,242 +10596,306 @@ paths:required: trueschema: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: stringresponses:'200':- description: store credit removed+ description: orders listedcontent: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+ email: [email protected]+ 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: stringget:- summary: List wishlists+ summary: Look up an invitationtags:- - Wishlists+ - Companiessecurity:- 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-keyin: headerrequired: trueschema: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: stringresponses:'200':- description: wishlists found+ description: invitation foundcontent: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+ email: [email protected]+ 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 expiredcontent: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: stringpost:- summary: Create a wishlist+ summary: Accept an invitationtags:- - Wishlists+ - Companiessecurity:- 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: javascriptlabel: 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 createdcontent: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+ email: [email protected]requestBody:content:application/json:schema:type: objectproperties:- 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 methodstags:- - Wishlists+ - Deliverysecurity:- api_key: []- bearer_auth: []+ description: Storefront-visible delivery methods. Filter by fulfillment_type+ to discover pickup options.x-codeSamples:- lang: javascriptlabel: 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-keyin: headerrequired: trueschema: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_typein: queryrequired: 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: stringresponses:'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 foundcontent: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 locationstags:- - Wishlists+ - Deliverysecurity:- 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: javascriptlabel: 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header+ - name: id+ in: pathrequired: true+ description: Delivery method prefixed IDschema: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: tokenin: pathrequired: true+ description: Digital link tokenschema:type: stringresponses:- '200':- description: wishlist updated+ '302':+ description: redirect to the file download+ '403':+ description: download link expired or limit exceededcontent: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 invalidschema:- "$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 sellerstags:- - 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header- required: true+ - name: page+ in: query+ required: falseschema:- type: string- - name: id- in: path- required: true+ type: integer+ - name: limit+ in: query+ required: falseschema:- 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 nameschema: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: stringresponses:- '201':- description: item added+ '200':+ description: sellers foundcontent: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 sellertags:- - Wishlists+ - Sellerssecurity:- 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-keyin: headerrequired: trueschema:type: string- - name: Authorization- in: header+ - name: id+ in: pathrequired: 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: stringresponses:- '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 foundcontent: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: stringnullable: true+ carrier_name:+ type: string+ nullable: trueservice:type: stringnullable: true@@ -13410,9 +14565,6 @@ components:type: stringowner_type:type: string- carrier_name:- type: string- nullable: truecost:type: stringdisplay_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_iddiff --git a/packages/admin-sdk/examples/order-fulfillments/purchase-label.ts b/packages/admin-sdk/examples/order-fulfillments/purchase-label.tsdeleted file mode 100644index 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.tsindex 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.jsonindex 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 filediff --git a/packages/dashboard-ui/src/ui/badge.tsx b/packages/dashboard-ui/src/ui/badge.tsxindex 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.tsxindex 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: stringfulfillmentId: stringdeliveries: 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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"><RelativeTimeiso={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: FulorderId={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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.jsonindex 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.rbindex 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 Spreeclass FulfillmentsController < BaseControllerscoped_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 Spreeendend- # 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 thisdiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex 9295f68fe9..5ee278bf75 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -722,8 +722,6 @@ Spree::Core::Engine.add_routes doresources :fulfillments, controller: 'orders/fulfillments', only: [:index, :show, :create, :update] domember dopatch :fulfill- # Deprecated alias of POST .../labels — removed in 6.1.- patch :purchase_labelpatch :mark_deliveredpatch :cancelpatch :splitdiff --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.rbindex 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: :contrexpect(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+enddescribe 'PATCH #mark_delivered' dodiff --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.rbindex 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: :conendend- 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' dobefore doSpree.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.rbindex 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: 'apiendend- 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' dopatch 'Mark a fulfillment delivered' dotags 'Fulfillments'diff --git a/spree/core/app/models/spree/fulfillment.rb b/spree/core/app/models/spree/fulfillment.rbindex 2be9216b7f..490c902b30 100644--- a/spree/core/app/models/spree/fulfillment.rb+++ b/spree/core/app/models/spree/fulfillment.rb@@ -125,9 +125,6 @@ module Spreeinclude Spree::HasStatushas_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.rbindex 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.rbindex 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 Spreemodule 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 Destroyprepend Spree::ServiceModule::Base@@ -15,6 +19,11 @@ module Spreereturn 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)endenddiff --git a/spree/core/app/workflows/spree/fulfillments/mark_delivered.rb b/spree/core/app/workflows/spree/fulfillments/mark_delivered.rbindex 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.rbdeleted file mode 100644index 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-enddiff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 0fa73f9935..992e807492 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -900,6 +900,7 @@ en:deleted: Deleteddeliveries:errors:+ delivered: This consignment has already arrived — its arrival is what the returns window counts from, so it cannot be deletedhas_label: This delivery was created by a shipping label — refund the label instead of deleting the deliverynot_found: This fulfillment has no delivery to track yetdelivery: Deliverydiff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rbindex 8a8fd906df..8c43cade20 100644--- a/spree/core/lib/spree/core/dependencies.rb+++ b/spree/core/lib/spree/core/dependencies.rb@@ -81,10 +81,6 @@ module Spreefulfillment_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 + deliveriesshipping_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.rbindex 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 doexpect(result.error.to_s).to eq(Spree.t('deliveries.errors.has_label'))expect(label.reload.delivery).to be_presentend+ # 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)+ endenddiff --git a/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rb b/spree/core/spec/workflows/spree/fulfillments/update_tracking_spec.rbdeleted file mode 100644index 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-enddiff --git a/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rb b/spree/providers/easypost/app/models/spree_easypost/fulfillment_provider.rbindex 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')enddiff --git a/spree/providers/easypost/app/models/spree_easypost/tracker_event.rb b/spree/providers/easypost/app/models/spree_easypost/tracker_event.rbindex 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.rbindex 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 doexpect(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