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
Add per-channel order routing rule management (Admin API + React dashboard) (#14342)
Damian Legawiec202d84637427
diff --git a/.changeset/order-routing-rules-admin.md b/.changeset/order-routing-rules-admin.mdnew file mode 100644index 0000000000..369412f36c--- /dev/null+++ b/.changeset/order-routing-rules-admin.md@@ -0,0 +1,8 @@+---+"@spree/admin-sdk": minor+"@spree/dashboard": minor+"@spree/dashboard-core": minor+"@spree/dashboard-ui": minor+---++Add per-channel order routing rule management. `@spree/admin-sdk` gains `channels.orderRoutingRules.{list,get,create,update,delete}` (nested under `/channels/:channel_id/order_routing_rules`) plus `orderRoutingRules.types()` for rule-kind discovery; the admin `Store` type now exposes `preferred_order_routing_strategy`. The dashboard's channel edit sheet embeds a routing-rules editor — drag-to-reorder priority, per-rule active toggles, an "Add rule" picker fed by the types endpoint (offering only kinds not yet on the channel; rule kinds are unique per channel), and schema-driven preference forms for rule kinds that declare preferences. The editor renders only when the channel's effective routing strategy is Rules. `Subject.OrderRoutingRule` is available for permission checks.diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yamlindex dc3505bfe2..7072af1c1a 100644--- a/docs/api-reference/admin.yaml+++ b/docs/api-reference/admin.yaml@@ -92,16 +92,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImM2MmZiM2NjLTJmMGYtNGJhZC05YzQzLWYyMmQ0ODBlZDNjMCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg0NTMwODkyfQ.05xpy9PDmtZVCev0ifcY0_MJ-nYpvRpt5BPRWu7Wqwk+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjMyOGRkZWM0LWFmZTYtNDBiNi05OGM4LWRjZGYzN2UwNWU3MiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg0NjUwOTkyfQ.09gXw6nFdC7XcrUoXDeDZrYt_QQFwMZ8woJRNn4lx80user:id: admin_UkLWZg9DAJemail: [email protected]- first_name: Isaura- last_name: Bradtke- full_name: Isaura Bradtke+ first_name: Magdalen+ last_name: Botsford+ full_name: Magdalen Botsfordselected_locale:- created_at: '2026-07-20T06:56:32.091Z'- updated_at: '2026-07-20T06:56:32.091Z'+ created_at: '2026-07-21T16:18:12.642Z'+ updated_at: '2026-07-21T16:18:12.642Z'avatar_url:roles:- id: role_UkLWZg9DAJ@@ -200,16 +200,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjQ0ZTVhYTM3LTVhZmEtNDNiZi1iMDg2LTY4Yjg3MzE2Njk1OSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg0NTMwODkzfQ.8-GsJTrnnGl2AQ5OjXZPlTk4bOma46VZPvibwK_F1BM+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjE5YjVlZjQ5LTE4MTItNGFmMy05MjQzLTIwOWE1NDZhYTE4NCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg0NjUwOTkzfQ.7xnWTcx4gkhnSBoM6vhV8q_Bmt17NYsZQmcKyxPNm28user:id: admin_UkLWZg9DAJemail: [email protected]- first_name: Mickie- last_name: Bahringer- full_name: Mickie Bahringer+ first_name: Marcella+ last_name: Little+ full_name: Marcella Littleselected_locale:- created_at: '2026-07-20T06:56:33.206Z'- updated_at: '2026-07-20T06:56:33.206Z'+ created_at: '2026-07-21T16:18:13.732Z'+ updated_at: '2026-07-21T16:18:13.732Z'avatar_url:roles:- id: role_UkLWZg9DAJ@@ -307,13 +307,13 @@ paths:example:user:id: admin_UkLWZg9DAJ- email: [email protected]- first_name: Takako- last_name: Schowalter- full_name: Takako Schowalter+ email: [email protected]+ first_name: Bud+ last_name: Pouros+ full_name: Bud Pourosselected_locale:- created_at: '2026-07-20T06:57:12.101Z'- updated_at: '2026-07-20T06:57:12.101Z'+ created_at: '2026-07-21T16:18:52.386Z'+ updated_at: '2026-07-21T16:18:52.386Z'avatar_url:roles:- id: role_UkLWZg9DAJ@@ -429,13 +429,13 @@ paths:example:user:id: admin_UkLWZg9DAJ- email: [email protected]- first_name: Dwana- last_name: Kiehn- full_name: Dwana Kiehn+ email: [email protected]+ first_name: Anglea+ last_name: Labadie+ full_name: Anglea Labadieselected_locale: de- created_at: '2026-07-20T06:57:12.407Z'- updated_at: '2026-07-20T06:57:12.422Z'+ created_at: '2026-07-21T16:18:52.714Z'+ updated_at: '2026-07-21T16:18:52.735Z'avatar_url:roles:- id: role_UkLWZg9DAJ@@ -628,16 +628,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImVmMTkxNDNlLWU2OGEtNDk5Yy1iODAzLWMyNDZhMzAyNGVmYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg0NTM0MjYzfQ.WjNiLsrRGj-x9lkisZMA6NFI9M578_TA57h8aOPY8Ac+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjdhZGRmZGU2LTNjNDEtNGJjMC05NGVhLWQ3ZGNiNTk4YmNmNyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg0NjU0MzY3fQ.s4fR6obGn-KKw-j644PhQiDHqbX54B_s0w09zRsBBiEuser:id: admin_UkLWZg9DAJemail: [email protected]- first_name: Royce- last_name: Funk- full_name: Royce Funk+ first_name: Dahlia+ last_name: Nolan+ full_name: Dahlia Nolanselected_locale:- created_at: '2026-07-20T06:57:43.590Z'- updated_at: '2026-07-20T06:57:43.902Z'+ created_at: '2026-07-21T16:19:27.037Z'+ updated_at: '2026-07-21T16:19:27.318Z'avatar_url:roles:- id: role_UkLWZg9DAJ@@ -752,8 +752,8 @@ paths:data:- id: ao_UkLWZg9DAJorigin: https://shop.example.com- created_at: '2026-07-20T06:56:27.466Z'- updated_at: '2026-07-20T06:56:27.466Z'+ created_at: '2026-07-21T16:18:08.030Z'+ updated_at: '2026-07-21T16:18:08.030Z'meta:page: 1limit: 25@@ -837,8 +837,8 @@ paths:example:id: ao_gbHJdmfrXBorigin: https://admin.example.com- created_at: '2026-07-20T06:56:28.088Z'- updated_at: '2026-07-20T06:56:28.088Z'+ created_at: '2026-07-21T16:18:08.617Z'+ updated_at: '2026-07-21T16:18:08.617Z'schema:"$ref": "#/components/schemas/AllowedOrigin"'422':@@ -925,8 +925,8 @@ paths:example:id: ao_UkLWZg9DAJorigin: https://shop.example.com- created_at: '2026-07-20T06:56:28.378Z'- updated_at: '2026-07-20T06:56:28.378Z'+ created_at: '2026-07-21T16:18:08.913Z'+ updated_at: '2026-07-21T16:18:08.913Z'schema:"$ref": "#/components/schemas/AllowedOrigin"'404':@@ -987,8 +987,8 @@ paths:example:id: ao_UkLWZg9DAJorigin: https://www.example.com- created_at: '2026-07-20T06:56:28.940Z'- updated_at: '2026-07-20T06:56:29.219Z'+ created_at: '2026-07-21T16:18:09.483Z'+ updated_at: '2026-07-21T16:18:09.759Z'schema:"$ref": "#/components/schemas/AllowedOrigin"'422':@@ -1108,34 +1108,34 @@ paths:key_type: publishabletoken_prefix:scopes: []- created_at: '2026-07-20T06:56:29.795Z'- updated_at: '2026-07-20T06:56:29.795Z'+ created_at: '2026-07-21T16:18:10.338Z'+ updated_at: '2026-07-21T16:18:10.338Z'revoked_at:last_used_at:channel_id:- plaintext_token: pk_s8qsX62wexmnk9WysAjYSKme+ plaintext_token: pk_NpVVr7KT3KR7aNQtYhRarkLBcreated_by_email:- id: key_gbHJdmfrXBname: Backend integrationkey_type: secret- token_prefix: sk_PiEwdvTU6+ token_prefix: sk_jvcayks8escopes:- write_all- created_at: '2026-07-20T06:56:29.796Z'- updated_at: '2026-07-20T06:56:29.796Z'+ created_at: '2026-07-21T16:18:10.339Z'+ updated_at: '2026-07-21T16:18:10.339Z'revoked_at:last_used_at:channel_id:plaintext_token:created_by_email:- id: key_EfhxLZ9ck8- name: quae+ name: aspernaturkey_type: secret- token_prefix: sk_2NFKiP14w+ token_prefix: sk_bEXJent5Pscopes:- write_all- created_at: '2026-07-20T06:56:29.796Z'- updated_at: '2026-07-20T06:56:29.796Z'+ created_at: '2026-07-21T16:18:10.341Z'+ updated_at: '2026-07-21T16:18:10.341Z'revoked_at:last_used_at:channel_id:@@ -1202,16 +1202,16 @@ paths:id: key_VqXmZF31wYname: CI keykey_type: secret- token_prefix: sk_YrTk9UUdj+ token_prefix: sk_R4Mob1qJSscopes:- read_orders- created_at: '2026-07-20T06:56:30.369Z'- updated_at: '2026-07-20T06:56:30.369Z'+ created_at: '2026-07-21T16:18:10.900Z'+ updated_at: '2026-07-21T16:18:10.900Z'revoked_at:last_used_at:channel_id:- plaintext_token: sk_YrTk9UUdjkLz11dMU5XftfHM- created_by_email: [email protected]+ plaintext_token: sk_R4Mob1qJSnAn1XSTJWmcr9Y4+ created_by_email: [email protected]'422':description: validation errorcontent:@@ -1300,12 +1300,12 @@ paths:key_type: publishabletoken_prefix:scopes: []- created_at: '2026-07-20T06:56:30.658Z'- updated_at: '2026-07-20T06:56:30.658Z'+ created_at: '2026-07-21T16:18:11.199Z'+ updated_at: '2026-07-21T16:18:11.199Z'revoked_at:last_used_at:channel_id:- plaintext_token: pk_rzXvzxgTqG7w4rtyb9Q7qkFx+ plaintext_token: pk_sLyTgpo6jEykowF7qMCRsbC4created_by_email:patch:summary: Update an API key@@ -1359,11 +1359,11 @@ paths:id: key_gbHJdmfrXBname: Backend integration (renamed)key_type: secret- token_prefix: sk_iVncK9AGx+ token_prefix: sk_Rqy49T6BQscopes:- write_all- created_at: '2026-07-20T06:56:30.942Z'- updated_at: '2026-07-20T06:56:31.228Z'+ created_at: '2026-07-21T16:18:11.482Z'+ updated_at: '2026-07-21T16:18:11.762Z'revoked_at:last_used_at:channel_id:@@ -1460,13 +1460,13 @@ paths:application/json:example:id: key_EfhxLZ9ck8- name: laudantium+ name: exkey_type: secret- token_prefix: sk_f39FA4nWr+ token_prefix: sk_hFAPcmw1Escopes:- write_all- created_at: '2026-07-20T06:56:31.525Z'- updated_at: '2026-07-20T06:56:31.525Z'+ created_at: '2026-07-21T16:18:12.078Z'+ updated_at: '2026-07-21T16:18:12.078Z'revoked_at:last_used_at:channel_id:@@ -1524,43 +1524,28 @@ paths:id: key_gbHJdmfrXBname: Backend integrationkey_type: secret- token_prefix: sk_LnuKvFNz2+ token_prefix: sk_hofZkVSLfscopes:- write_all- created_at: '2026-07-20T06:56:31.539Z'- updated_at: '2026-07-20T06:56:31.821Z'- revoked_at: '2026-07-20T06:56:31.821Z'+ created_at: '2026-07-21T16:18:12.094Z'+ updated_at: '2026-07-21T16:18:12.375Z'+ revoked_at: '2026-07-21T16:18:12.375Z'last_used_at:channel_id:plaintext_token:created_by_email:- "/api/v3/admin/channels":+ "/api/v3/admin/categories":get:- summary: List channels+ summary: List categoriestags:- - Channels+ - Categoriessecurity:- 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',- })+ Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).- const { data: channels } = await client.channels.list()- - lang: bash- label: Spree CLI- source: spree api get /channels+ **Required scope:** `read_categories` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -1570,57 +1555,67 @@ 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: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., children, parent,+ ancestors).+ schema:+ type: stringresponses:'200':- description: channels found+ description: categories 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-07-20T06:56:26.144Z'- updated_at: '2026-07-20T06:56:26.144Z'- - 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-07-20T06:56:37.345Z'- updated_at: '2026-07-20T06:56:37.345Z'+ - 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+ metadata: {}+ pretty_name: Clothing+ lft: 1+ rgt: 2+ products_count: 0+ created_at: '2026-07-21T16:18:14.329Z'+ updated_at: '2026-07-21T16:18:14.329Z'meta:page: 1limit: 25- count: 2+ count: 1pages: 1from: 1- to: 2- in: 2+ to: 1+ in: 1previous:next:schema:@@ -1629,47 +1624,23 @@ paths:data:type: arrayitems:- "$ref": "#/components/schemas/Channel"+ "$ref": "#/components/schemas/Category"meta:"$ref": "#/components/schemas/PaginationMeta"required:- data- metapost:- summary: Create a channel+ summary: Create a categorytags:- - Channels+ - Categoriessecurity:- 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',- })+ Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.- // `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}'+ **Required scope:** `write_categories` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -1679,74 +1650,94 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: stringresponses:'201':- description: channel created+ description: category createdcontent: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-07-20T06:56:37.995Z'- updated_at: '2026-07-20T06:56:37.995Z'+ 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+ metadata: {}+ pretty_name: Clothing -> Shirts+ lft: 2+ rgt: 3+ products_count: 0+ created_at: '2026-07-21T16:18:14.905Z'+ updated_at: '2026-07-21T16:18:14.913Z'+ schema:+ "$ref": "#/components/schemas/Category"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank+ details:+ name:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"requestBody:content:application/json:schema:type: object- required:- - nameproperties:name:type: string- example: Point of Sale- code:+ example: Shirts+ parent_id:type: string- example: pos- description: Slug — auto-derived from `name` when blank.- active:+ 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+ hide_from_nav:type: boolean- default: true- "/api/v3/admin/channels/{id}":- parameters:- - name: id- in: path- required: true- schema:- type: string+ example: false+ required:+ - name+ "/api/v3/admin/categories/{id}":get:- summary: Get a channel+ summary: Get a categorytags:- - Channels+ - Categoriessecurity:- 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',- })+ description: |-+ Returns a single category by ID.- const channel = await client.channels.get('channel_xxx')- - lang: bash- label: Spree CLI- source: spree api get /channels/{id}+ **Required scope:** `read_categories` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -1756,52 +1747,75 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'200':- description: channel found+ description: category foundcontent: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-07-20T06:56:38.010Z'- updated_at: '2026-07-20T06:56:38.010Z'- patch:- summary: Update a channel- tags:- - Channels- security:+ 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+ metadata: {}+ pretty_name: Clothing+ lft: 1+ rgt: 2+ products_count: 0+ created_at: '2026-07-21T16:18:15.214Z'+ updated_at: '2026-07-21T16:18:15.214Z'+ schema:+ "$ref": "#/components/schemas/Category"+ '404':+ description: category not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Category not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a category+ tags:+ - Categories+ 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',- })+ description: |-+ Updates a category.- 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}'+ **Required scope:** `write_categories` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -1811,26 +1825,47 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Category IDschema:type: stringresponses:'200':- description: channel updated+ description: category updatedcontent:application/json:example:- id: ch_gbHJdmfrXB- name: Wholesale (Updated)- 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-07-20T06:56:38.310Z'- updated_at: '2026-07-20T06:56:38.604Z'+ 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+ metadata: {}+ pretty_name: Apparel+ lft: 1+ rgt: 2+ products_count: 0+ created_at: '2026-07-21T16:18:15.812Z'+ updated_at: '2026-07-21T16:18:16.101Z'+ schema:+ "$ref": "#/components/schemas/Category"requestBody:content:application/json:@@ -1839,33 +1874,33 @@ paths:properties:name:type: string- code:+ example: Apparel+ parent_id:type: string- active:+ 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+ hide_from_nav:type: booleandelete:- summary: Delete a channel+ summary: Delete a categorytags:- - Channels+ - Categoriessecurity:- 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',- })+ description: |-+ Deletes a category and its descendants.- await client.channels.delete('channel_xxx')- - lang: bash- label: Spree CLI- source: spree api delete /channels/{id}+ **Required scope:** `write_categories` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -1875,53 +1910,30 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Category IDschema:type: stringresponses:'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+ description: category deleted+ "/api/v3/admin/categories/{id}/reposition":+ patch:+ summary: Reposition a categorytags:- - Channels+ - Categoriessecurity:- 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',- })+ Moves a category to a new parent and/or index within the tree.- // 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"}'+ **Required scope:** `write_categories` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -1931,77 +1943,73 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Category IDschema:type: stringresponses:'200':- description: products published+ description: category repositionedcontent:application/json:example:- product_count: 1+ 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+ metadata: {}+ pretty_name: Clothing -> Footwear+ lft: 2+ rgt: 3+ products_count: 0+ created_at: '2026-07-21T16:18:16.421Z'+ updated_at: '2026-07-21T16:18:16.710Z'schema:- type: object- properties:- product_count:- type: integer+ "$ref": "#/components/schemas/Category"requestBody:content:application/json:schema:type: object- required:- - product_idsproperties:- 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:+ new_parent_id: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+ 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:+ - Categoriessecurity:- 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',- })+ Products classified under the category, ordered by their classification position.- 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"]}'+ **Required scope:** `read_categories` (for API-key authentication).parameters:- name: x-spree-api-keyin: header@@ -2011,42 +2019,199 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: category_id+ in: path+ required: true+ description: Category IDschema:type: stringresponses:'200':- description: products unpublished+ description: products foundcontent:application/json:example:- product_count: 1+ data: []+ meta:+ page: 1+ limit: 25+ count: 0+ pages: 1+ from: 0+ to: 0+ in: 0+ previous:+ next:schema:type: objectproperties:- product_count:- type: integer+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Product"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ post:+ summary: Add a product to a category+ tags:+ - Categories+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Classifies a product under the category (appended to the end).++ **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: product added+ content:+ application/json:+ example:+ id: prod_UkLWZg9DAJ+ name: Product 19357+ slug: product-19357+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on:+ preorder_ships_at:+ purchasable: true+ preorder: false+ in_stock: false+ backorderable: true+ available: true+ description: Deleniti atque ea quos ipsum aut. Est temporibus vel+ odio perspiciatis sunt eos. Soluta ipsam praesentium accusamus quidem+ mollitia. Voluptatem exercitationem quod assumenda cupiditate pariatur+ atque corporis. Totam eius quia aliquid corporis recusandae. Dicta+ possimus officiis amet fugiat. Eius aliquam ullam debitis dolorem+ eum inventore iusto. Id cumque nulla ullam dignissimos vero. Reprehenderit+ illum labore numquam delectus aperiam veniam.+ description_html: |-+ Deleniti atque ea quos ipsum aut. Est temporibus vel odio perspiciatis sunt eos. Soluta ipsam praesentium accusamus quidem mollitia. Voluptatem exercitationem quod assumenda cupiditate pariatur atque corporis. Totam eius quia aliquid corporis recusandae.+ Dicta possimus officiis amet fugiat. Eius aliquam ullam debitis dolorem eum inventore iusto. Id cumque nulla ullam dignissimos vero. Reprehenderit illum labore numquam delectus aperiam veniam.+ default_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-07-21T16:18:17.077Z'+ updated_at: '2026-07-21T16:18:17.077Z'+ original_price:+ status: active+ metadata: {}+ deleted_at:+ created_at: '2026-07-21T16:18:17.056Z'+ updated_at: '2026-07-21T16:18:17.087Z'+ tax_category_id: taxcat_UkLWZg9DAJ+ schema:+ "$ref": "#/components/schemas/Product"requestBody:content:application/json:schema:type: object+ properties:+ product_id:+ type: string+ example: prod_abc123required:- - product_ids+ - product_id+ "/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: objectproperties:- product_ids:- type: array- items:- type: string- "/api/v3/admin/custom_field_definitions":+ new_position:+ type: integer+ description: 0-based index among the category's products+ required:+ - new_position+ "/api/v3/admin/channels":get:- summary: List custom field definitions+ summary: List channelstags:- - Custom Fields+ - Channelssecurity:- api_key: []bearer_auth: []description: |-- Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.+ Returns the channels configured for the current store.**Required scope:** `read_settings` (for API-key authentication).x-codeSamples:@@ -2060,12 +2225,10 @@ paths:secretKey: 'sk_xxx',})- const { data: definitions } = await client.customFieldDefinitions.list({- q: { resource_type_eq: 'Spree::Product' },- })+ const { data: channels } = await client.channels.list()- lang: bashlabel: Spree CLI- source: spree api get /custom_field_definitions -d '{"q":{"resource_type_eq":"Spree::Product"}}'+ source: spree api get /channelsparameters:- name: x-spree-api-keyin: header@@ -2077,45 +2240,47 @@ paths:required: trueschema:type: string- - name: expand+ - name: pagein: queryrequired: false- description: Comma-separated associations to expand. Use dot notation for- nested expand (max 4 levels).schema:- type: string- - name: fields+ type: integer+ - name: limitin: queryrequired: false- description: Comma-separated list of fields to include (e.g., key,label,field_type).- id is always included.schema:- type: string+ type: integerresponses:'200':- description: definitions returned+ description: channels foundcontent:application/json:example:data:- - id: cfdef_UkLWZg9DAJ- namespace: specs- key: fabric- label: Title- field_type: short_text- resource_type: Spree::Product- storefront_visible: true- created_at: '2026-07-20T06:56:39.884Z'- updated_at: '2026-07-20T06:56:39.884Z'- - id: cfdef_gbHJdmfrXB- namespace: custom- key: order_notes- label: Order Notes- field_type: short_text- resource_type: Spree::Order- storefront_visible: true- created_at: '2026-07-20T06:56:39.885Z'- updated_at: '2026-07-20T06:56:39.885Z'+ - 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-07-21T16:18:06.730Z'+ updated_at: '2026-07-21T16:18:06.730Z'+ - 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-07-21T16:18:17.752Z'+ updated_at: '2026-07-21T16:18:17.752Z'meta:page: 1limit: 25@@ -2126,14 +2291,32 @@ paths:in: 2previous:next:- post:- summary: Create a custom field definition+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/Channel"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ post:+ summary: Create a channeltags:- - Custom Fields+ - Channelssecurity:- api_key: []bearer_auth: []- description: "**Required scope:** `write_settings` (for API-key authentication)."+ 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: javascriptlabel: Spree Admin SDK@@ -2145,18 +2328,16 @@ paths: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,+ // `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 post /custom_field_definitions -d '{"namespace":"specs","key":"origin","label":"Country- of Origin","field_type":"short_text","resource_type":"Spree::Product","storefront_visible":true}'+ source: spree api post /channels -d '{"name":"Point of Sale","code":"pos","active":true}'parameters:- name: x-spree-api-keyin: header@@ -2170,53 +2351,51 @@ paths:type: stringresponses:'201':- description: definition created+ description: channel createdcontent: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- created_at: '2026-07-20T06:56:40.451Z'- updated_at: '2026-07-20T06:56:40.451Z'+ 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-07-21T16:18:18.335Z'+ updated_at: '2026-07-21T16:18:18.335Z'requestBody:content:application/json:schema:type: objectrequired:- - key- - field_type- - resource_type+ - nameproperties:- namespace:- type: string- description: Defaults to `custom`- key:- type: string- label:- type: string- description: Human-readable name; defaults to titleized `key`- field_type:+ name:type: string- description: Custom field type identifier (one of the registered- field-type class names).- resource_type:+ example: Point of Sale+ code:type: string- description: Owner class, e.g. `Spree::Product`- storefront_visible:+ example: pos+ description: Slug — auto-derived from `name` when blank.+ active:type: boolean- description: 'When false, definition is admin-only (was `display_on:- back_end`)'- "/api/v3/admin/custom_field_definitions/{id}":+ default: true+ "/api/v3/admin/channels/{id}":+ parameters:+ - name: id+ in: path+ required: true+ schema:+ type: stringget:- summary: Show a custom field definition+ summary: Get a channeltags:- - Custom Fields+ - Channelssecurity:- api_key: []bearer_auth: []@@ -2232,10 +2411,10 @@ paths:secretKey: 'sk_xxx',})- const definition = await client.customFieldDefinitions.get('cfd_UkLWZg9DAJ')+ const channel = await client.channels.get('channel_xxx')- lang: bashlabel: Spree CLI- source: spree api get /custom_field_definitions/{id}+ source: spree api get /channels/{id}parameters:- name: x-spree-api-keyin: header@@ -2247,44 +2426,28 @@ 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., key,label,field_type).- id is always included.- schema:- type: stringresponses:'200':- description: definition found+ description: channel foundcontent:application/json:example:- id: cfdef_UkLWZg9DAJ- namespace: specs- key: fabric- label: Title- field_type: short_text- resource_type: Spree::Product- storefront_visible: true- created_at: '2026-07-20T06:56:40.456Z'- updated_at: '2026-07-20T06:56:40.456Z'+ 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-07-21T16:18:18.348Z'+ updated_at: '2026-07-21T16:18:18.348Z'patch:- summary: Update a custom field definition+ summary: Update a channeltags:- - Custom Fields+ - Channelssecurity:- api_key: []bearer_auth: []@@ -2300,14 +2463,13 @@ paths:secretKey: 'sk_xxx',})- const definition = await client.customFieldDefinitions.update('cfd_UkLWZg9DAJ', {- label: 'Country of Origin',- storefront_visible: false,+ const channel = await client.channels.update('channel_xxx', {+ name: 'Wholesale (Updated)',+ active: false,})- lang: bashlabel: Spree CLI- source: spree api patch /custom_field_definitions/{id} -d '{"label":"Country- of Origin","storefront_visible":false}'+ source: spree api patch /channels/{id} -d '{"name":"Wholesale (Updated)","active":false}'parameters:- name: x-spree-api-keyin: header@@ -2319,47 +2481,44 @@ paths:required: trueschema:type: string- - name: id- in: path- required: true- schema:- type: stringresponses:'200':- description: definition updated+ description: channel updatedcontent:application/json:example:- id: cfdef_UkLWZg9DAJ- namespace: specs- key: fabric- label: Fabric Composition- field_type: short_text- resource_type: Spree::Product- storefront_visible: false- created_at: '2026-07-20T06:56:40.740Z'- updated_at: '2026-07-20T06:56:41.020Z'+ id: ch_gbHJdmfrXB+ name: Wholesale (Updated)+ 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-07-21T16:18:18.643Z'+ updated_at: '2026-07-21T16:18:18.935Z'requestBody:content:application/json:schema:type: objectproperties:- label:+ name:type: string- storefront_visible:+ code:+ type: string+ active:type: booleandelete:- summary: Delete a custom field definition+ summary: Delete a channeltags:- - Custom Fields+ - Channelssecurity:- 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).+ description: "**Required scope:** `write_settings` (for API-key authentication)."x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2371,10 +2530,10 @@ paths:secretKey: 'sk_xxx',})- await client.customFieldDefinitions.delete('cfd_UkLWZg9DAJ')+ await client.channels.delete('channel_xxx')- lang: bashlabel: Spree CLI- source: spree api delete /custom_field_definitions/{id}+ source: spree api delete /channels/{id}parameters:- name: x-spree-api-keyin: header@@ -2386,32 +2545,30 @@ paths:required: trueschema:type: string- - name: id- in: path- required: true- schema:- type: stringresponses:'204':- description: definition deleted- "/api/v3/admin/customer_groups":- get:- summary: List customer groups+ 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:- - Customer Groups+ - Channelssecurity:- 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.+ 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:** `read_customers` (for API-key authentication).+ **Required scope:** `write_products` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2423,10 +2580,16 @@ paths:secretKey: 'sk_xxx',})- const { data: groups } = await client.customerGroups.list({ page: 1, limit: 25 })+ // 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 get /customer_groups -d '{"page":1,"limit":25}'+ 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@@ -2436,105 +2599,60 @@ 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: 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: customer groups found+ description: products publishedcontent:application/json:example:- data:- - id: cg_UkLWZg9DAJ- name: VIPs- description: Top spenders- customers_count: 0- created_at: '2026-07-20T06:56:41.327Z'- updated_at: '2026-07-20T06:56:41.327Z'- - id: cg_gbHJdmfrXB- name: Wholesale- description:- customers_count: 0- created_at: '2026-07-20T06:56:41.328Z'- updated_at: '2026-07-20T06:56:41.328Z'- meta:- page: 1- limit: 25- count: 2- pages: 1- from: 1- to: 2- in: 2- previous:- next:+ product_count: 1schema:type: objectproperties:- 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"+ 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: stringpost:- summary: Create a customer group+ summary: Unpublish products from a channeltags:- - Customer Groups+ - Channelssecurity:- 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.-+ Unpublishes the listed products from this channel.- **Required scope:** `write_customers` (for API-key authentication).+ **Required scope:** `write_products` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2546,15 +2664,12 @@ paths: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'],+ const { product_count } = await client.channels.removeProducts('channel_xxx', {+ product_ids: ['prod_xxx', 'prod_yyy'],})- lang: bashlabel: 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"]}'+ source: spree api post /channels/{id}/remove_products -d '{"product_ids":["prod_xxx","prod_yyy"]}'parameters:- name: x-spree-api-keyin: header@@ -2567,75 +2682,47 @@ paths:schema:type: stringresponses:- '201':- description: customer group created- content:- application/json:- example:- id: cg_EfhxLZ9ck8- name: Wholesale 2- description: B2B accounts- customers_count: 1- created_at: '2026-07-20T06:56:42.220Z'- updated_at: '2026-07-20T06:56:42.220Z'- schema:- "$ref": "#/components/schemas/CustomerGroup"- '422':- description: validation error+ '200':+ description: products unpublishedcontent:application/json:example:- error:- code: validation_error- message: Name can't be blank- details:- name:- - can't be blank+ product_count: 1schema:- "$ref": "#/components/schemas/ErrorResponse"+ type: object+ properties:+ product_count:+ type: integerrequestBody:content:application/json:schema:type: objectrequired:- - name+ - product_idsproperties:- name:- type: string- example: Wholesale- description:- type: string- example: B2B accounts- nullable: true- customer_ids:+ product_ids:type: arrayitems:type: string- example:- - cus_UkLWZg9DAJ- "/api/v3/admin/customer_groups/{id}":+ "/api/v3/admin/channels/{channel_id}/order_routing_rules":parameters:- - name: id+ - name: channel_idin: pathrequired: true- description: Customer group prefixed IDschema:type: stringget:- summary: Get a customer group+ summary: List order routing rules for a channeltags:- - Customer Groups+ - Channelssecurity:- 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).-+ Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.- **Required scope:** `read_customers` (for API-key authentication).+ **Required scope:** `read_settings` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2647,12 +2734,10 @@ paths: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'] })+ const { data: rules } = await client.channels.orderRoutingRules.list('ch_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api get /customer_groups/{id} -d '{"expand":["customers"]}'+ source: spree api get /channels/{channel_id}/order_routing_rulesparameters:- name: x-spree-api-keyin: header@@ -2664,87 +2749,69 @@ paths:required: 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: customer group with embedded customers- content:- application/json:- example:- id: cg_UkLWZg9DAJ- name: VIPs- description: Top spenders- customers_count: 1- created_at: '2026-07-20T06:56:42.815Z'- updated_at: '2026-07-20T06:56:42.815Z'- customers:- - id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Margart- last_name: Volkman- phone:- accepts_email_marketing: false- full_name: Margart Volkman- available_store_credit_total: '0'- display_available_store_credit_total: "$0.00"- login: [email protected]- metadata: {}- last_sign_in_at:- current_sign_in_at:- created_at: '2026-07-20T06:56:43.078Z'- updated_at: '2026-07-20T06:56:43.078Z'- sign_in_count: 0- failed_attempts: 0- last_sign_in_ip:- current_sign_in_ip:- tags: []- internal_note_html:- default_billing_address_id:- default_shipping_address_id:- orders_count: 0- total_spent: '0.0'- display_total_spent: "$0.00"- last_order_completed_at:- customer_group_ids:- - cg_UkLWZg9DAJ- schema:- "$ref": "#/components/schemas/CustomerGroup"- '404':- description: customer group not found+ description: rules foundcontent:application/json:example:- error:- code: record_not_found- message: Customer group not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update a customer group+ data:+ - id: orule_UkLWZg9DAJ+ position: 1+ active: true+ created_at: '2026-07-21T16:18:06.734Z'+ updated_at: '2026-07-21T16:18:06.734Z'+ 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-07-21T16:18:06.737Z'+ updated_at: '2026-07-21T16:18:06.737Z'+ 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-07-21T16:18:06.740Z'+ updated_at: '2026-07-21T16:18:06.740Z'+ 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:- - Customer Groups+ - Channelssecurity:- 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.-+ 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_customers` (for API-key authentication).+ **Required scope:** `write_settings` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2756,15 +2823,12 @@ paths: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'],+ const rule = await client.channels.orderRoutingRules.create('ch_UkLWZg9DAJ', {+ type: 'preferred_location',})- lang: bashlabel: Spree CLI- source: spree api patch /customer_groups/{id} -d '{"name":"VIP customers (Q1)","customer_ids":["cus_UkLWZg9DAJ"]}'+ source: spree api post /channels/{channel_id}/order_routing_rules -d '{"type":"preferred_location"}'parameters:- name: x-spree-api-keyin: header@@ -2777,62 +2841,71 @@ paths:schema:type: stringresponses:- '200':- description: customer group updated+ '201':+ description: rule createdcontent:application/json:example:- id: cg_UkLWZg9DAJ- name: VIP customers (Q1)- description: Top spenders- customers_count: 0- created_at: '2026-07-20T06:56:43.680Z'- updated_at: '2026-07-20T06:56:43.960Z'- schema:- "$ref": "#/components/schemas/CustomerGroup"+ id: orule_VqXmZF31wY+ position: 3+ active: true+ created_at: '2026-07-21T16:18:55.907Z'+ updated_at: '2026-07-21T16:18:55.907Z'+ type: default_location+ channel_id: ch_UkLWZg9DAJ+ preferences: {}+ preference_schema: []+ label: Default location+ description: Prefer the stock location marked as default'422':- description: validation error+ description: unknown rule typecontent:application/json:example:error:- code: validation_error- message: Name can't be blank- details:- name:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"+ code: unknown_order_routing_rule_type+ message: Unknown typerequestBody:content:application/json:schema:type: objectproperties:- name:- type: string- example: VIP customers (Q1)- description:+ type:type: string- example: Updated description- nullable: true- customer_ids:- type: array- items:- type: string- example:- - cus_UkLWZg9DAJ- delete:- summary: Delete a customer group+ 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 ruletags:- - Customer Groups+ - Channelssecurity:- api_key: []bearer_auth: []description: |-- Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.+ 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_customers` (for API-key authentication).+ **Required scope:** `write_settings` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2844,10 +2917,14 @@ paths:secretKey: 'sk_xxx',})- await client.customerGroups.delete('cg_UkLWZg9DAJ')+ const rule = await client.channels.orderRoutingRules.update('ch_UkLWZg9DAJ', 'orule_k5nR8xLq', {+ active: false,+ position: 2,+ })- lang: bashlabel: Spree CLI- source: spree api delete /customer_groups/{id}+ source: spree api patch /channels/{channel_id}/order_routing_rules/{id} -d+ '{"active":false,"position":2}'parameters:- name: x-spree-api-keyin: header@@ -2860,20 +2937,44 @@ paths:schema:type: stringresponses:- '204':- description: customer group deleted- "/api/v3/admin/customers/{customer_id}/addresses":- get:- summary: List customer addresses+ '200':+ description: rule updated+ content:+ application/json:+ example:+ id: orule_UkLWZg9DAJ+ position: 2+ active: false+ created_at: '2026-07-21T16:18:06.734Z'+ updated_at: '2026-07-21T16:18:56.483Z'+ type: preferred_location+ channel_id: ch_UkLWZg9DAJ+ preferences: {}+ preference_schema: []+ label: Preferred location+ description: Fulfill from the location pinned on the order, when one+ is set+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ active:+ type: boolean+ position:+ type: integer+ preferences:+ type: object+ additionalProperties: true+ delete:+ summary: Delete an order routing ruletags:- - Customers+ - Channelssecurity:- api_key: []bearer_auth: []- description: |-- Returns the customer's saved addresses.-- **Required scope:** `read_customers` (for API-key authentication).+ description: "**Required scope:** `write_settings` (for API-key authentication)."x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2885,10 +2986,10 @@ paths:secretKey: 'sk_xxx',})- const { data: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')+ await client.channels.orderRoutingRules.delete('ch_UkLWZg9DAJ', 'orule_k5nR8xLq')- lang: bashlabel: Spree CLI- source: spree api get /customers/{customer_id}/addresses+ source: spree api delete /channels/{channel_id}/order_routing_rules/{id}parameters:- name: x-spree-api-keyin: header@@ -2900,76 +3001,80 @@ paths:required: trueschema:type: string- - name: customer_id- in: path+ 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: headerrequired: trueschema: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.+ - name: Authorization+ in: header+ required: trueschema:type: stringresponses:'200':- description: addresses found+ description: types foundcontent:application/json:example:data:- - id: addr_UkLWZg9DAJ- first_name: John- last_name: Doe- full_name: John Doe- address1: 1 Lovely Street- address2: Northwest- postal_code: '10118'- city: New York- phone: 555-555-0199- company: Company- country_name: United States of America- country_iso: US- state_text: NY- state_abbr: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_name: New York- label:- metadata: {}- created_at: '2026-07-20T06:56:44.808Z'- updated_at: '2026-07-20T06:56:44.808Z'- customer_id: cus_UkLWZg9DAJ- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- post:- summary: Create a customer address+ - 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 definitionstags:- - Customers+ - Custom Fieldssecurity:- 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.+ Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.- **Required scope:** `write_customers` (for API-key authentication).+ **Required scope:** `read_settings` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -2981,23 +3086,12 @@ paths: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_iso: 'US',- state_abbr: 'NY',- phone: '+1 212 555 1234',- label: 'Office',- is_default_shipping: true,+ const { data: definitions } = await client.customFieldDefinitions.list({+ q: { resource_type_eq: 'Spree::Product' },})- lang: bashlabel: 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_iso":"US","state_abbr":"NY","phone":"+1- 212 555 1234","label":"Office","is_default_shipping":true}'+ source: spree api get /custom_field_definitions -d '{"q":{"resource_type_eq":"Spree::Product"}}'parameters:- name: x-spree-api-keyin: header@@ -3009,86 +3103,63 @@ paths:required: trueschema:type: string- - name: customer_id- in: path- required: true+ - 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:- '201':- description: address created+ '200':+ description: definitions returnedcontent:application/json:example:- id: addr_gbHJdmfrXB- 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 of America- country_iso: US- state_text: NY- state_abbr: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_name: New York- label: Office- metadata: {}- created_at: '2026-07-20T06:56:46.212Z'- updated_at: '2026-07-20T06:56:46.212Z'- customer_id: cus_UkLWZg9DAJ- 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_iso:- type: string- description: ISO-2 country code (e.g. US)- state_abbr:- 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+ data:+ - id: cfdef_UkLWZg9DAJ+ namespace: specs+ key: fabric+ label: Title+ field_type: short_text+ resource_type: Spree::Product+ storefront_visible: true+ created_at: '2026-07-21T16:18:20.299Z'+ updated_at: '2026-07-21T16:18:20.299Z'+ - id: cfdef_gbHJdmfrXB+ namespace: custom+ key: order_notes+ label: Order Notes+ field_type: short_text+ resource_type: Spree::Order+ storefront_visible: true+ created_at: '2026-07-21T16:18:20.300Z'+ updated_at: '2026-07-21T16:18:20.300Z'+ meta:+ page: 1+ limit: 25+ count: 2+ pages: 1+ from: 1+ to: 2+ in: 2+ previous:+ next:+ post:+ summary: Create a custom field definitiontags:- - Customers+ - Custom Fieldssecurity:- api_key: []bearer_auth: []- description: |-- Updates a customer address.-- **Required scope:** `write_customers` (for API-key authentication).+ description: "**Required scope:** `write_settings` (for API-key authentication)."x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3100,14 +3171,18 @@ paths:secretKey: 'sk_xxx',})- const address = await client.customers.addresses.update(- 'cus_UkLWZg9DAJ',- 'addr_UkLWZg9DAJ',- { city: 'Manhattan' },- )+ 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 patch /customers/{customer_id}/addresses/{id} -d '{"city":"Manhattan"}'+ 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@@ -3119,68 +3194,59 @@ paths:required: trueschema:type: string- - name: customer_id- in: path- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: stringresponses:- '200':- description: address updated+ '201':+ description: definition createdcontent:application/json:example:- id: addr_UkLWZg9DAJ- first_name: John- last_name: Doe- full_name: John Doe- address1: 3 Lovely Street- address2: Northwest- postal_code: '10118'- city: Manhattan- phone: 555-555-0199- company: Company- country_name: United States of America- country_iso: US- state_text: NY- state_abbr: NY- quick_checkout: false- is_default_billing: false- is_default_shipping: false- state_name: New York- label:- metadata: {}- created_at: '2026-07-20T06:56:46.492Z'- updated_at: '2026-07-20T06:56:47.048Z'- customer_id: cus_UkLWZg9DAJ+ id: cfdef_EfhxLZ9ck8+ namespace: specs+ key: origin+ label: Country of Origin+ field_type: short_text+ resource_type: Spree::Product+ storefront_visible: true+ created_at: '2026-07-21T16:18:20.861Z'+ updated_at: '2026-07-21T16:18:20.861Z'requestBody:content:application/json:schema:type: object+ required:+ - key+ - field_type+ - resource_typeproperties:- city:+ namespace:type: string- is_default_billing:- type: boolean- is_default_shipping:+ 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- delete:- summary: Delete a customer address+ description: 'When false, definition is admin-only (was `display_on:+ back_end`)'+ "/api/v3/admin/custom_field_definitions/{id}":+ get:+ summary: Show a custom field definitiontags:- - Customers+ - Custom Fieldssecurity:- 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).+ description: "**Required scope:** `read_settings` (for API-key authentication)."x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3192,10 +3258,10 @@ paths:secretKey: 'sk_xxx',})- await client.customers.addresses.delete('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ')+ const definition = await client.customFieldDefinitions.get('cfd_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /customers/{customer_id}/addresses/{id}+ source: spree api get /custom_field_definitions/{id}parameters:- name: x-spree-api-keyin: header@@ -3207,31 +3273,48 @@ paths:required: trueschema:type: string- - name: customer_id+ - name: idin: pathrequired: trueschema:type: string- - name: id- in: path- required: true+ - 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:- '204':- description: address deleted- "/api/v3/admin/customers/{customer_id}/credit_cards":- get:- summary: List customer credit cards+ '200':+ description: definition found+ content:+ application/json:+ example:+ id: cfdef_UkLWZg9DAJ+ namespace: specs+ key: fabric+ label: Title+ field_type: short_text+ resource_type: Spree::Product+ storefront_visible: true+ created_at: '2026-07-21T16:18:20.864Z'+ updated_at: '2026-07-21T16:18:20.864Z'+ patch:+ summary: Update a custom field definitiontags:- - Customers+ - Custom Fieldssecurity:- 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).+ description: "**Required scope:** `write_settings` (for API-key authentication)."x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3243,10 +3326,14 @@ paths:secretKey: 'sk_xxx',})- const { data: cards } = await client.customers.creditCards.list('cus_UkLWZg9DAJ')+ const definition = await client.customFieldDefinitions.update('cfd_UkLWZg9DAJ', {+ label: 'Country of Origin',+ storefront_visible: false,+ })- lang: bashlabel: Spree CLI- source: spree api get /customers/{customer_id}/credit_cards+ source: spree api patch /custom_field_definitions/{id} -d '{"label":"Country+ of Origin","storefront_visible":false}'parameters:- name: x-spree-api-keyin: header@@ -3258,147 +3345,47 @@ paths:required: trueschema:type: string- - name: customer_id+ - name: idin: pathrequired: trueschema: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:'200':- description: credit cards found+ description: definition updatedcontent:application/json:example:- data:- - id: card_UkLWZg9DAJ- brand: visa- last4: '1111'- month: 12- year: 2027- name: Spree Commerce- default: false- gateway_payment_profile_id:- customer_id: cus_UkLWZg9DAJ- payment_method_id: pm_UkLWZg9DAJ- metadata: {}- created_at: '2026-07-20T06:56:48.143Z'- updated_at: '2026-07-20T06:56:48.143Z'- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- "/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- content:- application/json:- example:- id: card_UkLWZg9DAJ- brand: visa- last4: '1111'- month: 12- year: 2027- name: Spree Commerce- default: false- gateway_payment_profile_id:- customer_id: cus_UkLWZg9DAJ- payment_method_id: pm_UkLWZg9DAJ- metadata: {}- created_at: '2026-07-20T06:56:48.690Z'- updated_at: '2026-07-20T06:56:48.690Z'+ id: cfdef_UkLWZg9DAJ+ namespace: specs+ key: fabric+ label: Fabric Composition+ field_type: short_text+ resource_type: Spree::Product+ storefront_visible: false+ created_at: '2026-07-21T16:18:21.146Z'+ updated_at: '2026-07-21T16:18:21.428Z'+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ label:+ type: string+ storefront_visible:+ type: booleandelete:- summary: Delete a customer credit card+ summary: Delete a custom field definitiontags:- - Customers+ - Custom Fieldssecurity:- api_key: []bearer_auth: []description: |-- Deletes a saved credit card.+ Deletes the definition and cascades to all custom field values referencing it.- **Required scope:** `write_customers` (for API-key authentication).+ **Required scope:** `write_settings` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3410,10 +3397,10 @@ paths:secretKey: 'sk_xxx',})- await client.customers.creditCards.delete('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')+ await client.customFieldDefinitions.delete('cfd_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /customers/{customer_id}/credit_cards/{id}+ source: spree api delete /custom_field_definitions/{id}parameters:- name: x-spree-api-keyin: header@@ -3425,11 +3412,6 @@ paths:required: trueschema:type: string- - name: customer_id- in: path- required: true- schema:- type: string- name: idin: pathrequired: true@@ -3437,19 +3419,25 @@ paths:type: stringresponses:'204':- description: credit card deleted- "/api/v3/admin/customers/{customer_id}/store_credits":+ description: definition deleted+ "/api/v3/admin/customer_groups":get:- summary: List customer store credits+ summary: List customer groupstags:- - Customers+ - Customer Groupssecurity:- api_key: []bearer_auth: []description: |-- Returns store credits issued to the customer.+ 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_store_credits` (for API-key authentication).++ **Required scope:** `read_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3461,10 +3449,10 @@ paths:secretKey: 'sk_xxx',})- const { data: storeCredits } = await client.customers.storeCredits.list('cus_UkLWZg9DAJ')+ const { data: groups } = await client.customerGroups.list({ page: 1, limit: 25 })- lang: bashlabel: Spree CLI- source: spree api get /customers/{customer_id}/store_credits+ source: spree api get /customer_groups -d '{"page":1,"limit":25}'parameters:- name: x-spree-api-keyin: header@@ -3474,71 +3462,105 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- - name: customer_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[name_cont]+ in: query+ required: false+ description: Filter by name (contains)schema:type: string- - name: expand+ - name: sortin: queryrequired: false- description: Comma-separated associations to expand (e.g., category, store,- created_by). 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., amount,amount_used,memo,currency).- id is always included.+ description: Comma-separated list of fields to include. id is always included.schema:type: stringresponses:'200':- description: store credits found+ description: customer groups foundcontent:application/json:example: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-07-20T06:56:50.083Z'- updated_at: '2026-07-20T06:56:50.083Z'- customer_id: cus_UkLWZg9DAJ- created_by_id: admin_UkLWZg9DAJ- category_id: sccat_UkLWZg9DAJ- category_name: Exchange+ - id: cg_UkLWZg9DAJ+ name: VIPs+ description: Top spenders+ customers_count: 0+ created_at: '2026-07-21T16:18:21.719Z'+ updated_at: '2026-07-21T16:18:21.719Z'+ - id: cg_gbHJdmfrXB+ name: Wholesale+ description:+ customers_count: 0+ created_at: '2026-07-21T16:18:21.720Z'+ updated_at: '2026-07-21T16:18:21.720Z'meta:page: 1limit: 25- count: 1+ count: 2pages: 1from: 1- to: 1- in: 1+ to: 2+ in: 2previous: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: Issue a store credit to a customer+ summary: Create a customer grouptags:- - Customers+ - Customer Groupssecurity:- api_key: []bearer_auth: []description: |-- `created_by` is set automatically from the authenticated admin.+ 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_store_credits` (for API-key authentication).++ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3550,16 +3572,15 @@ paths:secretKey: 'sk_xxx',})- const credit = await client.customers.storeCredits.create('cus_UkLWZg9DAJ', {- amount: '25.00',- currency: 'USD',- category_id: 'cat_UkLWZg9DAJ',- memo: 'Goodwill credit',+ 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 /customers/{customer_id}/store_credits -d '{"amount":"25.00","currency":"USD","category_id":"cat_UkLWZg9DAJ","memo":"Goodwill- credit"}'+ 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: header@@ -3571,66 +3592,76 @@ paths:required: trueschema:type: string- - name: customer_id- in: path- required: true- schema:- type: stringresponses:'201':- description: store credit created+ description: customer group createdcontent:application/json:example:- 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-07-20T06:56:51.177Z'- updated_at: '2026-07-20T06:56:51.177Z'- customer_id: cus_UkLWZg9DAJ- created_by_id: admin_gbHJdmfrXB- category_id: sccat_UkLWZg9DAJ- category_name: Exchange+ id: cg_EfhxLZ9ck8+ name: Wholesale 2+ description: B2B accounts+ customers_count: 1+ created_at: '2026-07-21T16:18:22.575Z'+ updated_at: '2026-07-21T16:18:22.575Z'+ 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: objectrequired:- - amount- - currency- - category_id+ - nameproperties:- amount:- type: string- example: '50.00'- currency:- type: string- example: USD- category_id:+ name:type: string- description: StoreCreditCategory ID- memo:+ example: Wholesale+ description:type: string- "/api/v3/admin/customers/{customer_id}/store_credits/{id}":- patch:- summary: Update a store credit+ 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:- - Customers+ - Customer Groupssecurity:- api_key: []bearer_auth: []description: |-- Update memo / category / amount. The amount can only be changed if `amount_used == 0`.+ 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:** `write_store_credits` (for API-key authentication).++ **Required scope:** `read_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3642,15 +3673,12 @@ paths:secretKey: 'sk_xxx',})- const credit = await client.customers.storeCredits.update(- 'cus_UkLWZg9DAJ',- 'sc_UkLWZg9DAJ',- { memo: 'Reissued for damaged shipment' },- )+ // 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 /customers/{customer_id}/store_credits/{id} -d '{"memo":"Reissued- for damaged shipment"}'+ source: spree api get /customer_groups/{id} -d '{"expand":["customers"]}'parameters:- name: x-spree-api-keyin: header@@ -3662,62 +3690,175 @@ paths:required: trueschema:type: string- - name: customer_id- in: path+ - 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:+ example:+ id: cg_UkLWZg9DAJ+ name: VIPs+ description: Top spenders+ customers_count: 1+ created_at: '2026-07-21T16:18:23.162Z'+ updated_at: '2026-07-21T16:18:23.162Z'+ customers:+ - id: cus_UkLWZg9DAJ+ email: [email protected]+ first_name: Rochelle+ last_name: O'Conner+ phone:+ accepts_email_marketing: false+ full_name: Rochelle O'Conner+ available_store_credit_total: '0'+ display_available_store_credit_total: "$0.00"+ login: [email protected]+ metadata: {}+ last_sign_in_at:+ current_sign_in_at:+ created_at: '2026-07-21T16:18:23.424Z'+ updated_at: '2026-07-21T16:18:23.424Z'+ sign_in_count: 0+ failed_attempts: 0+ last_sign_in_ip:+ current_sign_in_ip:+ tags: []+ internal_note_html:+ default_billing_address_id:+ default_shipping_address_id:+ orders_count: 0+ total_spent: '0.0'+ display_total_spent: "$0.00"+ last_order_completed_at:+ customer_group_ids:+ - cg_UkLWZg9DAJ+ schema:+ "$ref": "#/components/schemas/CustomerGroup"+ '404':+ description: customer group not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Customer group not found+ 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: headerrequired: trueschema:type: string- - name: id- in: path+ - name: Authorization+ in: headerrequired: trueschema:type: stringresponses:'200':- description: store credit updated+ description: customer group updatedcontent:application/json:example:- 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-07-20T06:56:51.714Z'- updated_at: '2026-07-20T06:56:51.997Z'- customer_id: cus_UkLWZg9DAJ- created_by_id: admin_UkLWZg9DAJ- category_id: sccat_UkLWZg9DAJ- category_name: Exchange+ id: cg_UkLWZg9DAJ+ name: VIP customers (Q1)+ description: Top spenders+ customers_count: 0+ created_at: '2026-07-21T16:18:24.006Z'+ updated_at: '2026-07-21T16:18:24.286Z'+ 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: objectproperties:- amount:- type: string- example: '50.00'- category_id:+ name:type: string- memo:+ example: VIP customers (Q1)+ description:type: string+ example: Updated description+ nullable: true+ customer_ids:+ type: array+ items:+ type: string+ example:+ - cus_UkLWZg9DAJdelete:- summary: Delete a store credit+ summary: Delete a customer grouptags:- - Customers+ - Customer Groupssecurity:- api_key: []bearer_auth: []description: |-- Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.+ Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.- **Required scope:** `write_store_credits` (for API-key authentication).+ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -3729,10 +3870,10 @@ paths:secretKey: 'sk_xxx',})- await client.customers.storeCredits.delete('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ')+ await client.customerGroups.delete('cg_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /customers/{customer_id}/store_credits/{id}+ source: spree api delete /customer_groups/{id}parameters:- name: x-spree-api-keyin: header@@ -3744,29 +3885,19 @@ paths:required: trueschema:type: string- - name: customer_id- in: path- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: stringresponses:'204':- description: store credit deleted- "/api/v3/admin/customers":+ description: customer group deleted+ "/api/v3/admin/customers/{customer_id}/addresses":get:- summary: List customers+ summary: List customer addressestags:- Customerssecurity:- api_key: []bearer_auth: []description: |-- Returns a paginated list of customers. Supports Ransack search/filters.+ Returns the customer's saved addresses.**Required scope:** `read_customers` (for API-key authentication).x-codeSamples:@@ -3780,14 +3911,10 @@ paths:secretKey: 'sk_xxx',})- const { data: customers } = await client.customers.list({- search: 'jane',- sort: '-created_at',- limit: 25,- })+ const { data: addresses } = await client.customers.addresses.list('cus_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api get /customers -d '{"search":"jane","sort":"-created_at","limit":25}'+ source: spree api get /customers/{customer_id}/addressesparameters:- name: x-spree-api-keyin: header@@ -3797,74 +3924,57 @@ 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- schema:- type: integer- - name: q[search]- in: query- required: false- description: Email + name full-text-ish search+ - name: customer_id+ in: path+ required: trueschema:type: string- name: expandin: queryrequired: false- description: Comma-separated associations to expand (e.g., addresses, store_credits).+ 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., email,first_name,last_name).+ 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: customers found+ description: addresses foundcontent:application/json:example:data:- - id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Jane+ - id: addr_UkLWZg9DAJ+ first_name: Johnlast_name: Doe- phone:- accepts_email_marketing: false- full_name: Jane Doe- available_store_credit_total: '0'- display_available_store_credit_total: "$0.00"- login: [email protected]+ full_name: John Doe+ address1: 1 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: New York+ phone: 555-555-0199+ company: Company+ country_name: United States of America+ country_iso: US+ state_text: NY+ state_abbr: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_name: New York+ label:metadata: {}- last_sign_in_at:- current_sign_in_at:- created_at: '2026-07-20T06:56:53.092Z'- updated_at: '2026-07-20T06:56:53.092Z'- sign_in_count: 0- failed_attempts: 0- last_sign_in_ip:- current_sign_in_ip:- tags: []- 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: []+ created_at: '2026-07-21T16:18:25.146Z'+ updated_at: '2026-07-21T16:18:25.146Z'+ customer_id: cus_UkLWZg9DAJmeta:page: 1limit: 25@@ -3876,14 +3986,14 @@ paths:previous:next:post:- summary: Create a customer+ summary: Create a customer addresstags:- Customerssecurity:- api_key: []bearer_auth: []description: |-- Creates a customer. No welcome email is sent automatically.+ 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:@@ -3897,18 +4007,23 @@ paths:secretKey: 'sk_xxx',})- const customer = await client.customers.create({- email: '[email protected]',+ 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_iso: 'US',+ state_abbr: 'NY',phone: '+1 212 555 1234',- tags: ['wholesale'],- accepts_email_marketing: true,+ label: 'Office',+ is_default_shipping: true,})- lang: bashlabel: 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}'+ 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_iso":"US","state_abbr":"NY","phone":"+1+ 212 555 1234","label":"Office","is_default_shipping":true}'parameters:- name: x-spree-api-keyin: header@@ -3920,79 +4035,86 @@ paths:required: trueschema:type: string+ - name: customer_id+ in: path+ required: true+ schema:+ type: stringresponses:'201':- description: customer created+ description: address createdcontent:application/json:example:- id: cus_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"- login:+ id: addr_gbHJdmfrXB+ 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 of America+ country_iso: US+ state_text: NY+ state_abbr: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_name: New York+ label: Officemetadata: {}- last_sign_in_at:- current_sign_in_at:- created_at: '2026-07-20T06:56:53.943Z'- updated_at: '2026-07-20T06:56:53.943Z'- sign_in_count: 0- failed_attempts: 0- last_sign_in_ip:- current_sign_in_ip:- tags: []- 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: []+ created_at: '2026-07-21T16:18:26.507Z'+ updated_at: '2026-07-21T16:18:26.507Z'+ customer_id: cus_UkLWZg9DAJrequestBody:content:application/json:schema:type: object- required:properties:- email:- type: string- example: [email protected]first_name:type: stringlast_name:type: string+ address1:+ type: string+ address2:+ type: string+ city:+ type: string+ postal_code:+ type: string+ country_iso:+ type: string+ description: ISO-2 country code (e.g. US)+ state_abbr:+ type: string+ description: State/province abbreviation (e.g. NY)phone:type: string- accepts_email_marketing:- type: boolean- internal_note:+ company:type: string- tags:- type: array- items:- type: string- metadata:- type: object- "/api/v3/admin/customers/{id}":- get:- summary: Show a customer+ 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 addresstags:- Customerssecurity:- api_key: []bearer_auth: []description: |-- Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).+ Updates a customer address.- **Required scope:** `read_customers` (for API-key authentication).+ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4004,12 +4126,14 @@ paths:secretKey: 'sk_xxx',})- const customer = await client.customers.get('cus_UkLWZg9DAJ', {- expand: ['addresses', 'store_credits'],- })+ const address = await client.customers.addresses.update(+ 'cus_UkLWZg9DAJ',+ 'addr_UkLWZg9DAJ',+ { city: 'Manhattan' },+ )- lang: bashlabel: Spree CLI- source: spree api get /customers/{id} -d '{"expand":["addresses","store_credits"]}'+ source: spree api patch /customers/{customer_id}/addresses/{id} -d '{"city":"Manhattan"}'parameters:- name: x-spree-api-keyin: header@@ -4021,172 +4145,66 @@ paths:required: trueschema:type: string- - name: id+ - name: customer_idin: pathrequired: 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.+ - name: id+ in: path+ required: trueschema:type: stringresponses:'200':- description: customer found+ description: address updatedcontent:application/json:example:- id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Jane+ id: addr_UkLWZg9DAJ+ first_name: Johnlast_name: Doe- phone:- accepts_email_marketing: false- full_name: Jane Doe- available_store_credit_total: '0'- display_available_store_credit_total: "$0.00"- login: [email protected]- metadata: {}- last_sign_in_at:- current_sign_in_at:- created_at: '2026-07-20T06:56:54.214Z'- updated_at: '2026-07-20T06:56:54.214Z'- sign_in_count: 0- failed_attempts: 0- last_sign_in_ip:- current_sign_in_ip:- tags: []- 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 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- content:- application/json:- example:- id: cus_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"- login: [email protected]+ full_name: John Doe+ address1: 3 Lovely Street+ address2: Northwest+ postal_code: '10118'+ city: Manhattan+ phone: 555-555-0199+ company: Company+ country_name: United States of America+ country_iso: US+ state_text: NY+ state_abbr: NY+ quick_checkout: false+ is_default_billing: false+ is_default_shipping: false+ state_name: New York+ label:metadata: {}- last_sign_in_at:- current_sign_in_at:- created_at: '2026-07-20T06:56:54.795Z'- updated_at: '2026-07-20T06:56:55.079Z'- sign_in_count: 0- failed_attempts: 0- last_sign_in_ip:- current_sign_in_ip:- tags: []- 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: []+ created_at: '2026-07-21T16:18:26.777Z'+ updated_at: '2026-07-21T16:18:27.325Z'+ customer_id: cus_UkLWZg9DAJrequestBody:content:application/json:schema:type: objectproperties:- email:- type: string- first_name:- type: string- last_name:- type: string- phone:+ city:type: string- accepts_email_marketing:+ is_default_billing:+ type: boolean+ is_default_shipping:type: boolean- internal_note:- type: string- tags:- type: array- items:- type: string- metadata:- type: objectdelete:- summary: Delete a customer+ summary: Delete a customer addresstags:- Customerssecurity:- api_key: []bearer_auth: []description: |-- Deletes a customer. Returns 422 if the customer has any orders.+ 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:@@ -4200,10 +4218,10 @@ paths:secretKey: 'sk_xxx',})- await client.customers.delete('cus_UkLWZg9DAJ')+ await client.customers.addresses.delete('cus_UkLWZg9DAJ', 'addr_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /customers/{id}+ source: spree api delete /customers/{customer_id}/addresses/{id}parameters:- name: x-spree-api-keyin: header@@ -4215,6 +4233,11 @@ paths:required: trueschema:type: string+ - name: customer_id+ in: path+ required: true+ schema:+ type: string- name: idin: pathrequired: true@@ -4222,23 +4245,19 @@ paths:type: stringresponses:'204':- description: customer deleted- "/api/v3/admin/customers/bulk_add_to_groups":- post:- summary: Bulk-add customers to groups+ description: address deleted+ "/api/v3/admin/customers/{customer_id}/credit_cards":+ get:+ summary: List customer credit cardstags:- Customerssecurity:- 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).-+ Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.- **Required scope:** `write_customers` (for API-key authentication).+ **Required scope:** `read_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4250,13 +4269,10 @@ paths:secretKey: 'sk_xxx',})- const result = await client.customers.bulkAddToGroups({- ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],- customer_group_ids: ['cg_UkLWZg9DAJ'],- })+ const { data: cards } = await client.customers.creditCards.list('cus_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api post /customers/bulk_add_to_groups -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'+ source: spree api get /customers/{customer_id}/credit_cardsparameters:- name: x-spree-api-keyin: header@@ -4268,57 +4284,67 @@ paths:required: trueschema: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: stringresponses:'200':- description: customers added to groups+ description: credit cards foundcontent:application/json:example:- customer_count: 1- customer_group_count: 1- 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+ data:+ - id: card_UkLWZg9DAJ+ brand: visa+ last4: '1111'+ month: 12+ year: 2027+ name: Spree Commerce+ default: false+ gateway_payment_profile_id:+ customer_id: cus_UkLWZg9DAJ+ payment_method_id: pm_UkLWZg9DAJ+ metadata: {}+ created_at: '2026-07-21T16:18:28.495Z'+ updated_at: '2026-07-21T16:18:28.495Z'+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ "/api/v3/admin/customers/{customer_id}/credit_cards/{id}":+ get:+ summary: Show a customer credit cardtags:- Customerssecurity:- 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.-+ Returns a saved credit card by ID.- **Required scope:** `write_customers` (for API-key authentication).+ **Required scope:** `read_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4330,13 +4356,10 @@ paths:secretKey: 'sk_xxx',})- const result = await client.customers.bulkRemoveFromGroups({- ids: ['cus_UkLWZg9DAJ'],- customer_group_ids: ['cg_UkLWZg9DAJ'],- })+ const card = await client.customers.creditCards.get('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api post /customers/bulk_remove_from_groups -d '{"ids":["cus_UkLWZg9DAJ"],"customer_group_ids":["cg_UkLWZg9DAJ"]}'+ source: spree api get /customers/{customer_id}/credit_cards/{id}parameters:- name: x-spree-api-keyin: header@@ -4348,54 +4371,58 @@ paths:required: trueschema:type: string- responses:- '200':- description: customers removed from groups- content:- application/json:- example:- customer_count: 1- customer_group_count: 1- 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+ - 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:+ example:+ id: card_UkLWZg9DAJ+ brand: visa+ last4: '1111'+ month: 12+ year: 2027+ name: Spree Commerce+ default: false+ gateway_payment_profile_id:+ customer_id: cus_UkLWZg9DAJ+ payment_method_id: pm_UkLWZg9DAJ+ metadata: {}+ created_at: '2026-07-21T16:18:29.063Z'+ updated_at: '2026-07-21T16:18:29.063Z'+ delete:+ summary: Delete a customer credit cardtags:- Customerssecurity:- 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.-+ Deletes a saved credit card.**Required scope:** `write_customers` (for API-key authentication).x-codeSamples:@@ -4409,13 +4436,10 @@ paths:secretKey: 'sk_xxx',})- const result = await client.customers.bulkAddTags({- ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],- tags: ['vip', 'newsletter'],- })+ await client.customers.creditCards.delete('cus_UkLWZg9DAJ', 'cc_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api post /customers/bulk_add_tags -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"tags":["vip","newsletter"]}'+ source: spree api delete /customers/{customer_id}/credit_cards/{id}parameters:- name: x-spree-api-keyin: header@@ -4427,57 +4451,31 @@ paths:required: trueschema:type: string+ - name: customer_id+ in: path+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:- '200':- description: tags added- content:- application/json:- example:- customer_count: 1- tag_count: 2- 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+ '204':+ description: credit card deleted+ "/api/v3/admin/customers/{customer_id}/store_credits":+ get:+ summary: List customer store creditstags:- Customerssecurity:- 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.-+ Returns store credits issued to the customer.- **Required scope:** `write_customers` (for API-key authentication).+ **Required scope:** `read_store_credits` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4489,13 +4487,10 @@ paths:secretKey: 'sk_xxx',})- const result = await client.customers.bulkRemoveTags({- ids: ['cus_UkLWZg9DAJ'],- tags: ['vip'],- })+ const { data: storeCredits } = await client.customers.storeCredits.list('cus_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api post /customers/bulk_remove_tags -d '{"ids":["cus_UkLWZg9DAJ"],"tags":["vip"]}'+ source: spree api get /customers/{customer_id}/store_creditsparameters:- name: x-spree-api-keyin: header@@ -4507,54 +4502,69 @@ paths:required: trueschema: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., category, 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: tags removed+ description: store credits foundcontent:application/json:example:- customer_count: 1- tag_count: 1- schema:- type: object- properties:- customer_count:- type: integer- tag_count:- type: integer- requestBody:- content:- application/json:- schema:- type: object- required:- - ids- - tags- properties:- ids:- type: array- items:- type: string- example:- - cus_UkLWZg9DAJ- tags:- type: array- items:- type: string- example:- - vip- "/api/v3/admin/exports":- get:- summary: List exports+ 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-07-21T16:18:30.437Z'+ updated_at: '2026-07-21T16:18:30.437Z'+ customer_id: cus_UkLWZg9DAJ+ created_by_id: admin_UkLWZg9DAJ+ category_id: sccat_UkLWZg9DAJ+ category_name: Exchange+ 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 customertags:- - Exports+ - Customerssecurity:- 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`).+ `created_by` is set automatically from the authenticated admin.- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).+ **Required scope:** `write_store_credits` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4566,85 +4576,16 @@ paths:secretKey: 'sk_xxx',})- const { data: exports } = await client.exports.list()+ const credit = await client.customers.storeCredits.create('cus_UkLWZg9DAJ', {+ amount: '25.00',+ currency: 'USD',+ category_id: 'cat_UkLWZg9DAJ',+ memo: 'Goodwill credit',+ })- lang: bashlabel: 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- content:- application/json:- example:- data:- - id: exp_UkLWZg9DAJ- number: EF757881116- type: Spree::Exports::Products- format: csv- created_at: '2026-07-20T06:56:59.301Z'- updated_at: '2026-07-20T06:56:59.301Z'- user_id: admin_UkLWZg9DAJ- done: false- filename:- byte_size:- download_url:- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- 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"}}'+ source: spree api post /customers/{customer_id}/store_credits -d '{"amount":"25.00","currency":"USD","category_id":"cat_UkLWZg9DAJ","memo":"Goodwill+ credit"}'parameters:- name: x-spree-api-keyin: header@@ -4656,75 +4597,66 @@ paths:required: trueschema:type: string+ - name: customer_id+ in: path+ required: true+ schema:+ type: stringresponses:'201':- description: export queued+ description: store credit createdcontent:application/json:example:- id: exp_gbHJdmfrXB- number: EF462086219- type: Spree::Exports::Products- format: csv- created_at: '2026-07-20T06:56:59.603Z'- updated_at: '2026-07-20T06:56:59.603Z'- user_id: admin_UkLWZg9DAJ- done: false- filename:- byte_size:- download_url:+ 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-07-21T16:18:31.550Z'+ updated_at: '2026-07-21T16:18:31.550Z'+ customer_id: cus_UkLWZg9DAJ+ created_by_id: admin_gbHJdmfrXB+ category_id: sccat_UkLWZg9DAJ+ category_name: ExchangerequestBody:content:application/json:schema:type: objectrequired:- - type+ - amount+ - currency+ - category_idproperties:- type:+ amount:type: string- enum:- - Spree::Exports::Products- - Spree::Exports::Orders- - Spree::Exports::Customers- - Spree::Exports::ProductTranslations- - Spree::Exports::GiftCards- - Spree::Exports::CouponCodes- - Spree::Exports::NewsletterSubscribers- example: Spree::Exports::Products- record_selection:+ example: '50.00'+ currency: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:+ example: USD+ category_id: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+ description: StoreCreditCategory ID+ memo:+ type: string+ "/api/v3/admin/customers/{customer_id}/store_credits/{id}":+ patch:+ summary: Update a store credittags:- - Exports+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Returns export status. While `done` is `false`, the SPA continues polling.+ Update memo / category / amount. The amount can only be changed if `amount_used == 0`.- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).+ **Required scope:** `write_store_credits` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4736,10 +4668,15 @@ paths:secretKey: 'sk_xxx',})- const exp = await client.exports.get('exp_xxx')+ const credit = await client.customers.storeCredits.update(+ 'cus_UkLWZg9DAJ',+ 'sc_UkLWZg9DAJ',+ { memo: 'Reissued for damaged shipment' },+ )- lang: bashlabel: Spree CLI- source: spree api get /exports/{id}+ source: spree api patch /customers/{customer_id}/store_credits/{id} -d '{"memo":"Reissued+ for damaged shipment"}'parameters:- name: x-spree-api-keyin: header@@ -4751,6 +4688,11 @@ paths:required: trueschema:type: string+ - name: customer_id+ in: path+ required: true+ schema:+ type: string- name: idin: pathrequired: true@@ -4758,32 +4700,50 @@ paths:type: stringresponses:'200':- description: export found+ description: store credit updatedcontent:application/json:example:- id: exp_UkLWZg9DAJ- number: EF772243802- type: Spree::Exports::Products- format: csv- created_at: '2026-07-20T06:56:59.875Z'- updated_at: '2026-07-20T06:56:59.875Z'- user_id: admin_UkLWZg9DAJ- done: false- filename:- byte_size:- download_url:+ 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-07-21T16:18:32.094Z'+ updated_at: '2026-07-21T16:18:32.383Z'+ customer_id: cus_UkLWZg9DAJ+ created_by_id: admin_UkLWZg9DAJ+ category_id: sccat_UkLWZg9DAJ+ category_name: Exchange+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ amount:+ type: string+ example: '50.00'+ category_id:+ type: string+ memo:+ type: stringdelete:- summary: Delete an export+ summary: Delete a store credittags:- - Exports+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Removes the export and purges its attachment.+ Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).+ **Required scope:** `write_store_credits` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4795,10 +4755,10 @@ paths:secretKey: 'sk_xxx',})- await client.exports.delete('exp_xxx')+ await client.customers.storeCredits.delete('cus_UkLWZg9DAJ', 'sc_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /exports/{id}+ source: spree api delete /customers/{customer_id}/store_credits/{id}parameters:- name: x-spree-api-keyin: header@@ -4810,6 +4770,11 @@ paths:required: trueschema:type: string+ - name: customer_id+ in: path+ required: true+ schema:+ type: string- name: idin: pathrequired: true@@ -4817,19 +4782,19 @@ paths:type: stringresponses:'204':- description: export deleted- "/api/v3/admin/exports/{id}/download":+ description: store credit deleted+ "/api/v3/admin/customers":get:- summary: Download an export+ summary: List customerstags:- - Exports+ - Customerssecurity:- 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.+ Returns a paginated list of customers. Supports Ransack search/filters.- **Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).+ **Required scope:** `read_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -4841,21 +4806,14 @@ paths: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+ const { data: customers } = await client.customers.list({+ search: 'jane',+ sort: '-created_at',+ limit: 25,})- a.click()- URL.revokeObjectURL(url)- lang: bashlabel: Spree CLI- source: spree api get /exports/{id}/download+ source: spree api get /customers -d '{"search":"jane","sort":"-created_at","limit":25}'parameters:- name: x-spree-api-keyin: header@@ -4865,119 +4823,74 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- - name: id- in: path- required: true+ - name: page+ in: query+ required: falseschema:- 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.-- **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- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication+ type: integer+ - name: limit+ in: query+ required: falseschema:- type: string- - name: order_id- in: path- required: true- description: Order ID+ type: integer+ - name: q[search]+ in: query+ required: false+ description: Email + name full-text-ish searchschema:type: string- name: expandin: 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: Comma-separated associations to expand (e.g., addresses, store_credits).+ 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).+ description: Comma-separated list of fields to include (e.g., email,first_name,last_name).id is always included.schema:type: stringresponses:'200':- description: fulfillments found+ description: customers foundcontent:application/json:example:data:- - id: ful_UkLWZg9DAJ- number: H17931544429- tracking: U10000- tracking_url:- 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: ready- fulfillment_type: shipping- fulfilled_at:- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1+ - id: cus_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"+ login: [email protected]metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:15.157Z'- updated_at: '2026-07-20T06:57:15.228Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_UkLWZg9DAJ+ last_sign_in_at:+ current_sign_in_at:+ created_at: '2026-07-21T16:18:33.470Z'+ updated_at: '2026-07-21T16:18:33.470Z'+ sign_in_count: 0+ failed_attempts: 0+ last_sign_in_ip:+ current_sign_in_ip:+ tags: []+ 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@@ -4989,16 +4902,16 @@ paths:previous:next:post:- summary: Create a fulfillment+ summary: Create a customertags:- - Fulfillments+ - Customerssecurity:- 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).+ Creates a customer. No welcome email is sent automatically.- **Required scope:** `write_fulfillments` (for API-key authentication).+ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5010,16 +4923,18 @@ 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 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 /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 /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@@ -5029,127 +4944,81 @@ 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: fulfillment created+ description: customer createdcontent:application/json:example:- id: ful_gbHJdmfrXB- number: H50469820256- tracking: INPOST-12345- tracking_url:- 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: shipped- fulfillment_type: shipping- fulfilled_at: '2026-07-20T06:57:16Z'- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1+ id: cus_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"+ login:metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:16.179Z'- updated_at: '2026-07-20T06:57:16.196Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_UkLWZg9DAJ- '422':- description: order not completed- content:- application/json:- example:- error:- code: processing_error- message: Fulfillments can only be created manually on completed- orders+ last_sign_in_at:+ current_sign_in_at:+ created_at: '2026-07-21T16:18:34.296Z'+ updated_at: '2026-07-21T16:18:34.296Z'+ sign_in_count: 0+ failed_attempts: 0+ last_sign_in_ip:+ current_sign_in_ip:+ tags: []+ 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:- - stock_location_idproperties:- stock_location_id:+ email:type: string- description: Stock location the fulfillment ships from- tracking:+ example: [email protected]+ first_name: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:+ last_name: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:+ phone: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:+ accepts_email_marketing:+ type: boolean+ internal_note:type: string- enum:- - shipped- description: Pass 'shipped' to register the fulfillment as already- shipped- items:+ tags: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+ type: stringmetadata:type: object- additionalProperties: true- "/api/v3/admin/orders/{order_id}/fulfillments/{id}":+ "/api/v3/admin/customers/{id}":get:- summary: Show a shipment+ summary: Show a customertags:- - Fulfillments+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Returns details of a specific shipment.+ Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).- **Required scope:** `read_fulfillments` (for API-key authentication).+ **Required scope:** `read_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5161,10 +5030,12 @@ paths:secretKey: 'sk_xxx',})- const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ const customer = await client.customers.get('cus_UkLWZg9DAJ', {+ expand: ['addresses', 'store_credits'],+ })- lang: bashlabel: Spree CLI- source: spree api get /orders/{order_id}/fulfillments/{id}+ source: spree api get /customers/{id} -d '{"expand":["addresses","store_credits"]}'parameters:- name: x-spree-api-keyin: header@@ -5174,83 +5045,73 @@ 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 ID+ description: Customer IDschema:type: string- name: expandin: 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: 'Comma-separated associations: addresses, orders, store_credits,+ default_billing_address, default_shipping_address'schema:type: string- name: fieldsin: queryrequired: false- description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).+ description: Comma-separated list of fields to include (e.g., email,first_name,last_name).id is always included.schema:type: stringresponses:'200':- description: shipment found+ description: customer foundcontent:application/json:example:- id: ful_UkLWZg9DAJ- number: H68164259586- tracking: U10000- tracking_url:- 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: ready- fulfillment_type: shipping- fulfilled_at:- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1+ id: cus_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"+ login: [email protected]metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:17.520Z'- updated_at: '2026-07-20T06:57:17.651Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_UkLWZg9DAJ+ last_sign_in_at:+ current_sign_in_at:+ created_at: '2026-07-21T16:18:34.573Z'+ updated_at: '2026-07-21T16:18:34.573Z'+ sign_in_count: 0+ failed_attempts: 0+ last_sign_in_ip:+ current_sign_in_ip:+ tags: []+ 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 shipment+ summary: Update a customertags:- - Fulfillments+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Updates a fulfillment (tracking, delivery rate).+ Updates customer attributes. `tags` replaces the full set.- **Required scope:** `write_fulfillments` (for API-key authentication).+ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5262,12 +5123,13 @@ paths:secretKey: 'sk_xxx',})- const fulfillment = await client.orders.fulfillments.update('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {- tracking: '1Z999AA10123456784',+ const customer = await client.customers.update('cus_UkLWZg9DAJ', {+ first_name: 'Updated',+ tags: ['wholesale', 'vip'],})- lang: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/fulfillments/{id} -d '{"tracking":"1Z999AA10123456784"}'+ source: spree api patch /customers/{id} -d '{"first_name":"Updated","tags":["wholesale","vip"]}'parameters:- name: x-spree-api-keyin: header@@ -5277,83 +5139,82 @@ 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: shipment updated+ description: customer updatedcontent:application/json:example:- id: ful_UkLWZg9DAJ- number: H76137673685- tracking: 1Z999AA10123456784- tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784- 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: ready- fulfillment_type: shipping- fulfilled_at:- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1+ id: cus_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"+ login: [email protected]metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:18.297Z'- updated_at: '2026-07-20T06:57:18.648Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_UkLWZg9DAJ+ last_sign_in_at:+ current_sign_in_at:+ created_at: '2026-07-21T16:18:35.133Z'+ updated_at: '2026-07-21T16:18:35.421Z'+ sign_in_count: 0+ failed_attempts: 0+ last_sign_in_ip:+ current_sign_in_ip:+ tags: []+ 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:- tracking:+ email:type: string- example: 1Z999AA10123456784- description: Carrier tracking number, or a full https:// tracking- link served back as tracking_url unchanged- selected_delivery_rate_id:+ first_name:type: string- description: Delivery rate ID (dr_...) to select- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":- patch:- summary: Fulfill a fulfillment+ 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 customertags:- - Fulfillments+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Marks a fulfillment as fulfilled.+ Deletes a customer. Returns 422 if the customer has any orders.- **Required scope:** `write_fulfillments` (for API-key authentication).+ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5365,11 +5226,10 @@ paths:secretKey: 'sk_xxx',})- const fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ await client.customers.delete('cus_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{- ... }'+ source: spree api delete /customers/{id}parameters:- name: x-spree-api-keyin: header@@ -5379,69 +5239,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: string- name: idin: pathrequired: true- description: Fulfillment IDschema:type: stringresponses:- '200':- description: fulfillment fulfilled- content:- application/json:- example:- id: ful_UkLWZg9DAJ- number: H85626051071- tracking: U10000- tracking_url:- 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: shipped- fulfillment_type: shipping- fulfilled_at: '2026-07-20T06:57:19Z'- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1- metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:18.977Z'- updated_at: '2026-07-20T06:57:19.314Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_UkLWZg9DAJ- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":- patch:- summary: Cancel a fulfillment+ '204':+ description: customer deleted+ "/api/v3/admin/customers/bulk_add_to_groups":+ post:+ summary: Bulk-add customers to groupstags:- - Fulfillments+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Cancels a fulfillment.+ 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_fulfillments` (for API-key authentication).++ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5453,11 +5276,13 @@ paths:secretKey: 'sk_xxx',})- const fulfillment = await client.orders.fulfillments.cancel('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ const result = await client.customers.bulkAddToGroups({+ ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],+ customer_group_ids: ['cg_UkLWZg9DAJ'],+ })- lang: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/fulfillments/{id}/cancel -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@@ -5467,69 +5292,59 @@ 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 canceled+ description: customers added to groupscontent:application/json:example:- id: ful_UkLWZg9DAJ- number: H17425619714- tracking: U10000- tracking_url:- 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: canceled- fulfillment_type: shipping- fulfilled_at:- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1- metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:19.660Z'- updated_at: '2026-07-20T06:57:20.021Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_UkLWZg9DAJ- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":- patch:- summary: Resume a fulfillment+ customer_count: 1+ customer_group_count: 1+ 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 groupstags:- - Fulfillments+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Resumes a canceled fulfillment.+ 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_fulfillments` (for API-key authentication).++ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5541,11 +5356,13 @@ paths:secretKey: 'sk_xxx',})- const fulfillment = await client.orders.fulfillments.resume('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ const result = await client.customers.bulkRemoveFromGroups({+ ids: ['cus_UkLWZg9DAJ'],+ customer_group_ids: ['cg_UkLWZg9DAJ'],+ })- lang: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/fulfillments/{id}/resume -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@@ -5555,69 +5372,58 @@ 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 resumed+ description: customers removed from groupscontent:application/json:example:- id: ful_UkLWZg9DAJ- number: H60358029563- tracking: U10000- tracking_url:- 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: pending- fulfillment_type: shipping- fulfilled_at:- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1- metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:20.367Z'- updated_at: '2026-07-20T06:57:20.719Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_UkLWZg9DAJ- "/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":- patch:- summary: Split a fulfillment+ customer_count: 1+ customer_group_count: 1+ 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 customerstags:- - Fulfillments+ - Customerssecurity:- api_key: []bearer_auth: []description: |-- Transfers items from this shipment to a new shipment at a different stock location.+ 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_fulfillments` (for API-key authentication).++ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5629,12 +5435,13 @@ paths:secretKey: 'sk_xxx',})- const fulfillment = await client.orders.fulfillments.split('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {- quantity: 1,+ const result = await client.customers.bulkAddTags({+ ids: ['cus_UkLWZg9DAJ', 'cus_QrLWXg9CAJ'],+ tags: ['vip', 'newsletter'],})- lang: bashlabel: Spree CLI- source: spree api patch /orders/{order_id}/fulfillments/{id}/split -d '{"quantity":1}'+ source: spree api post /customers/bulk_add_tags -d '{"ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"],"tags":["vip","newsletter"]}'parameters:- name: x-spree-api-keyin: header@@ -5644,92 +5451,59 @@ 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 split+ description: tags addedcontent:application/json:example:- data:- - id: ful_gbHJdmfrXB- number: H42221280801- tracking:- tracking_url:- 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: ready- fulfillment_type: shipping- fulfilled_at:- items:- - item_id: li_UkLWZg9DAJ- variant_id: variant_UkLWZg9DAJ- quantity: 1- metadata: {}- adjustment_total: '0.0'- pre_tax_amount: '0.0'- created_at: '2026-07-20T06:57:21.417Z'- updated_at: '2026-07-20T06:57:21.465Z'- order_id: or_UkLWZg9DAJ- stock_location_id: sloc_gbHJdmfrXB+ customer_count: 1+ tag_count: 2+ schema:+ type: object+ properties:+ customer_count:+ type: integer+ tag_count:+ type: integerrequestBody:content:application/json:schema:type: objectrequired:- - variant_id- - quantity+ - ids+ - tagsproperties:- 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 gift card batches+ 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 customerstags:- - Gift Cards+ - Customerssecurity:- 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`.+ Removes each tag name in `tags` from every customer in `ids`. No-op+ for customers that don't carry the tag.- **Required scope:** `read_gift_cards` (for API-key authentication).+ **Required scope:** `write_customers` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -5741,10 +5515,13 @@ paths:secretKey: 'sk_xxx',})- const { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })+ const result = await client.customers.bulkRemoveTags({+ ids: ['cus_UkLWZg9DAJ'],+ tags: ['vip'],+ })- lang: bashlabel: Spree CLI- source: spree api get /gift_card_batches -d '{"page":1,"limit":25}'+ source: spree api post /customers/bulk_remove_tags -d '{"ids":["cus_UkLWZg9DAJ"],"tags":["vip"]}'parameters:- name: x-spree-api-keyin: header@@ -5754,49 +5531,100 @@ 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: Records per page- schema:- type: integer- - name: q[prefix_cont]- in: query- required: false- description: Filter by prefix (contains)+ responses:+ '200':+ description: tags removed+ content:+ application/json:+ example:+ customer_count: 1+ tag_count: 1+ schema:+ type: object+ properties:+ customer_count:+ type: integer+ tag_count:+ type: integer+ requestBody:+ content:+ application/json:+ schema:+ type: object+ required:+ - ids+ - tags+ properties:+ ids:+ type: array+ items:+ type: string+ example:+ - cus_UkLWZg9DAJ+ tags:+ type: array+ items:+ type: string+ example:+ - vip+ "/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: trueschema:type: string- - name: sort- in: query- required: false- description: Sort by field. Prefix with `-` for descending.+ - name: Authorization+ in: header+ required: trueschema:type: stringresponses:'200':- description: gift card batches found+ description: exports foundcontent:application/json:example:data:- - id: gcb_UkLWZg9DAJ- codes_count: 2- currency: USD- prefix: WELCOME- created_at: '2026-07-20T06:57:00.488Z'- updated_at: '2026-07-20T06:57:00.488Z'- amount: '50.0'- expires_at:- created_by_id:+ - id: exp_UkLWZg9DAJ+ number: EF266677385+ type: Spree::Exports::Products+ format: csv+ created_at: '2026-07-21T16:18:39.564Z'+ updated_at: '2026-07-21T16:18:39.564Z'+ user_id: admin_UkLWZg9DAJ+ done: false+ filename:+ byte_size:+ download_url:meta:page: 1limit: 25@@ -5807,34 +5635,24 @@ paths:in: 1previous:next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/GiftCardBatch"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - metapost:- summary: Create a gift card batch+ summary: Create an exporttags:- - Gift Cards+ - Exportssecurity:- 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.+ 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_gift_cards` (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@@ -5846,16 +5664,13 @@ paths:secretKey: 'sk_xxx',})- const batch = await client.giftCardBatches.create({- prefix: 'WELCOME',- amount: '25.00',- currency: 'USD',- codes_count: 100,- expires_at: '2030-12-31',+ const exp = await client.exports.create({+ type: 'Spree::Exports::Products',+ search_params: { name_cont: 'shirt' }})- lang: bashlabel: 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"}'+ source: spree api post /exports -d '{"type":"Spree::Exports::Products","search_params":{"name_cont":"shirt"}}'parameters:- name: x-spree-api-keyin: header@@ -5869,83 +5684,73 @@ paths:type: stringresponses:'201':- description: gift card batch created- content:- application/json:- example:- id: gcb_gbHJdmfrXB- codes_count: 5- currency: USD- prefix: NEWCAMP- created_at: '2026-07-20T06:57:01.065Z'- updated_at: '2026-07-20T06:57:01.065Z'- amount: '25.0'- expires_at: '2030-12-31'- created_by_id: admin_UkLWZg9DAJ- schema:- "$ref": "#/components/schemas/GiftCardBatch"- '422':- description: validation error+ description: export queuedcontent:application/json:example:- error:- code: validation_error- message: Prefix can't be blank- details:- prefix:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"+ id: exp_gbHJdmfrXB+ number: EF036992406+ type: Spree::Exports::Products+ format: csv+ created_at: '2026-07-21T16:18:39.862Z'+ updated_at: '2026-07-21T16:18:39.862Z'+ user_id: admin_UkLWZg9DAJ+ done: false+ filename:+ byte_size:+ download_url:requestBody:content:application/json:schema:type: objectrequired:- - prefix- - amount- - codes_count+ - typeproperties:- 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: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:+ enum:+ - Spree::Exports::Products+ - Spree::Exports::Orders+ - Spree::Exports::Customers+ - Spree::Exports::ProductTranslations+ - Spree::Exports::GiftCards+ - Spree::Exports::CouponCodes+ - Spree::Exports::NewsletterSubscribers+ example: Spree::Exports::Products+ record_selection: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+ 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 gift card batch+ summary: Show an exporttags:- - Gift Cards+ - Exportssecurity:- api_key: []bearer_auth: []description: |-- Returns a single batch.+ Returns export status. While `done` is `false`, the SPA continues polling.- **Required scope:** `read_gift_cards` (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@@ -5957,10 +5762,10 @@ paths:secretKey: 'sk_xxx',})- const batch = await client.giftCardBatches.get('gcb_K3zr8x')+ const exp = await client.exports.get('exp_xxx')- lang: bashlabel: Spree CLI- source: spree api get /gift_card_batches/{id}+ source: spree api get /exports/{id}parameters:- name: x-spree-api-keyin: header@@ -5972,48 +5777,39 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: gift card batch found- content:- application/json:- example:- id: gcb_UkLWZg9DAJ- codes_count: 2- currency: USD- prefix: WELCOME- created_at: '2026-07-20T06:57:01.365Z'- updated_at: '2026-07-20T06:57:01.365Z'- amount: '50.0'- expires_at:- created_by_id:- schema:- "$ref": "#/components/schemas/GiftCardBatch"- '404':- description: gift card batch not found+ description: export foundcontent: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+ id: exp_UkLWZg9DAJ+ number: EF880393396+ type: Spree::Exports::Products+ format: csv+ created_at: '2026-07-21T16:18:40.138Z'+ updated_at: '2026-07-21T16:18:40.138Z'+ user_id: admin_UkLWZg9DAJ+ done: false+ filename:+ byte_size:+ download_url:+ delete:+ summary: Delete an exporttags:- - Gift Cards+ - Exportssecurity:- 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[state_eq]` for status filtering.-+ Removes the export and purges its attachment.- **Required scope:** `read_gift_cards` (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@@ -6025,14 +5821,10 @@ paths:secretKey: 'sk_xxx',})- const { data: giftCards } = await client.giftCards.list({- page: 1,- limit: 25,- expand: ['customer', 'created_by'],- })+ await client.exports.delete('exp_xxx')- lang: bashlabel: Spree CLI- source: spree api get /gift_cards -d '{"page":1,"limit":25,"expand":["customer","created_by"]}'+ source: spree api delete /exports/{id}parameters:- name: x-spree-api-keyin: header@@ -6042,137 +5834,28 @@ 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[code_cont]- in: query- required: false- description: Filter by gift card code (contains)- schema:- type: string- - name: q[state_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.+ - name: id+ in: path+ required: trueschema:type: stringresponses:- '200':- description: gift cards found- content:- application/json:- example:- data:- - id: gc_UkLWZg9DAJ- code: F33554D1133BC02A- 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-07-20T06:57:01.944Z'- updated_at: '2026-07-20T06:57:01.944Z'- customer_id:- created_by_id:- - id: gc_gbHJdmfrXB- code: AC3796235283FAC6- 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-07-20T06:57:01.946Z'- updated_at: '2026-07-20T06:57:01.946Z'- 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+ '204':+ description: export deleted+ "/api/v3/admin/exports/{id}/download":+ get:+ summary: Download an exporttags:- - Gift Cards+ - Exportssecurity:- 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.-+ 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_gift_cards` (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@@ -6184,15 +5867,21 @@ paths:secretKey: 'sk_xxx',})- const giftCard = await client.giftCards.create({- amount: '25.00',- currency: 'USD',- expires_at: '2030-12-31',- user_id: 'cus_UkLWZg9DAJ',+ // 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 post /gift_cards -d '{"amount":"25.00","currency":"USD","expires_at":"2030-12-31","user_id":"cus_UkLWZg9DAJ"}'+ source: spree api get /exports/{id}/downloadparameters:- name: x-spree-api-keyin: header@@ -6204,96 +5893,32 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:- '201':- description: gift card created+ '200':+ description: CSV filecontent:- application/json:- example:- id: gc_EfhxLZ9ck8- code: 6439979003471DB0- 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-07-20T06:57:02.544Z'- updated_at: '2026-07-20T06:57:02.544Z'- customer_id:- created_by_id: admin_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+ application/json: {}+ text/csv: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+ type: string+ format: binary+ "/api/v3/admin/orders/{order_id}/fulfillments":get:- summary: Get a gift card+ summary: List fulfillmentstags:- - Gift Cards+ - Fulfillmentssecurity:- api_key: []bearer_auth: []description: |-- Returns a single gift card.+ Returns all shipments for an order.- **Required scope:** `read_gift_cards` (for API-key authentication).+ **Required scope:** `read_fulfillments` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -6305,12 +5930,10 @@ paths:secretKey: 'sk_xxx',})- const giftCard = await client.giftCards.get('gc_K3zr8x', {- expand: ['customer', 'created_by', 'orders'],- })+ const { data: fulfillments } = await client.orders.fulfillments.list('or_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api get /gift_cards/{id} -d '{"expand":["customer","created_by","orders"]}'+ source: spree api get /orders/{order_id}/fulfillmentsparameters:- name: x-spree-api-keyin: header@@ -6320,64 +5943,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., 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. id is always included.+ description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).+ id is always included.schema:type: stringresponses:'200':- description: gift card found- content:- application/json:- example:- id: gc_UkLWZg9DAJ- code: 6E1868C9882C69E7- 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-07-20T06:57:02.839Z'- updated_at: '2026-07-20T06:57:02.839Z'- customer_id:- created_by_id:- schema:- "$ref": "#/components/schemas/GiftCard"- '404':- description: gift card not found+ description: fulfillments foundcontent:application/json:example:- error:- code: record_not_found- message: Gift card not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update a gift card+ data:+ - id: ful_UkLWZg9DAJ+ number: H21250078931+ tracking: U10000+ tracking_url:+ 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: ready+ fulfillment_type: shipping+ fulfilled_at:+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:18:57.423Z'+ updated_at: '2026-07-21T16:18:57.508Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_UkLWZg9DAJ+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ post:+ summary: Create a fulfillmenttags:- - Gift Cards+ - Fulfillmentssecurity:- api_key: []bearer_auth: []description: |-- Updates an active gift card's editable attributes. Redeemed or- partially-redeemed cards cannot be edited.-+ 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_gift_cards` (for API-key authentication).+ **Required scope:** `write_fulfillments` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -6389,12 +6036,16 @@ paths:secretKey: 'sk_xxx',})- const giftCard = await client.giftCards.update('gc_K3zr8x', {- amount: '75.00',+ 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 patch /gift_cards/{id} -d '{"amount":"75.00"}'+ 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@@ -6404,65 +6055,127 @@ 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: gift card updated+ '201':+ description: fulfillment createdcontent:application/json:example:- id: gc_UkLWZg9DAJ- code: 81428027501D9E35- 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-07-20T06:57:03.415Z'- updated_at: '2026-07-20T06:57:03.705Z'- customer_id:- created_by_id:- schema:- "$ref": "#/components/schemas/GiftCard"+ id: ful_gbHJdmfrXB+ number: H35335565430+ tracking: INPOST-12345+ tracking_url:+ 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: shipped+ fulfillment_type: shipping+ fulfilled_at: '2026-07-21T16:18:58Z'+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:18:58.534Z'+ updated_at: '2026-07-21T16:18:58.556Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_UkLWZg9DAJ+ '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: object- properties:- amount:+ required:+ - stock_location_id+ properties:+ stock_location_id:type: string- example: '75.00'- expires_at:+ description: Stock location the fulfillment ships from+ tracking:type: string- example: '2031-12-31'- nullable: true- user_id:+ 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- example: cus_UkLWZg9DAJ- nullable: true- delete:- summary: Delete a gift card+ 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: 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: Show a shipmenttags:- - Gift Cards+ - Fulfillmentssecurity:- api_key: []bearer_auth: []description: |-- Deletes an unused gift card. Cards that have been redeemed or- partially redeemed cannot be deleted and return 422.-+ Returns details of a specific shipment.- **Required scope:** `write_gift_cards` (for API-key authentication).+ **Required scope:** `read_fulfillments` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -6474,10 +6187,10 @@ paths:secretKey: 'sk_xxx',})- await client.giftCards.delete('gc_K3zr8x')+ const fulfillment = await client.orders.fulfillments.get('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api delete /gift_cards/{id}+ source: spree api get /orders/{order_id}/fulfillments/{id}parameters:- name: x-spree-api-keyin: header@@ -6487,147 +6200,83 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- 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/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+ - name: order_id+ in: pathrequired: true+ description: Order IDschema:type: string- - name: Authorization- in: header+ - name: id+ in: pathrequired: true+ description: Fulfillment IDschema: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+ - name: expandin: 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).schema:type: string- - name: expand+ - name: fieldsin: queryrequired: false- description: 'Comma-separated associations to embed. Supported: `countries`.'+ description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).+ id is always included.schema:type: stringresponses:'200':- description: markets found+ description: shipment foundcontent:application/json:example:- data:- - id: mkt_UkLWZg9DAJ- name: EU- currency: USD- default_locale: en- tax_inclusive: false- default: false- country_isos:- - DE- supported_locales:- - en- created_at: '2026-07-20T06:57:08.927Z'- updated_at: '2026-07-20T06:57:08.927Z'- 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/Market"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- post:- summary: Create a market+ id: ful_UkLWZg9DAJ+ number: H97384278775+ tracking: U10000+ tracking_url:+ 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: ready+ fulfillment_type: shipping+ fulfilled_at:+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:18:59.962Z'+ updated_at: '2026-07-21T16:19:00.037Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_UkLWZg9DAJ+ patch:+ summary: Update a shipmenttags:- - Markets+ - Fulfillmentssecurity:- api_key: []bearer_auth: []description: |-- Creates a new market for the current store.-- - `country_isos` 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.-+ Updates a fulfillment (tracking, delivery rate).- **Required scope:** `write_settings` (for API-key authentication).+ **Required scope:** `write_fulfillments` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -6639,17 +6288,12 @@ paths: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_isos: ['DE', 'FR', 'IT'],+ const fulfillment = await client.orders.fulfillments.update('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {+ tracking: '1Z999AA10123456784',})- lang: bashlabel: Spree CLI- source: spree api post /markets -d '{"name":"Europe","currency":"EUR","default_locale":"de","supported_locales":["de","en","fr"],"tax_inclusive":true,"country_isos":["DE","FR","IT"]}'+ source: spree api patch /orders/{order_id}/fulfillments/{id} -d '{"tracking":"1Z999AA10123456784"}'parameters:- name: x-spree-api-keyin: header@@ -6659,115 +6303,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: Fulfillment IDschema:type: stringresponses:- '201':- description: market created- content:- application/json:- example:- id: mkt_gbHJdmfrXB- name: France only- currency: EUR- default_locale: fr- tax_inclusive: true- default: false- country_isos:- - FR- supported_locales:- - en- - fr- created_at: '2026-07-20T06:57:09.529Z'- updated_at: '2026-07-20T06:57:09.529Z'- schema:- "$ref": "#/components/schemas/Market"- '422':- description: validation error+ '200':+ description: shipment updatedcontent: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"+ id: ful_UkLWZg9DAJ+ number: H53590241003+ tracking: 1Z999AA10123456784+ tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784+ 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: ready+ fulfillment_type: shipping+ fulfilled_at:+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:19:00.729Z'+ updated_at: '2026-07-21T16:19:01.280Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_UkLWZg9DAJrequestBody:content:application/json:schema:type: objectproperties:- name:- type: string- example: Europe- currency:+ tracking:type: string- example: EUR- description: ISO 4217 currency code.- default_locale:+ example: 1Z999AA10123456784+ description: Carrier tracking number, or a full https:// tracking+ link served back as tracking_url unchanged+ selected_delivery_rate_id: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_isos:- 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_isos- "/api/v3/admin/markets/{id}":- parameters:- - name: id- in: path- required: true- schema:- type: string- get:- summary: Get a market+ description: Delivery rate ID (dr_...) to select+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":+ patch:+ summary: Fulfill a fulfillmenttags:- - Markets+ - Fulfillmentssecurity:- api_key: []bearer_auth: []- description: "**Required scope:** `read_settings` (for API-key authentication)."+ description: |-+ Marks a fulfillment as fulfilled.++ **Required scope:** `write_fulfillments` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -6779,10 +6391,11 @@ paths:secretKey: 'sk_xxx',})- const market = await client.markets.get('market_xxx')+ const fulfillment = await client.orders.fulfillments.fulfill('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api get /markets/{id}+ source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{+ ... }'parameters:- name: x-spree-api-keyin: header@@ -6792,60 +6405,69 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- - name: expand- in: query- required: false+ - 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: market found- content:- application/json:- example:- id: mkt_UkLWZg9DAJ- name: EU- currency: USD- default_locale: en- tax_inclusive: false- default: false- country_isos:- - DE- supported_locales:- - en- created_at: '2026-07-20T06:57:09.861Z'- updated_at: '2026-07-20T06:57:09.861Z'- schema:- "$ref": "#/components/schemas/Market"- '404':- description: market not found+ description: fulfillment fulfilledcontent:application/json:example:- error:- code: record_not_found- message: Market not found- schema:- "$ref": "#/components/schemas/ErrorResponse"+ id: ful_UkLWZg9DAJ+ number: H18570707749+ tracking: U10000+ tracking_url:+ 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: shipped+ fulfillment_type: shipping+ fulfilled_at: '2026-07-21T16:19:02Z'+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:19:01.681Z'+ updated_at: '2026-07-21T16:19:02.040Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_UkLWZg9DAJ+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":patch:- summary: Update a market+ summary: Cancel a fulfillmenttags:- - Markets+ - Fulfillmentssecurity:- api_key: []bearer_auth: []description: |-- Updates an existing market. Pass `country_isos` 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.-+ Cancels a fulfillment.- **Required scope:** `write_settings` (for API-key authentication).+ **Required scope:** `write_fulfillments` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -6857,17 +6479,11 @@ paths:secretKey: 'sk_xxx',})- // `country_isos` 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_isos: ['DE', 'FR'],- })+ const fulfillment = await client.orders.fulfillments.cancel('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')- lang: bashlabel: Spree CLI- source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_isos":["DE","FR"]}'+ source: spree api patch /orders/{order_id}/fulfillments/{id}/cancel -d '{+ ... }'parameters:- name: x-spree-api-keyin: header@@ -6877,81 +6493,157 @@ 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: market updated+ description: fulfillment canceledcontent:application/json:example:- id: mkt_UkLWZg9DAJ- name: European Union- currency: USD- default_locale: en- tax_inclusive: true- default: false- country_isos:- - DE- supported_locales:- - en- created_at: '2026-07-20T06:57:10.541Z'- updated_at: '2026-07-20T06:57:10.864Z'- schema:- "$ref": "#/components/schemas/Market"- '422':- description: validation error+ id: ful_UkLWZg9DAJ+ number: H84639515232+ tracking: U10000+ tracking_url:+ 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: canceled+ fulfillment_type: shipping+ fulfilled_at:+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:19:02.408Z'+ updated_at: '2026-07-21T16:19:02.811Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_UkLWZg9DAJ+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":+ patch:+ summary: Resume a fulfillment+ tags:+ - Fulfillments+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Resumes a canceled 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.resume('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{order_id}/fulfillments/{id}/resume -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 resumedcontent: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- 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_isos:- type: array- items:- type: string- delete:- summary: Delete a market+ id: ful_UkLWZg9DAJ+ number: H96657094908+ tracking: U10000+ tracking_url:+ 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: pending+ fulfillment_type: shipping+ fulfilled_at:+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:19:03.177Z'+ updated_at: '2026-07-21T16:19:03.571Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_UkLWZg9DAJ+ "/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":+ patch:+ summary: Split a fulfillmenttags:- - Markets+ - Fulfillmentssecurity:- 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`.-+ Transfers items from this shipment to a new shipment at a different stock location.- **Required scope:** `write_settings` (for API-key authentication).+ **Required scope:** `write_fulfillments` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -6963,12 +6655,12 @@ paths: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')+ const fulfillment = await client.orders.fulfillments.split('or_UkLWZg9DAJ', 'ful_UkLWZg9DAJ', {+ quantity: 1,+ })- lang: bashlabel: Spree CLI- source: spree api delete /markets/{id}+ source: spree api patch /orders/{order_id}/fulfillments/{id}/split -d '{"quantity":1}'parameters:- name: x-spree-api-keyin: header@@ -6978,31 +6670,92 @@ 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:- '204':- description: market deleted- '422':- description: cannot delete default or last market+ '200':+ description: fulfillment splitcontent:application/json:example:- error:- code: validation_error- message: Market cannot be deleted- "/api/v3/admin/option_types":+ data:+ - id: ful_gbHJdmfrXB+ number: H96732131004+ tracking:+ tracking_url:+ 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: ready+ fulfillment_type: shipping+ fulfilled_at:+ items:+ - item_id: li_UkLWZg9DAJ+ variant_id: variant_UkLWZg9DAJ+ quantity: 1+ metadata: {}+ adjustment_total: '0.0'+ pre_tax_amount: '0.0'+ created_at: '2026-07-21T16:19:04.387Z'+ updated_at: '2026-07-21T16:19:04.450Z'+ order_id: or_UkLWZg9DAJ+ stock_location_id: sloc_gbHJdmfrXB+ 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 option types+ summary: List gift card batchestags:- - Option Types+ - Gift Cardssecurity:- api_key: []bearer_auth: []description: |-- Returns a paginated list of option types.+ 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@@ -7014,10 +6767,10 @@ paths:secretKey: 'sk_xxx',})- const { data: optionTypes } = await client.optionTypes.list()+ const { data: batches } = await client.giftCardBatches.list({ page: 1, limit: 25 })- lang: bashlabel: Spree CLI- source: spree api get /option_types+ source: spree api get /gift_card_batches -d '{"page":1,"limit":25}'parameters:- name: x-spree-api-keyin: header@@ -7039,45 +6792,37 @@ paths:- name: limitin: queryrequired: false- description: Number of records per page+ description: Records per pageschema:type: integer- - name: q[name_cont]+ - name: q[prefix_cont]in: queryrequired: 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).+ description: Filter by prefix (contains)schema:type: string- - name: fields+ - name: sortin: queryrequired: false- description: Comma-separated list of fields to include (e.g., name,label,position).- id is always included.+ description: Sort by field. Prefix with `-` for descending.schema:type: stringresponses:'200':- description: option types found+ description: gift card batches foundcontent:application/json:example:data:- - id: opt_UkLWZg9DAJ- name: foo-size-1- label: Size- position: 1- kind: dropdown- metadata: {}- filterable: true- created_at: '2026-07-20T06:57:12.439Z'- updated_at: '2026-07-20T06:57:12.439Z'+ - id: gcb_UkLWZg9DAJ+ codes_count: 2+ currency: USD+ prefix: WELCOME+ created_at: '2026-07-21T16:18:40.751Z'+ updated_at: '2026-07-21T16:18:40.751Z'+ amount: '50.0'+ expires_at:+ created_by_id:meta:page: 1limit: 25@@ -7094,36 +6839,28 @@ paths:data:type: arrayitems:- "$ref": "#/components/schemas/OptionType"+ "$ref": "#/components/schemas/GiftCardBatch"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 option type+ summary: Create a gift card batchtags:- - Option Types+ - Gift Cardssecurity:- 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.+ 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@@ -7135,17 +6872,16 @@ paths:secretKey: 'sk_xxx',})- const optionType = await client.optionTypes.create({- name: 'color',- label: 'Color',- option_values: [- { name: 'red', label: 'Red' },- { name: 'navy', label: 'Navy' },- ],+ 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 /option_types -d '{"name":"color","label":"Color","option_values":[{"name":"red","label":"Red"},{"name":"navy","label":"Navy"}]}'+ 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@@ -7155,26 +6891,25 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: stringresponses:'201':- description: option type created+ description: gift card batch createdcontent:application/json:example:- id: opt_gbHJdmfrXB- name: material- label: Material- position: 2- kind: dropdown- metadata: {}- filterable: true- created_at: '2026-07-20T06:57:13.040Z'- updated_at: '2026-07-20T06:57:13.040Z'+ id: gcb_gbHJdmfrXB+ codes_count: 5+ currency: USD+ prefix: NEWCAMP+ created_at: '2026-07-21T16:18:41.323Z'+ updated_at: '2026-07-21T16:18:41.323Z'+ amount: '25.0'+ expires_at: '2030-12-31'+ created_by_id: admin_UkLWZg9DAJschema:- "$ref": "#/components/schemas/OptionType"+ "$ref": "#/components/schemas/GiftCardBatch"'422':description: validation errorcontent:@@ -7182,11 +6917,9 @@ paths:example:error:code: validation_error- message: Name can't be blank and Presentation can't be blank+ message: Prefix can't be blankdetails:- name:- - can't be blank- presentation:+ prefix:- can't be blankschema:"$ref": "#/components/schemas/ErrorResponse"@@ -7195,47 +6928,50 @@ paths:application/json:schema:type: object+ required:+ - prefix+ - amount+ - codes_countproperties:- name:+ prefix:type: string- example: color- label:+ example: WELCOME+ description: Lowercased and prepended to every generated code.+ amount:type: string- example: Color- position:+ 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: 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}":+ 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: Get an option type+ summary: Get a gift card batchtags:- - Option Types+ - Gift Cardssecurity:- api_key: []bearer_auth: []description: |-- Returns a single option type by ID, including its option values.+ Returns a single batch.- **Required scope:** `read_products` (for API-key authentication).+ **Required scope:** `read_gift_cards` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -7247,10 +6983,10 @@ paths:secretKey: 'sk_xxx',})- const optionType = await client.optionTypes.get('ot_UkLWZg9DAJ')+ const batch = await client.giftCardBatches.get('gcb_K3zr8x')- lang: bashlabel: Spree CLI- source: spree api get /option_types/{id}+ source: spree api get /gift_card_batches/{id}parameters:- name: x-spree-api-keyin: header@@ -7260,67 +6996,50 @@ paths:- name: Authorizationin: headerrequired: 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: stringresponses:'200':- description: option type found+ description: gift card batch foundcontent:application/json:example:- id: opt_UkLWZg9DAJ- name: foo-size-5- label: Size- position: 1- kind: dropdown- metadata: {}- filterable: true- created_at: '2026-07-20T06:57:13.339Z'- updated_at: '2026-07-20T06:57:13.339Z'+ id: gcb_UkLWZg9DAJ+ codes_count: 2+ currency: USD+ prefix: WELCOME+ created_at: '2026-07-21T16:18:41.617Z'+ updated_at: '2026-07-21T16:18:41.617Z'+ amount: '50.0'+ expires_at:+ created_by_id:schema:- "$ref": "#/components/schemas/OptionType"+ "$ref": "#/components/schemas/GiftCardBatch"'404':- description: option type not found+ description: gift card batch not foundcontent:application/json:example:error:code: record_not_found- message: Option type not found+ message: Gift card batch not foundschema:"$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update an option type+ "/api/v3/admin/gift_cards":+ get:+ summary: List gift cardstags:- - Option Types+ - Gift Cardssecurity:- api_key: []bearer_auth: []description: |-- Updates an option type. Supports updating nested option values.+ 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[state_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@@ -7332,13 +7051,14 @@ paths:secretKey: 'sk_xxx',})- const optionType = await client.optionTypes.update('ot_UkLWZg9DAJ', {- label: 'Updated Label',- option_values: [{ name: 'red', label: 'Crimson' }],+ const { data: giftCards } = await client.giftCards.list({+ page: 1,+ limit: 25,+ expand: ['customer', 'created_by'],})- lang: bashlabel: Spree CLI- source: spree api patch /option_types/{id} -d '{"label":"Updated Label","option_values":[{"name":"red","label":"Crimson"}]}'+ source: spree api get /gift_cards -d '{"page":1,"limit":25,"expand":["customer","created_by"]}'parameters:- name: x-spree-api-keyin: header@@ -7351,87 +7071,134 @@ paths:description: Bearer token for admin authenticationschema:type: string- - name: id- in: path- required: true- description: Option type 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[code_cont]+ in: query+ required: false+ description: Filter by gift card code (contains)schema:type: string- responses:- '200':- description: option type updated- content:- application/json:- example:- id: opt_UkLWZg9DAJ- name: foo-size-7- label: Updated Label- position: 1- kind: dropdown- metadata: {}- filterable: true- created_at: '2026-07-20T06:57:13.927Z'- updated_at: '2026-07-20T06:57:14.209Z'+ - name: q[state_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: B488359A91D76C3A+ 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-07-21T16:18:42.199Z'+ updated_at: '2026-07-21T16:18:42.199Z'+ customer_id:+ created_by_id:+ - id: gc_gbHJdmfrXB+ code: 05ACFCA2D4BB6555+ 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-07-21T16:18:42.200Z'+ updated_at: '2026-07-21T16:18:42.200Z'+ customer_id:+ created_by_id:+ meta:+ page: 1+ limit: 25+ count: 2+ pages: 1+ from: 1+ to: 2+ in: 2+ previous:+ next:schema:- "$ref": "#/components/schemas/OptionType"- '422':- description: validation error+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/GiftCard"+ meta:+ "$ref": "#/components/schemas/PaginationMeta"+ required:+ - data+ - meta+ '401':+ description: unauthorizedcontent:application/json:example:error:- code: validation_error- message: Presentation can't be blank- details:- presentation:- - can't be blank+ code: authentication_required+ message: Authentication requiredschema:"$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+ post:+ summary: Create a gift cardtags:- - Option Types+ - Gift Cardssecurity:- api_key: []bearer_auth: []description: |-- Deletes an option type.+ 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_products` (for API-key authentication).++ **Required scope:** `write_gift_cards` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -7443,10 +7210,15 @@ paths:secretKey: 'sk_xxx',})- await client.optionTypes.delete('ot_UkLWZg9DAJ')+ 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 /option_types/{id}+ 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@@ -7456,30 +7228,98 @@ 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:- '204':- description: option type deleted- "/api/v3/admin/orders/{order_id}/gift_cards":- post:- summary: Apply a gift card to an order+ '201':+ description: gift card created+ content:+ application/json:+ example:+ id: gc_EfhxLZ9ck8+ code: A140E23184A16AA6+ 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-07-21T16:18:42.788Z'+ updated_at: '2026-07-21T16:18:42.788Z'+ customer_id:+ created_by_id: admin_UkLWZg9DAJ+ schema:+ "$ref": "#/components/schemas/GiftCard"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Amount must be greater than 0+ details:+ amount:+ - must be greater than 0+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ required:+ - amount+ properties:+ amount:+ type: string+ example: '25.00'+ description: Decimal amount, greater than zero.+ currency:+ type: string+ example: USD+ description: ISO 4217 currency code. Defaults to the store currency.+ code:+ type: string+ example: WELCOME50+ description: Optional caller-supplied code. Auto-generated when+ omitted.+ expires_at:+ type: string+ example: '2030-12-31'+ description: ISO 8601 date.+ nullable: true+ user_id:+ type: string+ example: cus_UkLWZg9DAJ+ description: Optional customer prefixed ID.+ nullable: true+ "/api/v3/admin/gift_cards/{id}":+ parameters:+ - name: id+ in: path+ required: true+ description: Gift card prefixed ID+ schema:+ type: string+ get:+ summary: Get a gift cardtags:- - Orders+ - Gift Cardssecurity:- api_key: []bearer_auth: []description: |-- Applies a gift card by code to the order. Returns the gift card.+ Returns a single gift card.- **Required scope:** `write_gift_cards` (for API-key authentication).+ **Required scope:** `read_gift_cards` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -7491,12 +7331,12 @@ paths:secretKey: 'sk_xxx',})- await client.orders.giftCards.apply('or_UkLWZg9DAJ', {- code: 'GIFT-XXXX-YYYY',+ const giftCard = await client.giftCards.get('gc_K3zr8x', {+ expand: ['customer', 'created_by', 'orders'],})- lang: bashlabel: Spree CLI- source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'+ source: spree api get /gift_cards/{id} -d '{"expand":["customer","created_by","orders"]}'parameters:- name: x-spree-api-keyin: header@@ -7506,62 +7346,62 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- - name: order_id- in: path- required: true- description: Order ID+ - name: fields+ in: query+ required: false+ description: Comma-separated list of fields to include. id is always included.schema:type: stringresponses:- '201':- description: gift card applied+ '200':+ description: gift card foundcontent:application/json:example:id: gc_UkLWZg9DAJ- code: 849A0FE4531E1949+ code: 061A199E7FEA86EAstatus: activecurrency: USD- amount: '10.0'- amount_used: '10.0'+ amount: '50.0'+ amount_used: '0.0'amount_authorized: '0.0'- amount_remaining: '0.0'- display_amount: "$10.00"- display_amount_used: "$10.00"- display_amount_remaining: "$0.00"+ amount_remaining: '50.0'+ display_amount: "$50.00"+ display_amount_used: "$0.00"+ display_amount_remaining: "$50.00"expires_at:redeemed_at:expired: falseactive: true- created_at: '2026-07-20T06:57:21.814Z'- updated_at: '2026-07-20T06:57:22.113Z'+ created_at: '2026-07-21T16:18:43.100Z'+ updated_at: '2026-07-21T16:18:43.100Z'customer_id:created_by_id:- requestBody:- content:- application/json:- schema:- type: object- required:- - code- properties:- code:- type: string- description: Gift card code- example: GIFT-XXXX-YYYY- "/api/v3/admin/orders/{order_id}/gift_cards/{id}":- delete:- summary: Remove a gift card from an order+ schema:+ "$ref": "#/components/schemas/GiftCard"+ '404':+ description: gift card not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Gift card not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a gift cardtags:- - Orders+ - Gift Cardssecurity:- api_key: []bearer_auth: []description: |-- Removes the gift card from the order.+ 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:@@ -7575,10 +7415,12 @@ paths:secretKey: 'sk_xxx',})- await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')+ const giftCard = await client.giftCards.update('gc_K3zr8x', {+ amount: '75.00',+ })- lang: bashlabel: Spree CLI- source: spree api delete /orders/{order_id}/gift_cards/{id}+ source: spree api patch /gift_cards/{id} -d '{"amount":"75.00"}'parameters:- name: x-spree-api-keyin: header@@ -7588,36 +7430,65 @@ 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: Gift card IDschema:type: stringresponses:- '204':- description: gift card removed- "/api/v3/admin/orders/{order_id}/items":- get:- summary: List order items+ '200':+ description: gift card updated+ content:+ application/json:+ example:+ id: gc_UkLWZg9DAJ+ code: 492F7742A8EF1266+ 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-07-21T16:18:43.679Z'+ updated_at: '2026-07-21T16:18:43.968Z'+ customer_id:+ created_by_id:+ 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 cardtags:- - Orders+ - Gift Cardssecurity:- api_key: []bearer_auth: []description: |-- Returns all line items for an order.+ Deletes an unused gift card. Cards that have been redeemed or+ partially redeemed cannot be deleted and return 422.- **Required scope:** `read_orders` (for API-key authentication).++ **Required scope:** `write_gift_cards` (for API-key authentication).x-codeSamples:- lang: javascriptlabel: Spree Admin SDK@@ -7629,10 +7500,10 @@ paths:secretKey: 'sk_xxx',})- const { data: items } = await client.orders.items.list('or_UkLWZg9DAJ')+ await client.giftCards.delete('gc_K3zr8x')- lang: bashlabel: Spree CLI- source: spree api get /orders/{order_id}/items+ source: spree api delete /gift_cards/{id}parameters:- name: x-spree-api-keyin: header@@ -7642,122 +7513,31 @@ 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: items found+ '204':+ description: gift card deleted+ '422':+ description: redeemed gift card cannot be deletedcontent:application/json:example:- data:- - id: li_UkLWZg9DAJ- variant_id: variant_gbHJdmfrXB- preorder: false- preorder_ships_at:- quantity: 2- currency: USD- name: Product 171777- slug: product-171777- 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-1- label: S- position: 1- color_code:- option_type_name: foo-size-10- option_type_label: Size- image_url:- metadata: {}- created_at: '2026-07-20T06:57:22.812Z'- updated_at: '2026-07-20T06:57:22.812Z'- digital_links: []- metadata: {}- created_at: '2026-07-20T06:57:23.101Z'- updated_at: '2026-07-20T06:57:23.101Z'- 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+ error:+ code: validation_error+ message: Gift card cannot be deleted+ "/api/v3/admin/imports":+ get:+ summary: List importstags:- - Orders+ - Importssecurity:- api_key: []bearer_auth: []description: |-- Adds a new line item to the order.-- **Required scope:** `write_orders` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })+ Returns CSV imports queued or completed for the current store.- const item = await client.orders.items.create('or_UkLWZg9DAJ', {- variant_id: 'variant_k5nR8xLq',- quantity: 2,- })- - lang: bash- label: Spree CLI- source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'+ **Required scope:** 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@@ -7767,109 +7547,177 @@ 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: item added- content:+ '200':+ description: imports found+ content:application/json:example:- id: li_gbHJdmfrXB- variant_id: variant_VqXmZF31wY- preorder: false- preorder_ships_at:- quantity: 3- currency: USD- name: Product 195196- slug: product-195196- 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-3- label: S- position: 1- color_code:- option_type_name: foo-size-12- option_type_label: Size- image_url:- metadata: {}- created_at: '2026-07-20T06:57:24.022Z'- updated_at: '2026-07-20T06:57:24.022Z'- digital_links: []- metadata: {}- created_at: '2026-07-20T06:57:24.054Z'- updated_at: '2026-07-20T06:57:24.054Z'- 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: Show an item+ data:+ - id: imp_UkLWZg9DAJ+ number: IM447505410+ type: Spree::Imports::Products+ rows_count: 0+ created_at: '2026-07-21T16:18:44.840Z'+ updated_at: '2026-07-21T16:18:44.847Z'+ status: pending+ owner_type: Spree::Store+ owner_id: store_UkLWZg9DAJ+ user_id: admin_UkLWZg9DAJ+ processing_errors:+ preferred_delimiter: ","+ original_filename: products_import.csv+ original_byte_size: 3612+ 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: shipping_category+ label: Shipping Category+ 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:- - Orders+ - Importssecurity:- api_key: []bearer_auth: []description: |-- Returns details of a specific line item.+ 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:** `read_orders` (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 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:** 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@@ -7879,11856 +7727,360 @@ 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: 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:- example:- id: li_UkLWZg9DAJ- variant_id: variant_gbHJdmfrXB- preorder: false- preorder_ships_at:- quantity: 2- currency: USD- name: Product 201972- slug: product-201972- 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-4- label: S- position: 1- color_code:- option_type_name: foo-size-13- option_type_label: Size- image_url:- metadata: {}- created_at: '2026-07-20T06:57:24.135Z'- updated_at: '2026-07-20T06:57:24.135Z'- digital_links: []- metadata: {}- created_at: '2026-07-20T06:57:24.424Z'- updated_at: '2026-07-20T06:57:24.424Z'- cost_price: '17.0'- tax_category_id: taxcat_UkLWZg9DAJ- patch:- summary: Update an item- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Updates an order item quantity or metadata.-- **Required scope:** `write_orders` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- 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}'- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: 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:- example:- id: li_UkLWZg9DAJ- variant_id: variant_gbHJdmfrXB- preorder: false- preorder_ships_at:- quantity: 5- currency: USD- name: Product 214133- slug: product-214133- 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-5- label: S- position: 1- color_code:- option_type_name: foo-size-14- option_type_label: Size- image_url:- metadata: {}- created_at: '2026-07-20T06:57:24.756Z'- updated_at: '2026-07-20T06:57:24.756Z'- digital_links: []- metadata: {}- created_at: '2026-07-20T06:57:25.041Z'- updated_at: '2026-07-20T06:57:25.343Z'- cost_price: '17.0'- tax_category_id: taxcat_UkLWZg9DAJ- requestBody:- content:- application/json:- schema:- type: object- properties:- quantity:- type: integer- delete:- summary: Remove an item- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Removes an item from the order.-- **Required scope:** `write_orders` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api delete /orders/{order_id}/items/{id}- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order ID- schema:- type: string- - name: id- in: path- required: true- description: Item ID- schema:- type: string- responses:- '204':- description: line item removed- "/api/v3/admin/orders/{order_id}/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.-- **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 order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {- amount: '25.00',- })- - lang: bash- label: Spree CLI- source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: 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+ description: import created in mapping statecontent:application/json:example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R642369123- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 1- 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"- store_credit_total: '50.0'- display_store_credit_total: "-$50.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at:- approved_at:- created_at: '2026-07-20T06:57:32.179Z'- updated_at: '2026-07-20T06:57:32.233Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id:- created_by_id:- customer_id: cus_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- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Removes any applied store credit from the order.-- **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.orders.storeCredits.remove('or_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api delete /orders/{order_id}/store_credits- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- 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.-- **Required scope:** `read_orders` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const { data: orders, meta } = await client.orders.list({- status_eq: 'complete',- completed_at_gt: '2026-01-01',- sort: '-completed_at',- limit: 25,- })- - lang: bash- label: Spree CLI- source: spree api get /orders -d '{"status_eq":"complete","completed_at_gt":"2026-01-01","sort":"-completed_at","limit":25}'- parameters:- - name: x-spree-api-key- in: header- 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:- example:- data:- - id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R382326538- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 0- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at:- approved_at:- created_at: '2026-07-20T06:57:34.073Z'- updated_at: '2026-07-20T06:57:34.073Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id:- created_by_id:- customer_id: cus_UkLWZg9DAJ- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- '401':- description: unauthorized- content:- application/json:- example:- error:- code: authentication_required- message: Authentication required- schema:- "$ref": "#/components/schemas/ErrorResponse"- post:- summary: Create a draft order- tags:- - Orders- security:- - api_key: []- bearer_auth: []- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- 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.',- internal_note: 'VIP customer — handle with care.',- 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_iso: 'US',- state_abbr: '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_iso: 'US',- state_abbr: 'NY',- phone: '+1 212 555 1234',- },- // billing_address_id: 'addr_UkLWZg9DAJ',-- // Optional. Invalid codes are non-fatal — the order is created either way.- coupon_code: 'WELCOME10',- })- - lang: bash- label: Spree CLI- source: spree api post /orders -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":"VIP customer — handle with care.","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_iso":"US","state_abbr":"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_iso":"US","state_abbr":"NY","phone":"+1- 212 555 1234"},"coupon_code":"WELCOME10"}'- description: |-- Creates a new draft order in one shot. Customer, items, addresses, currency,- market, channel, locale, notes, metadata, and a coupon code can all be- provided inline.-- Setting `preferred_stock_location_id` pins the order's preferred fulfillment- location — Order Routing's built-in `PreferredLocation` rule consumes it- when picking which stock location ships each shipment.-- Invalid coupon codes are non-fatal — the order is created and the failure- is reported on the service result (not in the API response body for now).--- **Required scope:** `write_orders` (for API-key authentication).- parameters:- - name: x-spree-api-key- in: header- 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:- example:- id: or_gbHJdmfrXB- market_id:- channel_id: ch_UkLWZg9DAJ- number: R877501109- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 0- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at:- approved_at:- created_at: '2026-07-20T06:57:35.866Z'- updated_at: '2026-07-20T06:57:35.871Z'- preferred_stock_location_id: sloc_UkLWZg9DAJ- tags: []- internal_note:- approver_id:- canceler_id:- created_by_id:- 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_iso:- type: string- state_abbr:- 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_iso:- type: string- state_abbr:- type: string- phone:- type: string- billing_address_id:- type: string- description: Existing customer address ID- items:- type: array- items:- type: object- required:- - variant_id- - quantity- properties:- variant_id:- type: string- description: Variant ID- quantity:- type: integer- example: 1- metadata:- type: object- coupon_code:- type: string- description: Optional. Applied non-fatally; invalid codes do not- block creation.- "/api/v3/admin/orders/{id}":- get:- summary: Show an order- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Returns full order details including admin-only fields.-- **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 order = await client.orders.get('or_UkLWZg9DAJ', {- expand: ['items', 'fulfillments', 'payments', 'customer'],- })- - lang: bash- label: Spree CLI- source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'- parameters:- - name: x-spree-api-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:- example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R510884213- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 0- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at:- approved_at:- created_at: '2026-07-20T06:57:36.163Z'- updated_at: '2026-07-20T06:57:36.163Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id:- created_by_id:- customer_id: cus_UkLWZg9DAJ- '404':- description: order not found- content:- application/json:- example:- error:- code: order_not_found- message: Order not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update an order- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Updates an order. Supports updating email, addresses, special instructions, and line items.-- **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 order = await client.orders.update('or_UkLWZg9DAJ', {- email: '[email protected]',- internal_note: 'VIP — gift wrap on next order',- })- - lang: bash- label: Spree CLI- source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"VIP- — gift wrap on next order"}'- parameters:- - name: x-spree-api-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:- example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R354680381- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 0- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at:- approved_at:- created_at: '2026-07-20T06:57:37.335Z'- updated_at: '2026-07-20T06:57:37.649Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id:- created_by_id:- customer_id: cus_UkLWZg9DAJ- requestBody:- content:- application/json:- schema:- type: object- properties:- email:- type: string- special_instructions:- 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.- ship_address:- type: object- properties:- firstname:- type: string- lastname:- type: string- address1:- type: string- city:- type: string- zipcode:- type: string- country_iso:- type: string- state_abbr:- type: string- phone:- type: string- bill_address:- type: object- properties:- firstname:- type: string- lastname:- type: string- address1:- type: string- city:- type: string- zipcode:- type: string- country_iso:- type: string- state_abbr:- type: string- phone:- type: string- items:- type: array- items:- type: object- required:- - variant_id- properties:- variant_id:- type: string- description: Variant ID- quantity:- type: integer- example: 1- metadata:- type: object- delete:- summary: Delete a draft order- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Deletes a draft order. Completed orders cannot be deleted.-- **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.delete('or_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api delete /orders/{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: 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.-- Set `notify_customer: true` to send the order confirmation email.--- **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 order = await client.orders.complete('or_UkLWZg9DAJ', {- notify_customer: true,- })- - lang: bash- label: Spree CLI- source: spree api patch /orders/{id}/complete -d '{"notify_customer":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: id- in: path- required: true- description: Order ID- schema:- type: string- responses:- '200':- description: order completed- content:- application/json:- example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R406055252- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 1- fulfillment_status: ready- payment_status: paid- completed_at: '2026-07-20T06:57:38.664Z'- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- status: draft- last_ip_address:- considered_risky: false- confirmation_delivered: false- store_owner_notification_delivered:- payment_total: '110.0'- display_payment_total: "$110.00"- metadata: {}- canceled_at:- approved_at:- created_at: '2026-07-20T06:57:38.610Z'- updated_at: '2026-07-20T06:57:38.686Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id:- created_by_id:- customer_id: cus_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- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Cancels a completed order.-- **Required scope:** `write_orders` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const order = await client.orders.cancel('or_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api patch /orders/{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: id- in: path- required: true- description: Order ID- schema:- type: string- responses:- '200':- description: order canceled- content:- application/json:- example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R371015890- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 1- fulfillment_status: canceled- payment_status: void- completed_at: '2026-07-20T06:57:40.599Z'- 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: "-0.0"- display_amount_due: "$0.00"- delivery_total: '10.0'- display_delivery_total: "$10.00"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at: '2026-07-20T06:57:40.892Z'- approved_at:- created_at: '2026-07-20T06:57:40.541Z'- updated_at: '2026-07-20T06:57:40.932Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id: admin_UkLWZg9DAJ- created_by_id:- customer_id: cus_UkLWZg9DAJ- "/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).-- **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 order = await client.orders.approve('or_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api patch /orders/{id}/approve -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: id- in: path- required: true- description: Order ID- schema:- type: string- responses:- '200':- description: order approved- content:- application/json:- example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R229408920- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 1- fulfillment_status:- payment_status:- completed_at: '2026-07-20T06:57:41.295Z'- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at:- approved_at: '2026-07-20T06:57:41.587Z'- created_at: '2026-07-20T06:57:41.240Z'- updated_at: '2026-07-20T06:57:41.295Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id: admin_UkLWZg9DAJ- canceler_id:- created_by_id:- customer_id: cus_UkLWZg9DAJ- "/api/v3/admin/orders/{id}/resume":- patch:- summary: Resume a canceled order- tags:- - Orders- security:- - api_key: []- bearer_auth: []- description: |-- Resumes a previously canceled order.-- **Required scope:** `write_orders` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const order = await client.orders.resume('or_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api patch /orders/{id}/resume -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: id- in: path- required: true- description: Order ID- schema:- type: string- responses:- '200':- description: order resumed- content:- application/json:- example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R804768369- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 1- fulfillment_status: canceled- payment_status: void- completed_at: '2026-07-20T06:57:41.953Z'- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at: '2026-07-20T06:57:42.275Z'- approved_at:- created_at: '2026-07-20T06:57:41.870Z'- updated_at: '2026-07-20T06:57:42.400Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id: admin_UkLWZg9DAJ- created_by_id:- customer_id: cus_UkLWZg9DAJ- "/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.-- **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.resendConfirmation('or_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api post /orders/{id}/resend_confirmation -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: id- in: path- required: true- description: Order ID- schema:- type: string- responses:- '200':- description: confirmation resent- content:- application/json:- example:- id: or_UkLWZg9DAJ- market_id:- channel_id: ch_UkLWZg9DAJ- number: R312692651- email: [email protected]- customer_note:- currency: USD- locale: en- total_quantity: 1- fulfillment_status:- payment_status:- completed_at: '2026-07-20T06:57:42.735Z'- 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"- store_credit_total: '0.0'- display_store_credit_total: "$0.00"- covered_by_store_credit: false- gift_card:- market:- 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: {}- canceled_at:- approved_at:- created_at: '2026-07-20T06:57:42.684Z'- updated_at: '2026-07-20T06:57:42.734Z'- preferred_stock_location_id:- tags: []- internal_note:- approver_id:- canceler_id:- created_by_id:- customer_id: cus_UkLWZg9DAJ- "/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.-- **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: paymentMethods } = await client.paymentMethods.list()- - lang: bash- label: Spree CLI- source: spree api get /payment_methods- 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:- example:- data:- - id: pm_UkLWZg9DAJ- name: Check- description:- type: check- session_required: false- source_required: false- metadata: {}- active: true- auto_capture:- storefront_visible: true- position: 1- created_at: '2026-07-20T06:57:44.197Z'- updated_at: '2026-07-20T06:57:44.197Z'- 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- 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.-- **Required scope:** `read_settings` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const { data: types } = await client.paymentMethods.types()- - lang: bash- label: Spree CLI- source: spree api get /payment_methods/types- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- schema:- type: string- responses:- '200':- description: provider types found- content:- application/json:- example:- data:- - type: bogus- label: Bogus- description:- preference_schema:- - key: dummy_secret_key- type: password- default:- - key: dummy_key- type: string- default: PUBLICKEY123- - type: custom_payment_source_method- label: Custom Payment Source Method- description:- preference_schema: []- "/api/v3/admin/payment_methods/{id}":- get:- summary: Show a payment method- tags:- - Payment Methods- security:- - api_key: []- bearer_auth: []- description: |-- Returns a payment method by ID.-- **Required scope:** `read_settings` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api get /payment_methods/{id}- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- schema:- type: string- - name: id- in: path- required: true- schema:- type: string- - name: expand- in: query- required: false- description: Comma-separated associations to expand. Use dot notation for- nested expand (max 4 levels).- schema:- type: string- - name: fields- in: query- required: false- description: Comma-separated list of fields to include (e.g., name,type,active).- id is always included.- schema:- type: string- responses:- '200':- description: payment method found- content:- application/json:- example:- id: pm_UkLWZg9DAJ- name: Check- description:- type: check- session_required: false- source_required: false- metadata: {}- active: true- auto_capture:- storefront_visible: true- position: 1- created_at: '2026-07-20T06:57:44.792Z'- updated_at: '2026-07-20T06:57:44.792Z'- preferences: {}- preference_schema: []- "/api/v3/admin/orders/{order_id}/payments":- get:- summary: List payments- tags:- - Payments- security:- - api_key: []- bearer_auth: []- description: |-- Returns all payments for an order.-- **Required scope:** `read_payments` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api get /orders/{order_id}/payments- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- description: Bearer token for admin authentication- schema:- type: string- - name: order_id- in: path- required: true- description: Order ID- schema:- type: string- - name: expand- in: query- required: false- description: Comma-separated associations to expand (e.g., payment_method,- source). Use dot notation for nested expand (max 4 levels).- 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:- example:- data:- - id: py_UkLWZg9DAJ- payment_method_id: pm_UkLWZg9DAJ- response_code: BGS-609243242af9- number: P7S338OR- amount: '110.0'- display_amount: "$110.00"- status: completed- 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-07-20T06:57:26.392Z'- updated_at: '2026-07-20T06:57:26.395Z'- metadata: {}- avs_response:- cvv_response_code:- cvv_response_message:- created_at: '2026-07-20T06:57:26.394Z'- updated_at: '2026-07-20T06:57:26.394Z'- captured_amount: '0.0'- order_id: or_UkLWZg9DAJ- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- post:- summary: Create a payment- tags:- - Payments- security:- - api_key: []- bearer_auth: []- description: |-- Creates a new payment for the order.-- **Required scope:** `write_payments` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- 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"}'- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- 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:- example:- id: py_gbHJdmfrXB- payment_method_id: pm_EfhxLZ9ck8- response_code:- number: PXB9L8R3- amount: '110.0'- display_amount: "$110.00"- status: checkout- source_type:- source_id:- source:- metadata: {}- avs_response:- cvv_response_code:- cvv_response_message:- created_at: '2026-07-20T06:57:27.755Z'- updated_at: '2026-07-20T06:57:27.755Z'- captured_amount: '0.0'- order_id: or_gbHJdmfrXB- requestBody:- content:- application/json:- schema:- type: object- required:- - payment_method_id- properties:- payment_method_id:- type: string- description: Payment method ID- amount:- type: string- example: '99.99'- source_id:- type: string- description: Payment source ID- "/api/v3/admin/orders/{order_id}/payments/{id}":- get:- summary: Show a payment- tags:- - Payments- security:- - api_key: []- bearer_auth: []- description: |-- Returns details of a specific payment.-- **Required scope:** `read_payments` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- 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}- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: 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:- example:- id: py_UkLWZg9DAJ- payment_method_id: pm_UkLWZg9DAJ- response_code: BGS-43426241a9a2- number: P718Q4OZ- amount: '110.0'- display_amount: "$110.00"- status: completed- 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-07-20T06:57:28.125Z'- updated_at: '2026-07-20T06:57:28.128Z'- metadata: {}- avs_response:- cvv_response_code:- cvv_response_message:- created_at: '2026-07-20T06:57:28.127Z'- updated_at: '2026-07-20T06:57:28.127Z'- captured_amount: '0.0'- order_id: or_UkLWZg9DAJ- "/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.-- **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',- })-- const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api patch /orders/{order_id}/payments/{id}/capture -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: Payment ID- schema:- type: string- responses:- '200':- description: payment captured- content:- application/json:- example:- id: py_UkLWZg9DAJ- payment_method_id: pm_UkLWZg9DAJ- response_code: BGS-c4a12477e98a- number: PVIADWHT- amount: '110.0'- display_amount: "$110.00"- status: completed- 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-07-20T06:57:28.788Z'- updated_at: '2026-07-20T06:57:28.791Z'- metadata: {}- avs_response:- cvv_response_code:- cvv_response_message:- created_at: '2026-07-20T06:57:28.790Z'- updated_at: '2026-07-20T06:57:29.142Z'- captured_amount: '110.0'- order_id: or_UkLWZg9DAJ- '422':- description: capture failed- content:- application/json:- example:- error:- code: processing_error- message: 'Bogus Gateway: Forced failure'- schema:- "$ref": "#/components/schemas/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.-- **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',- })-- const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api patch /orders/{order_id}/payments/{id}/void -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: Payment ID- schema:- type: string- responses:- '200':- description: payment voided- content:- application/json:- example:- id: py_UkLWZg9DAJ- payment_method_id: pm_UkLWZg9DAJ- response_code: void-BGS-442bc044007f- number: P36LG5QA- amount: '110.0'- display_amount: "$110.00"- status: void- 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-07-20T06:57:30.231Z'- updated_at: '2026-07-20T06:57:30.233Z'- metadata: {}- avs_response:- cvv_response_code:- cvv_response_message:- created_at: '2026-07-20T06:57:30.232Z'- updated_at: '2026-07-20T06:57:30.545Z'- captured_amount: '0.0'- order_id: or_UkLWZg9DAJ- "/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.-- **Required scope:** `read_products` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const { data: priceLists } = await client.priceLists.list()- - lang: bash- label: Spree CLI- source: spree api get /price_lists- parameters:- - name: x-spree-api-key- in: header- 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:- example:- data:- - id: pl_UkLWZg9DAJ- name: Wholesale- description:- status: draft- position: 1- match_policy: all- starts_at:- ends_at:- deleted_at:- created_at: '2026-07-20T06:57:45.077Z'- updated_at: '2026-07-20T06:57:45.077Z'- currently_active: false- products_count: 0- prices_count: 0- product_ids: []- - id: pl_gbHJdmfrXB- name: Holiday- description:- status: draft- position: 2- match_policy: all- starts_at:- ends_at:- deleted_at:- created_at: '2026-07-20T06:57:45.078Z'- updated_at: '2026-07-20T06:57:45.078Z'- currently_active: false- products_count: 0- prices_count: 0- product_ids: []- 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/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.-- **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',- })-- // 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)`), so there's no need to- // pre-declare `product_ids` separately.- const priceList = await client.priceLists.create({- name: 'EU wholesale',- description: 'Tiered pricing for verified B2B customers',- match_policy: 'all',- starts_at: '2026-06-01T00:00:00Z',- ends_at: '2026-09-01T00:00:00Z',- rules: [- {- type: 'customer_group_rule',- preferences: { customer_group_ids: ['cg_aBc123'] },- },- {- type: 'volume_rule',- preferences: { min_quantity: 10 },- },- ],- prices: [- {- variant_id: 'variant_xY9',- currency: 'USD',- amount: '19.99',- compare_at_amount: '24.99',- },- {- variant_id: 'variant_aB7',- currency: 'USD',- amount: '21.99',- },- ],- })- - lang: bash- label: Spree CLI- source: spree api post /price_lists -d '{"name":"EU wholesale","description":"Tiered- pricing for verified B2B customers","match_policy":"all","starts_at":"2026-06-01T00:00:00Z","ends_at":"2026-09-01T00:00:00Z","rules":[{"type":"customer_group_rule","preferences":{"customer_group_ids":["cg_aBc123"]}},{"type":"volume_rule","preferences":{"min_quantity":10}}],"prices":[{"variant_id":"variant_xY9","currency":"USD","amount":"19.99","compare_at_amount":"24.99"},{"variant_id":"variant_aB7","currency":"USD","amount":"21.99"}]}'- parameters:- - name: x-spree-api-key- in: header- 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, no product_ids)- content:- application/json:- example:- id: pl_EfhxLZ9ck8- name: EU wholesale- description:- status: draft- position: 3- match_policy: all- starts_at:- ends_at:- deleted_at:- created_at: '2026-07-20T06:57:46.040Z'- updated_at: '2026-07-20T06:57:46.042Z'- currently_active: false- products_count: 1- prices_count: 2- product_ids:- - prod_UkLWZg9DAJ- 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- product_ids:- type: array- items:- type: string- description: Prefixed product ids to seed the list with.- example:- - prod_aBc123- 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 alternative to `product_ids`: ship- the exact per-variant prices the list should contain. Each row- upserts on the unique key `(variant_id, currency, price_list_id)`.- Mix-and-match with `product_ids` is supported but typically unnecessary- — `prices` alone tells the server which variants belong to the- list and what the override amount is.'- 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- starts_at:- ends_at:- deleted_at:- created_at: '2026-07-20T06:57:46.362Z'- updated_at: '2026-07-20T06:57:46.362Z'- currently_active: false- products_count: 0- prices_count: 0- product_ids: []- 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- starts_at:- ends_at:- deleted_at:- created_at: '2026-07-20T06:57:47.993Z'- updated_at: '2026-07-20T06:57:48.305Z'- currently_active: false- products_count: 0- prices_count: 0- product_ids: []- 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- product_ids:- type: array- items:- type: string- description: Prefixed product ids — reconciles list membership (adds- + removes).- example:- - prod_aBc123- 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- starts_at:- ends_at:- deleted_at:- created_at: '2026-07-20T06:57:48.621Z'- updated_at: '2026-07-20T06:57:48.925Z'- currently_active: true- products_count: 0- prices_count: 0- product_ids: []- 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 1- description:- status: inactive- position: 1- match_policy: all- starts_at:- ends_at:- deleted_at:- created_at: '2026-07-20T06:57:48.963Z'- updated_at: '2026-07-20T06:57:49.297Z'- currently_active: false- products_count: 0- prices_count: 0- product_ids: []- 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_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-07-20T06:57:49.408Z'- updated_at: '2026-07-20T06:57:49.408Z'- - 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-07-20T06:57:49.412Z'- updated_at: '2026-07-20T06:57:49.412Z'- 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/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-07-20T06:57:50.058Z'- updated_at: '2026-07-20T06:57:50.058Z'- 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-07-20T06:57:50.113Z'- updated_at: '2026-07-20T06:57:50.113Z'- 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-07-20T06:57:50.790Z'- updated_at: '2026-07-20T06:57:51.084Z'- 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::Metafields::ShortText- field_type: short_text- key: custom.title- value: wool- created_at: '2026-07-20T06:57:52.553Z'- updated_at: '2026-07-20T06:57:52.553Z'- 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::Metafields::LongText- field_type: long_text- key: custom.description- value: A longer description- created_at: '2026-07-20T06:57:53.152Z'- updated_at: '2026-07-20T06:57:53.152Z'- 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: Metafield definition has already been taken- details:- metafield_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::Metafields::ShortText- field_type: short_text- key: custom.title- value: wool- created_at: '2026-07-20T06:57:53.507Z'- updated_at: '2026-07-20T06:57:53.507Z'- 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::Metafields::ShortText- field_type: short_text- key: custom.title- value: cotton- created_at: '2026-07-20T06:57:53.826Z'- updated_at: '2026-07-20T06:57:54.104Z'- 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: |-- Sed dignissimos tempora exercitationem aperiam laboriosam provident. Autem dignissimos expedita odit maiores magni. Exercitationem aperiam ipsum voluptas quas.- Occaecati quibusdam officiis eius fugiat aperiam veritatis. Voluptatibus necessitatibus quo beatae est incidunt. Aperiam dicta quam repellat atque hic.- Ipsam blanditiis quas deleniti explicabo molestias. Voluptates dolores itaque voluptatem asperiores sunt officiis delectus. Cupiditate delectus ipsam quas recusandae at fuga enim ipsum. Labore doloremque explicabo odit consequuntur quasi fugit eligendi.- - key: slug- type: string- source: espresso-machine- - key: meta_description- type: string- source:- - key: meta_title- type: string- source:- default_locale: en- supported_locales:- - de- - en- - fr- "/api/v3/admin/products":- get:- summary: List products- tags:- - Products- security:- - api_key: []- bearer_auth: []- description: |-- Returns a paginated list of products for the current store.-- **Required scope:** `read_products` (for API-key authentication).- x-codeSamples:- - lang: javascript- label: Spree Admin SDK- source: |-- import { createAdminClient } from '@spree/admin-sdk'-- const client = createAdminClient({- baseUrl: 'https://your-store.com',- secretKey: 'sk_xxx',- })-- const { data: products } = await client.products.list({- 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 622106- slug: product-622106- meta_title:- meta_description:- meta_keywords:- variant_count: 0- available_on:- preorder_ships_at:- purchasable: true- preorder: false- in_stock: false- backorderable: true- available: true- description: Rem magni iste dolore culpa itaque et dolor. Odio quia- suscipit incidunt repellendus laboriosam. Laborum laudantium explicabo- maxime ipsum commodi eveniet alias perferendis. Odit reprehenderit- quibusdam placeat sequi minus. Unde quod suscipit sapiente aspernatur- repellat distinctio. Voluptatem molestias reprehenderit itaque- voluptates ab quis. Nemo quos minima consectetur officiis ex asperiores- suscipit. Iusto voluptatibus eligendi labore nisi aliquam ab modi- cupiditate. Laudantium hic sed aspernatur nisi alias eum nemo.- Alias consequatur sapiente quidem natus nihil fugiat. Beatae labore- id harum aperiam minima totam quos saepe. Aliquam aspernatur repellat- iste libero. Veniam autem nisi voluptas incidunt consectetur reprehenderit- laboriosam quidem. Commodi quis reiciendis tenetur sit occaecati- expedita repellendus eum. Veritatis error nobis laudantium sit- nesciunt dolore reprehenderit.- description_html: |-- Rem magni iste dolore culpa itaque et dolor. Odio quia suscipit incidunt repellendus laboriosam. Laborum laudantium explicabo maxime ipsum commodi eveniet alias perferendis. Odit reprehenderit quibusdam placeat sequi minus. Unde quod suscipit sapiente aspernatur repellat distinctio.- Voluptatem molestias reprehenderit itaque voluptates ab quis. Nemo quos minima consectetur officiis ex asperiores suscipit. Iusto voluptatibus eligendi labore nisi aliquam ab modi cupiditate. Laudantium hic sed aspernatur nisi alias eum nemo. Alias consequatur sapiente quidem natus nihil fugiat.- Beatae labore id harum aperiam minima totam quos saepe. Aliquam aspernatur repellat iste libero. Veniam autem nisi voluptas incidunt consectetur reprehenderit laboriosam quidem. Commodi quis reiciendis tenetur sit occaecati expedita repellendus eum. Veritatis error nobis laudantium sit nesciunt dolore reprehenderit.- default_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-07-20T06:57:54.794Z'- updated_at: '2026-07-20T06:57:54.794Z'- original_price:- status: active- metadata: {}- deleted_at:- created_at: '2026-07-20T06:57:54.781Z'- updated_at: '2026-07-20T06:57:54.801Z'- 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',- description: 'Soft, organic cotton.',- 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_items: [{ 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_items: [{ 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":"Soft,- organic cotton.","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_items":[{"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_items":[{"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- thumbnail_url:- tags: []- price:- original_price:- status: draft- metadata: {}- deleted_at:- created_at: '2026-07-20T06:57:55.542Z'- updated_at: '2026-07-20T06:57:55.544Z'- 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_items:` (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_items:- 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 666722- slug: product-666722- meta_title:- meta_description:- meta_keywords:- variant_count: 0- available_on:- preorder_ships_at:- purchasable: true- preorder: false- in_stock: false- backorderable: true- available: true- description: Rerum exercitationem porro ab consequuntur doloribus.- Animi dicta sequi quibusdam ab. Quibusdam quod fuga quia ab. Consequatur- culpa cum perferendis eius officiis nobis.- description_html: Rerum exercitationem porro ab consequuntur doloribus.- Animi dicta sequi quibusdam ab. Quibusdam quod fuga quia ab. Consequatur- culpa cum perferendis eius officiis nobis.- default_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-07-20T06:57:55.933Z'- updated_at: '2026-07-20T06:57:55.933Z'- original_price:- status: active- metadata: {}- deleted_at:- created_at: '2026-07-20T06:57:55.923Z'- updated_at: '2026-07-20T06:57:55.939Z'- 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-686952- meta_title:- meta_description:- meta_keywords:- variant_count: 0- available_on:- preorder_ships_at:- purchasable: true- preorder: false- in_stock: false- backorderable: true- available: true- description: Quo impedit enim quibusdam doloremque ea. Quo quis quod- hic ullam. Repellat debitis repudiandae occaecati iste quis molestiae- ratione vel. Quas illum cumque debitis quia a sed facere nostrum.- Ex autem recusandae cumque quas eaque. Dicta error reiciendis suscipit- doloremque ipsum dolore iste. Eligendi reiciendis eius ad nam quo.- Esse facere unde est dolor. Exercitationem minima natus ducimus- beatae quo. Accusamus voluptate neque ipsam culpa aliquam. Velit- vel deleniti ullam neque iusto dolor corporis. Tenetur saepe hic- repellat eaque doloremque. Maiores neque natus iste provident eligendi- illum consequatur eos. Hic autem a labore culpa eligendi. Saepe- sapiente soluta molestias explicabo nostrum quam. Necessitatibus- dicta vitae est natus. Laboriosam velit quaerat amet delectus expedita- ipsa. Officia dolorem beatae dolore sint. Cumque dicta facilis animi- cum odit recusandae unde.- description_html: |-- Quo impedit enim quibusdam doloremque ea. Quo quis quod hic ullam. Repellat debitis repudiandae occaecati iste quis molestiae ratione vel. Quas illum cumque debitis quia a sed facere nostrum. Ex autem recusandae cumque quas eaque.- Dicta error reiciendis suscipit doloremque ipsum dolore iste. Eligendi reiciendis eius ad nam quo. Esse facere unde est dolor. Exercitationem minima natus ducimus beatae quo.- Accusamus voluptate neque ipsam culpa aliquam. Velit vel deleniti ullam neque iusto dolor corporis. Tenetur saepe hic repellat eaque doloremque. Maiores neque natus iste provident eligendi illum consequatur eos. Hic autem a labore culpa eligendi.- Saepe sapiente soluta molestias explicabo nostrum quam. Necessitatibus dicta vitae est natus. Laboriosam velit quaerat amet delectus expedita ipsa. Officia dolorem beatae dolore sint. Cumque dicta facilis animi cum odit recusandae unde.- default_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-07-20T06:57:56.662Z'- updated_at: '2026-07-20T06:57:56.662Z'- original_price:- status: active- metadata: {}- deleted_at:- created_at: '2026-07-20T06:57:56.653Z'- updated_at: '2026-07-20T06:57:56.978Z'- 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_items:` (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_items:- 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- "/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 (taxon) 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_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/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-07-20T06:56:39.585Z'- updated_at: '2026-07-20T06:56:39.585Z'- promotion_id: promo_UkLWZg9DAJ- order_id:- - id: coupon_gbHJdmfrXB- code: BBB222- state: unused- created_at: '2026-07-20T06:56:39.586Z'- updated_at: '2026-07-20T06:56:39.586Z'- 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-07-20T06:58:01.736Z'- updated_at: '2026-07-20T06:58:01.736Z'- 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-07-20T06:58:02.399Z'- updated_at: '2026-07-20T06:58:02.399Z'- 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-07-20T06:58:03.022Z'- updated_at: '2026-07-20T06:58:03.022Z'- type: currency- promotion_id: promo_UkLWZg9DAJ- preferences:- currency: USD- preference_schema:- - key: currency- type: string- default:- label: Currency- product_ids:- category_ids:- customer_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-07-20T06:58:03.651Z'- updated_at: '2026-07-20T06:58:03.651Z'- type: currency- promotion_id: promo_UkLWZg9DAJ- preferences:- currency: EUR- preference_schema:- - key: currency- type: string- default:- label: Currency- product_ids:- category_ids:- customer_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-07-20T06:58:03.943Z'- updated_at: '2026-07-20T06:58:04.240Z'- type: currency- promotion_id: promo_UkLWZg9DAJ- preferences:- currency: GBP- preference_schema:- - key: currency- type: string- default:- label: Currency- product_ids:- category_ids:- customer_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-07-20T06:58:04.566Z'- 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-07-20T06:58:04.566Z'- updated_at: '2026-07-20T06:58:04.566Z'- 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-07-20T06:58:05.510Z'- 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-07-20T06:58:05.510Z'- updated_at: '2026-07-20T06:58:05.530Z'- 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-07-20T06:58:05.833Z'- 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-07-20T06:58:05.833Z'- updated_at: '2026-07-20T06:58:05.833Z'- 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-07-20T06:58:06.718Z'- 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-07-20T06:58:06.718Z'- updated_at: '2026-07-20T06:58:07.014Z'- 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_isos- type: array- default: []- - key: country_id- type: integer- default:- - key: country_iso- 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: match_policy- type: string- default: any- - key: eligible_values- type: array- default: []- - 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-58c473833f77- amount: '5.0'- payment_id: py_UkLWZg9DAJ- refund_reason_id: rr_UkLWZg9DAJ- reimbursement_id:- metadata: {}- created_at: '2026-07-20T06:57:31.879Z'- updated_at: '2026-07-20T06:57:31.879Z'- 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_credit_categories":- get:- summary: List store credit categories- tags:- - Settings- security:- - api_key: []- bearer_auth: []- description: |-- Returns the configured store credit categories. Categories classify- store credits (e.g., "Goodwill", "Gift Card", "Refund") and surface- in the admin UI as a dropdown when issuing or editing a store- credit. Category names matching `Spree::Config[:non_expiring_credit_types]`- are flagged via `non_expiring: true`.--- **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: categories } = await client.storeCreditCategories.list()- - lang: bash- label: Spree CLI- source: spree api get /store_credit_categories- parameters:- - name: x-spree-api-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: store credit categories found- content:- application/json:- example:- data:- - id: sccat_UkLWZg9DAJ- name: Goodwill- created_at: '2026-07-20T06:58:10.500Z'- updated_at: '2026-07-20T06:58:10.500Z'- non_expiring: false- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/StoreCreditCategory"- 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/store_credit_categories/{id}":- parameters:- - name: id- in: path- required: true- description: Store credit category ID- schema:- type: string- get:- summary: Get a store credit category- tags:- - Settings- security:- - api_key: []- bearer_auth: []- description: |-- Returns a single store credit category 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 category = await client.storeCreditCategories.get('sccat_UkLWZg9DAJ')- - lang: bash- label: Spree CLI- source: spree api get /store_credit_categories/{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: store credit category found- content:- application/json:- example:- id: sccat_UkLWZg9DAJ- name: Goodwill- created_at: '2026-07-20T06:58:10.797Z'- updated_at: '2026-07-20T06:58:10.797Z'- non_expiring: false- schema:- "$ref": "#/components/schemas/StoreCreditCategory"- '404':- description: store credit category not found- content:- application/json:- example:- error:- code: record_not_found- message: Store credit category not found- 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.-- **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- 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_unit_system: imperial- preferred_storefront_access: public- preferred_guest_checkout: true- created_at: '2026-07-20T06:56:26.135Z'- updated_at: '2026-07-20T06:58:11.378Z'- 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- 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- 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_unit_system: imperial- preferred_storefront_access: public- preferred_guest_checkout: true- created_at: '2026-07-20T06:56:26.135Z'- updated_at: '2026-07-20T06:58:12.014Z'- 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- 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::LegacyUser- "/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: category- fields:- - key: name- type: string- - key: pretty_name- type: string- - key: description- type: html- - key: permalink- type: string- readable: true- - resource_type: taxonomy- fields:- - key: name- type: string- readable: false- - 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: false- "/api/v3/admin/translations/batch":- post:- summary: Batch upsert translations- tags:- - Settings- security:- - api_key: []- bearer_auth: []- description: |-- Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.-- **Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).- parameters:- - name: x-spree-api-key- in: header- required: true- schema:- type: string- - name: Authorization- in: header- required: true- schema:- type: string- responses:- '200':- description: translations upserted- content:- application/json:- example:- data:- - resource_id: opt_UkLWZg9DAJ- resource_type: option_type- translations:- de:- label: Größe- translated_field_count: 1- fr:- label:- translated_field_count: 0- default_locale: en- supported_locales:- - de- - en- - fr- - resource_id: optval_UkLWZg9DAJ- resource_type: option_value- translations:- de:- label: Klein- translated_field_count: 1- fr:- label:- translated_field_count: 0- default_locale: en- supported_locales:- - de- - en- - fr- '422':- description: unsupported locale rolls back the whole batch- content:- application/json:- example:- error:- code: validation_error- message: 'Unsupported locale(s): es'- details:- translations:- '0':- - 'Unsupported locale(s): es'- requestBody:- content:- application/json:- schema:- type: object- required:- - translations- properties:- translations:- type: array- items:- type: object- required:- - resource_type- - resource_id- - values- properties:- resource_type:- type: string- description: Translatable resource type token, e.g. `option_type`- resource_id:- type: string- description: Prefixed id of the record- values:- type: object- description: 'Map of locale code to { field: value }'- additionalProperties:- type: object- additionalProperties: true- "/api/v3/admin/admin_users":- get:- summary: List staff- tags:- - Staff- security:- - api_key: []- bearer_auth: []- description: |-- Returns admin users with at least one role assignment on the current store.-- **Required scope:** `read_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: 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: admin_UkLWZg9DAJ- email: [email protected]- first_name: Ozell- last_name: O'Kon- full_name: Ozell O'Kon- selected_locale:- created_at: '2026-07-20T06:56:26.499Z'- updated_at: '2026-07-20T06:56:26.499Z'- avatar_url:- roles:- - id: role_UkLWZg9DAJ- name: admin- 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_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 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: admin_UkLWZg9DAJ- email: [email protected]- first_name: Gayla- last_name: Carter- full_name: Gayla Carter- selected_locale:- created_at: '2026-07-20T06:56:26.867Z'- updated_at: '2026-07-20T06:56:26.867Z'- avatar_url:- roles:- - id: role_UkLWZg9DAJ- name: admin- 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_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 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: admin_UkLWZg9DAJ- email: [email protected]- first_name: Renamed- last_name: Predovic- full_name: Renamed Predovic- selected_locale:- created_at: '2026-07-20T06:56:27.154Z'- updated_at: '2026-07-20T06:56:27.172Z'- avatar_url:- roles:- - id: role_UkLWZg9DAJ- name: admin- 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_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.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_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: 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-07-20T06:57:07.705Z'- updated_at: '2026-07-20T06:57:07.705Z'- expires_at: '2026-08-03T06:57:07.703Z'- role_id: role_UkLWZg9DAJ- role_name: admin- inviter_email: [email protected]- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=h1AKTQuWUyJWVtzSFqD7A8PE"- 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_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 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-07-20T06:57:08.013Z'- updated_at: '2026-07-20T06:57:08.013Z'- expires_at: '2026-08-03T06:57:08.011Z'- role_id: role_UkLWZg9DAJ- role_name: admin- inviter_email: [email protected]- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=MfUyYL3kBSudPikqhHMzSqB6"- 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_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.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_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 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-07-20T06:57:08.578Z'- updated_at: '2026-07-20T06:57:08.578Z'- expires_at: '2026-08-03T06:57:08.576Z'- role_id: role_UkLWZg9DAJ- role_name: admin- inviter_email: [email protected]- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=r8pNyvsDduRdeq1V4zgLKiPB"- invitee_exists: false- store:- id: store_UkLWZg9DAJ- name: Spree Test Store- "/api/v3/admin/roles":- get:- summary: List roles- tags:- - Staff- security:- - api_key: []- bearer_auth: []- description: |-- Returns the roles available for staff role pickers. Roles are global, not per-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: 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- created_at: '2026-07-20T06:58:07.895Z'- updated_at: '2026-07-20T06:58:07.895Z'- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- "/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- state_abbr: STATE_ABBR_50- name: Brooklyn warehouse- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_iso: US- country_name: United States of America- state_text: STATE_ABBR_50- 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- pickup_ready_in_minutes:- pickup_instructions:- created_at: '2026-07-20T06:58:08.189Z'- updated_at: '2026-07-20T06:58:08.189Z'- 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_iso: 'US',- state_abbr: '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_iso":"US","state_abbr":"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- state_abbr:- name: Manhattan store- address1:- city:- zipcode:- country_iso:- country_name:- state_text:- 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- pickup_ready_in_minutes: 30- pickup_instructions:- created_at: '2026-07-20T06:58:08.771Z'- updated_at: '2026-07-20T06:58:08.771Z'- 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_iso:- type: string- nullable: true- description: ISO-3166 alpha-2 country code (e.g. "US").- state_abbr:- 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- state_abbr: STATE_ABBR_54- name: Brooklyn warehouse- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_iso: US- country_name: United States of America- state_text: STATE_ABBR_54- 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- pickup_ready_in_minutes:- pickup_instructions:- created_at: '2026-07-20T06:58:09.063Z'- updated_at: '2026-07-20T06:58:09.063Z'- 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- state_abbr: STATE_ABBR_56- name: Renamed warehouse- address1: 1600 Pennsylvania Ave NW- city: Washington- zipcode: '20500'- country_iso: US- country_name: United States of America- state_text: STATE_ABBR_56- 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- pickup_ready_in_minutes: 45- pickup_instructions:- created_at: '2026-07-20T06:58:09.648Z'- updated_at: '2026-07-20T06:58:09.923Z'- 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_iso:- type: string- nullable: true- state_abbr:- 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 master 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_items'],- })- - lang: bash- label: Spree CLI- source: spree api get /products/{product_id}/variants -d '{"expand":["prices","stock_items"]}'- parameters:- - name: x-spree-api-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_items, 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-103- options_text: ''- 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:- price:- id:- amount:- amount_in_cents: 0- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$0.00"- display_compare_at_amount:- price_list_id:- original_price:- option_values: []- metadata: {}- position: 1- cost_price: '17.0'- cost_currency: USD- barcode:- weight_unit: lb- dimensions_unit:- backorder_limit:- deleted_at:- created_at: '2026-07-20T06:58:14.331Z'- updated_at: '2026-07-20T06:58:14.338Z'- preorderable: false- tax_category_id: taxcat_UkLWZg9DAJ- available_stock: 0- reserved_quantity: 0- total_on_hand: 0- product_name: Product 844385- - id: variant_gbHJdmfrXB- product_id: prod_UkLWZg9DAJ- sku: SKU-104- 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: 122.34- height: 14.79- width: 190.2- depth: 74.61- 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:- option_values:- - id: optval_UkLWZg9DAJ- option_type_id: opt_UkLWZg9DAJ- name: size-19- label: S- position: 1- color_code:- option_type_name: foo-size-28- option_type_label: Size- image_url:- metadata: {}- created_at: '2026-07-20T06:58:14.352Z'- updated_at: '2026-07-20T06:58:14.352Z'- metadata: {}- position: 2- cost_price: '17.0'- cost_currency: USD- barcode:- weight_unit: lb- dimensions_unit:- backorder_limit:- deleted_at:- created_at: '2026-07-20T06:58:14.350Z'- updated_at: '2026-07-20T06:58:14.360Z'- preorderable: false- tax_category_id: taxcat_UkLWZg9DAJ- available_stock: 0- reserved_quantity: 0- total_on_hand: 0- product_name: Product 844385- 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_items: [{ 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_items":[{"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:- price:- id: price_EfhxLZ9ck8- amount: '24.99'- amount_in_cents: 2499- compare_at_amount:- compare_at_amount_in_cents:- currency: USD- display_amount: "$24.99"- display_compare_at_amount:- price_list_id:- original_price:- 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-07-20T06:58:15.002Z'- updated_at: '2026-07-20T06:58:15.002Z'- metadata: {}- position: 3- cost_price:- cost_currency: USD- barcode:- weight_unit: lb- dimensions_unit:- backorder_limit:- deleted_at:- created_at: '2026-07-20T06:58:15.005Z'- updated_at: '2026-07-20T06:58:15.007Z'- preorderable: false- tax_category_id: taxcat_UkLWZg9DAJ- available_stock: 0- reserved_quantity: 0- total_on_hand: 0- product_name: Product 852128- '422':- description: validation error- content:- application/json:- example:- error:- code: validation_error- message: Option value variants can't be blank- details:- option_value_variants:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- required:- - options- 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: Required. A variant created here is always non-master,- so it must declare at least one option pair (e.g. size + color)- or creation fails with 422. One pair per option type the variant- 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_items:- 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_items'],- })- - lang: bash- label: Spree CLI- source: spree api get /products/{product_id}/variants/{id} -d '{"expand":["prices","stock_items"]}'- parameters:- - name: x-spree-api-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_items, 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-110- 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: 53.91- height: 36.86- width: 41.29- depth: 137.2- 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:- option_values:- - id: optval_UkLWZg9DAJ- option_type_id: opt_UkLWZg9DAJ- name: size-22- label: S- position: 1- color_code:- option_type_name: foo-size-31- option_type_label: Size- image_url:- metadata: {}- created_at: '2026-07-20T06:58:15.514Z'- updated_at: '2026-07-20T06:58:15.514Z'- metadata: {}- position: 2- cost_price: '17.0'- cost_currency: USD- barcode:- weight_unit: lb- dimensions_unit:- backorder_limit:- deleted_at:- created_at: '2026-07-20T06:58:15.509Z'- updated_at: '2026-07-20T06:58:15.533Z'- preorderable: false- tax_category_id: taxcat_UkLWZg9DAJ- available_stock: 0- reserved_quantity: 0- total_on_hand: 0- product_name: Product 878838- '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_items: [- { 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_items":[{"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: 187.69- height: 68.26- width: 90.44- depth: 179.69- 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:- option_values:- - id: optval_UkLWZg9DAJ- option_type_id: opt_UkLWZg9DAJ- name: size-24- label: S- position: 1- color_code:- option_type_name: foo-size-33- option_type_label: Size- image_url:- metadata: {}- created_at: '2026-07-20T06:58:16.338Z'- updated_at: '2026-07-20T06:58:16.338Z'- metadata: {}- position: 2- cost_price: '17.0'- cost_currency: USD- barcode:- weight_unit: lb- dimensions_unit:- backorder_limit:- deleted_at:- created_at: '2026-07-20T06:58:16.335Z'- updated_at: '2026-07-20T06:58:16.651Z'- preorderable: false- tax_category_id: taxcat_UkLWZg9DAJ- available_stock: 0- reserved_quantity: 0- total_on_hand: 0- product_name: Product 899952- 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_items:- 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_gbHJdmfrXB- event_name: order.created- event_id:- response_code: 500- execution_time: 200- error_type:- request_errors:- response_body:- success: false- payload:- event: order.created- data:- id: 1- created_at: '2026-07-20T06:58:17.289Z'- updated_at: '2026-07-20T06:58:17.289Z'- delivered_at: '2026-07-20T06:58:17.289Z'- webhook_endpoint_id: whe_UkLWZg9DAJ- webhook_endpoint_url: https://shop.example.com/webhooks- - id: whd_UkLWZg9DAJ- event_name: order.created- event_id:- response_code: 200- execution_time: 150- error_type:- request_errors:- response_body:- success: true- payload:- event: order.created- data:- id: 1- created_at: '2026-07-20T06:58:17.287Z'- updated_at: '2026-07-20T06:58:17.287Z'- delivered_at: '2026-07-20T06:58:17.287Z'- 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- payload:- event: order.created- data:- id: 1- created_at: '2026-07-20T06:58:18.175Z'- updated_at: '2026-07-20T06:58:18.175Z'- delivered_at: '2026-07-20T06:58:18.175Z'- 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:- payload:- event: order.created- data:- id: 1- created_at: '2026-07-20T06:58:19.124Z'- updated_at: '2026-07-20T06:58:19.124Z'- delivered_at:- 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-07-20T06:58:19.342Z'- updated_at: '2026-07-20T06:58:19.342Z'- 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.completed', '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.completed","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.completed- disabled_reason:- created_at: '2026-07-20T06:58:20.498Z'- updated_at: '2026-07-20T06:58:20.498Z'- disabled_at:- secret_key: 26b2f57058836c3b4476b5d1aad96bb8da0b92d26118b763fcc43934dd97f360- 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.completed- - 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-07-20T06:58:20.944Z'- updated_at: '2026-07-20T06:58:20.944Z'- 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.completed', 'order.canceled', 'order.paid'],- })- - lang: bash- label: Spree CLI- source: spree api patch /webhook_endpoints/{id} -d '{"name":"Order pipeline- (v2)","subscriptions":["order.completed","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-07-20T06:58:21.966Z'- updated_at: '2026-07-20T06:58:22.256Z'- 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:- payload:- id: a73c9017-1353-49c2-a3cd-8096a3058646- name: webhook.test- created_at: '2026-07-20T06:58:23Z'- data:- message: This is a test webhook from Spree.- metadata:- spree_version: 5.6.0.rc3- created_at: '2026-07-20T06:58:23.335Z'- updated_at: '2026-07-20T06:58:23.335Z'- delivered_at:- 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-07-20T06:58:23.373Z'- updated_at: '2026-07-20T06:58:23.652Z'- 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-07-20T06:58:23.698Z'- updated_at: '2026-07-20T06:58:23.978Z'- disabled_at: '2026-07-20T06:58:23.978Z'- 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/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:- example:- 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- metadata: {}- pretty_name: Clothing- lft: 1- rgt: 2- products_count: 0- created_at: '2026-07-20T06:56:33.827Z'- updated_at: '2026-07-20T06:56:33.827Z'- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Category"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- post:- summary: Create a category- tags:- - 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:- 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- metadata: {}- pretty_name: Clothing -> Shirts- lft: 2- rgt: 3- products_count: 0- created_at: '2026-07-20T06:56:34.407Z'- updated_at: '2026-07-20T06:56:34.413Z'- schema:- "$ref": "#/components/schemas/Category"- '422':- description: validation error- content:- application/json:- example:- error:- code: validation_error- message: Name can't be blank- details:- name:- - can't be blank- schema:- "$ref": "#/components/schemas/ErrorResponse"- requestBody:- content:- application/json:- schema:- type: object- properties:- 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- hide_from_nav:- type: boolean- example: false- 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:- 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- metadata: {}- pretty_name: Clothing- lft: 1- rgt: 2- products_count: 0- created_at: '2026-07-20T06:56:34.722Z'- updated_at: '2026-07-20T06:56:34.722Z'- schema:- "$ref": "#/components/schemas/Category"- '404':- description: category not found- content:- application/json:- example:- error:- code: record_not_found- message: Category not found- schema:- "$ref": "#/components/schemas/ErrorResponse"- patch:- summary: Update a category- tags:- - 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:- 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- metadata: {}- pretty_name: Apparel- lft: 1- rgt: 2- products_count: 0- created_at: '2026-07-20T06:56:35.316Z'- updated_at: '2026-07-20T06:56:35.603Z'- 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- hide_from_nav:- type: boolean- 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:- 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- metadata: {}- pretty_name: Clothing -> Footwear- lft: 2- rgt: 3- products_count: 0- created_at: '2026-07-20T06:56:35.919Z'- updated_at: '2026-07-20T06:56:36.212Z'- schema:- "$ref": "#/components/schemas/Category"+ id: imp_gbHJdmfrXB+ number: IM326512320+ type: Spree::Imports::Products+ rows_count: 0+ created_at: '2026-07-21T16:18:45.155Z'+ updated_at: '2026-07-21T16:18:45.199Z'+ status: mapping+ owner_type: Spree::Store+ owner_id: store_UkLWZg9DAJ+ user_id: admin_UkLWZg9DAJ+ processing_errors:+ preferred_delimiter: ","+ 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: shipping_category+ label: Shipping Category+ 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: shipping_category+ file_column:+ required: false+ - id: immap_3uWpPTcf5W+ schema_field: image1_src+ file_column:+ required: false+ - id: immap_D6Psx31WaT+ schema_field: image2_src+ file_column:+ required: false+ - id: immap_msx3nOJap6+ schema_field: image3_src+ file_column:+ required: false+ - id: immap_5CQZnCRf8J+ schema_field: option1_name+ file_column:+ required: false+ - id: immap_M2nyloHRUQ+ schema_field: option1_value+ file_column:+ required: false+ - id: immap_prklVeMgbn+ schema_field: option2_name+ file_column:+ required: false+ - id: immap_so8jaGonyx+ schema_field: option2_value+ file_column:+ required: false+ - id: immap_rsClYtECFI+ schema_field: option3_name+ file_column:+ required: false+ - id: immap_8DR0I7fEbw+ schema_field: option3_value+ file_column:+ required: false+ - id: immap_aAtNvLSUAr+ schema_field: category1+ file_column:+ required: false+ - id: immap_QiA48cIW7A+ schema_field: category2+ file_column:+ required: false+ - id: immap_QDA48cIW7A+ schema_field: category3+ file_column:+ required: false+ '422':+ description: unknown import type+ content:+ application/json:+ 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:- new_parent_id:+ type: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":+ enum:+ - Spree::Imports::Products+ - Spree::Imports::Customers+ - Spree::Imports::ProductTranslations+ example: Spree::Imports::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: List category products+ summary: Download an import templatetags:- - Categories+ - Importssecurity:- api_key: []bearer_auth: []description: |-- Products classified under the category, ordered by their classification position.+ Returns a CSV header row for the given import type, including the custom field columns available for the model.- **Required scope:** `read_categories` (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@@ -19738,55 +8090,35 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- - name: category_id- in: path+ - name: type+ in: queryrequired: true- description: Category ID+ description: Registered import type, e.g. Spree::Imports::Products.schema:type: stringresponses:'200':- description: products found+ description: CSV templatecontent:- application/json:- example:- data: []- meta:- page: 1- limit: 25- count: 0- pages: 1- from: 0- to: 0- in: 0- previous:- next:+ application/json: {}+ text/csv:schema:- type: object- properties:- data:- type: array- items:- "$ref": "#/components/schemas/Product"- meta:- "$ref": "#/components/schemas/PaginationMeta"- required:- - data- - meta- post:- summary: Add a product to a category+ type: string+ format: binary+ "/api/v3/admin/imports/{id}":+ get:+ summary: Show an importtags:- - Categories+ - Importssecurity:- api_key: []bearer_auth: []description: |-- Classifies a product under the category (appended to the end).+ 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:** `write_categories` (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@@ -19796,89 +8128,162 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authenticationschema:type: string- - name: category_id+ - name: idin: pathrequired: true- description: Category IDschema:type: stringresponses:- '201':- description: product added+ '200':+ description: import foundcontent:application/json:example:- id: prod_UkLWZg9DAJ- name: Product 16683- slug: product-16683- meta_title:- meta_description:- meta_keywords:- variant_count: 0- available_on:- preorder_ships_at:- purchasable: true- preorder: false- in_stock: false- backorderable: true- available: true- description: Consequuntur neque dolor quae aut assumenda inventore.- Illo neque doloribus natus repellendus soluta. Unde nihil sint sit- ab eius porro.- description_html: Consequuntur neque dolor quae aut assumenda inventore.- Illo neque doloribus natus repellendus soluta. Unde nihil sint sit- ab eius porro.- default_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-07-20T06:56:36.627Z'- updated_at: '2026-07-20T06:56:36.627Z'- original_price:- status: active- metadata: {}- deleted_at:- created_at: '2026-07-20T06:56:36.604Z'- updated_at: '2026-07-20T06:56:36.638Z'- tax_category_id: taxcat_UkLWZg9DAJ- schema:- "$ref": "#/components/schemas/Product"- requestBody:- content:- application/json:- schema:- type: object- properties:- product_id:- type: string- example: prod_abc123- required:- - product_id- "/api/v3/admin/categories/{category_id}/products/{id}/reposition":- patch:- summary: Reposition a category product+ id: imp_UkLWZg9DAJ+ number: IM458953931+ type: Spree::Imports::Products+ rows_count: 0+ created_at: '2026-07-21T16:18:46.069Z'+ updated_at: '2026-07-21T16:18:46.076Z'+ status: pending+ owner_type: Spree::Store+ owner_id: store_UkLWZg9DAJ+ user_id: admin_UkLWZg9DAJ+ processing_errors:+ preferred_delimiter: ","+ original_filename: products_import.csv+ original_byte_size: 3612+ 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: shipping_category+ label: Shipping Category+ 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:- - Categories+ - Importssecurity:- api_key: []bearer_auth: []description: |-- Moves a product to a new index among the category's products.+ Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.- **Required scope:** `write_categories` (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@@ -19888,45 +8293,26 @@ paths:- name: Authorizationin: headerrequired: true- description: Bearer token for admin authentication- schema:- type: string- - name: category_id- in: path- required: true- description: Category IDschema:type: string- name: idin: pathrequired: true- description: Product IDschema:type: stringresponses:'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/imports":+ description: import deleted+ "/api/v3/admin/imports/{id}/download":get:- summary: List imports+ summary: Download the originally uploaded filetags:- Importssecurity:- api_key: []bearer_auth: []description: |-- Returns CSV imports queued or completed for the current store.+ 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:@@ -19940,172 +8326,33 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:'200':- description: imports found+ description: CSV filecontent:- application/json:- example:- data:- - id: imp_UkLWZg9DAJ- number: IM937584249- type: Spree::Imports::Products- rows_count: 0- created_at: '2026-07-20T06:57:04.567Z'- updated_at: '2026-07-20T06:57:04.574Z'- status: pending- owner_type: Spree::Store- owner_id: store_UkLWZg9DAJ- user_id: admin_UkLWZg9DAJ- processing_errors:- preferred_delimiter: ","- original_filename: products_import.csv- original_byte_size: 3612- 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: shipping_category- label: Shipping Category- required: false- - name: image1_src- label: Image 1 URL- required: false- - name: image2_src- label: Image 2 URL- required: false- - name: image3_src- label: Image 3 URL- required: false- - name: option1_name- label: Option 1 Name- required: false- - name: option1_value- label: Option 1 Value- required: false- - name: option2_name- label: Option 2 Name- required: false- - name: option2_value- label: Option 2 Value- required: false- - name: option3_name- label: Option 3 Name- required: false- - name: option3_value- label: Option 3 Value- required: false- - name: category1- label: Category 1- required: false- - name: category2- label: Category 2- required: false- - name: category3- label: Category 3- required: false- csv_headers: []- sample_row: {}- mappings: []- meta:- page: 1- limit: 25- count: 1- pages: 1- from: 1- to: 1- in: 1- previous:- next:- post:- summary: Create an import+ application/json: {}+ text/csv:+ schema:+ type: string+ format: binary+ "/api/v3/admin/imports/{id}/complete_mapping":+ patch:+ summary: Complete mapping and start processingtags:- Importssecurity:- 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`.+ 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).@@ -20120,26 +8367,31 @@ paths:required: trueschema:type: string+ - name: id+ in: path+ required: true+ schema:+ type: stringresponses:- '201':- description: import created in mapping state+ '200':+ description: mapping completed, processing queuedcontent:application/json:example:id: imp_gbHJdmfrXB- number: IM319349748+ number: IM358913381type: Spree::Imports::Productsrows_count: 0- created_at: '2026-07-20T06:57:04.889Z'- updated_at: '2026-07-20T06:57:04.933Z'- status: mapping+ created_at: '2026-07-21T16:18:46.976Z'+ updated_at: '2026-07-21T16:18:47.061Z'+ status: completed_mappingowner_type: Spree::Storeowner_id: store_UkLWZg9DAJuser_id: admin_UkLWZg9DAJprocessing_errors:preferred_delimiter: ","- original_filename: import.csv- original_byte_size: 44+ original_filename: products_import.csv+ original_byte_size: 3612original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"completed_rows_count: 0failed_rows_count: 0@@ -20255,16 +8507,8 @@ paths:- name: category3label: Category 3required: false- csv_headers:- - slug- - sku- - name- - price- sample_row:- slug: widget- sku: W-1- name: Widget- price: '10.00'+ csv_headers: []+ sample_row: {}mappings:- id: immap_UkLWZg9DAJschema_field: slug@@ -20284,83 +8528,83 @@ paths:required: true- id: immap_uw2YK1rnl0schema_field: status- file_column:+ file_column: statusrequired: false- id: immap_OIJLhNcSbfschema_field: description- file_column:+ file_column: descriptionrequired: false- id: immap_AXs1igzRC6schema_field: meta_title- file_column:+ file_column: meta_titlerequired: false- id: immap_p6klVeMgbnschema_field: meta_description- file_column:+ file_column: meta_descriptionrequired: false- id: immap_nJqfPa3Cpeschema_field: meta_keywords- file_column:+ file_column: meta_keywordsrequired: false- id: immap_98FqgRua4hschema_field: tags- file_column:+ file_column: tagsrequired: false- id: immap_xhoCpeNMWuschema_field: compare_at_price- file_column:+ file_column: compare_at_pricerequired: false- id: immap_vEmzDoNU0Hschema_field: currency- file_column:+ file_column: currencyrequired: false- id: immap_2KY5XM6frIschema_field: width- file_column:+ file_column: widthrequired: false- id: immap_HOVtlDrOmLschema_field: height- file_column:+ file_column: heightrequired: false- id: immap_ed6l8wVqSMschema_field: depth- file_column:+ file_column: depthrequired: false- id: immap_s18jaGonyxschema_field: dimensions_unit- file_column:+ file_column: dimensions_unitrequired: false- id: immap_GZUcnUYI5Aschema_field: weight- file_column:+ file_column: weightrequired: false- id: immap_ROeNhrwyV9schema_field: weight_unit- file_column:+ file_column: weight_unitrequired: false- id: immap_L3pHOn63Vwschema_field: available_on- file_column:+ file_column: available_onrequired: false- id: immap_PQNMcnNFWwschema_field: discontinue_on- file_column:+ file_column: discontinue_onrequired: false- id: immap_C9SrJgpzQ4schema_field: track_inventory- file_column:+ file_column: track_inventoryrequired: false- id: immap_YHETxCGlb0schema_field: inventory_count- file_column:+ file_column: inventory_countrequired: false- id: immap_5OQZnCRf8Jschema_field: inventory_backorderable- file_column:+ file_column: inventory_backorderablerequired: false- id: immap_F0GX8NaP3Yschema_field: tax_category- file_column:+ file_column: tax_categoryrequired: false- id: immap_kOKT9MVfb0schema_field: shipping_category@@ -20368,110 +8612,7346 @@ paths:required: false- id: immap_3uWpPTcf5Wschema_field: image1_src- file_column:+ file_column: image1_srcrequired: false- id: immap_D6Psx31WaTschema_field: image2_src- file_column:+ file_column: image2_srcrequired: false- id: immap_msx3nOJap6schema_field: image3_src- file_column:+ file_column: image3_srcrequired: false- id: immap_5CQZnCRf8Jschema_field: option1_name- file_column:+ file_column: option1_namerequired: false- id: immap_M2nyloHRUQschema_field: option1_value- file_column:+ file_column: option1_valuerequired: false- id: immap_prklVeMgbnschema_field: option2_name- file_column:+ file_column: option2_namerequired: false- id: immap_so8jaGonyxschema_field: option2_value- file_column:+ file_column: option2_valuerequired: false- id: immap_rsClYtECFIschema_field: option3_name- file_column:+ file_column: option3_namerequired: false- id: immap_8DR0I7fEbwschema_field: option3_value- file_column:+ file_column: option3_valuerequired: false- id: immap_aAtNvLSUArschema_field: category1- file_column:+ file_column: category1+ required: false+ - id: immap_QiA48cIW7A+ schema_field: category2+ file_column: category2+ required: false+ - id: immap_QDA48cIW7A+ schema_field: category3+ file_column: category3+ required: false+ 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+ content:+ application/json:+ example:+ id: imp_gbHJdmfrXB+ number: IM760090924+ type: Spree::Imports::Products+ rows_count: 1+ created_at: '2026-07-21T16:18:47.356Z'+ updated_at: '2026-07-21T16:18:47.383Z'+ status: processing+ owner_type: Spree::Store+ owner_id: store_UkLWZg9DAJ+ user_id: admin_UkLWZg9DAJ+ processing_errors:+ preferred_delimiter: ","+ original_filename: products_import.csv+ original_byte_size: 3612+ 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: shipping_category+ label: Shipping Category+ 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 Valuerequired: false- - id: immap_QiA48cIW7A- schema_field: category2- file_column:+ - name: category1+ label: Category 1required: false- - id: immap_QDA48cIW7A- schema_field: category3- file_column:+ - name: category2+ label: Category 2+ required: false+ - name: category3+ label: Category 3required: false+ csv_headers: []+ sample_row: {}+ mappings: []+ "/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+ content:+ application/json:+ example:+ data:+ - id: imrow_gbHJdmfrXB+ row_number: 2+ status: failed+ validation_errors: boom+ item_type:+ created_at: '2026-07-21T16:18:47.666Z'+ updated_at: '2026-07-21T16:18:47.666Z'+ import_id: imp_UkLWZg9DAJ+ item_id:+ data:+ slug: test-product+ name: Test Product+ price: '10.00'+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ "/api/v3/admin/markets":+ get:+ summary: List markets+ tags:+ - 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: EU+ currency: USD+ default_locale: en+ tax_inclusive: false+ default: false+ country_isos:+ - DE+ supported_locales:+ - en+ created_at: '2026-07-21T16:18:49.326Z'+ updated_at: '2026-07-21T16:18:49.326Z'+ 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/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_isos` 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_isos: ['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_isos":["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:+ example:+ id: mkt_gbHJdmfrXB+ name: France only+ currency: EUR+ default_locale: fr+ tax_inclusive: true+ default: false+ country_isos:+ - FR+ supported_locales:+ - en+ - fr+ created_at: '2026-07-21T16:18:49.919Z'+ updated_at: '2026-07-21T16:18:49.919Z'+ schema:+ "$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+ 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_isos:+ 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_isos+ "/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:+ example:+ id: mkt_UkLWZg9DAJ+ name: EU+ currency: USD+ default_locale: en+ tax_inclusive: false+ default: false+ country_isos:+ - DE+ supported_locales:+ - en+ created_at: '2026-07-21T16:18:50.259Z'+ updated_at: '2026-07-21T16:18:50.259Z'+ schema:+ "$ref": "#/components/schemas/Market"+ '404':+ description: market not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Market not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update a market+ tags:+ - Markets+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Updates an existing market. Pass `country_isos` 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_isos` 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_isos: ['DE', 'FR'],+ })+ - lang: bash+ label: Spree CLI+ source: spree api patch /markets/{id} -d '{"name":"European Union","tax_inclusive":true,"country_isos":["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:+ example:+ id: mkt_UkLWZg9DAJ+ name: European Union+ currency: USD+ default_locale: en+ tax_inclusive: true+ default: false+ country_isos:+ - DE+ supported_locales:+ - en+ created_at: '2026-07-21T16:18:50.882Z'+ updated_at: '2026-07-21T16:18:51.171Z'+ 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+ 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_isos:+ 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+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Market cannot be deleted+ "/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:+ example:+ data:+ - id: opt_UkLWZg9DAJ+ name: foo-size-1+ label: Size+ position: 1+ kind: dropdown+ metadata: {}+ filterable: true+ created_at: '2026-07-21T16:18:52.753Z'+ updated_at: '2026-07-21T16:18:52.753Z'+ 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 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:+ example:+ id: opt_gbHJdmfrXB+ name: material+ label: Material+ position: 2+ kind: dropdown+ metadata: {}+ filterable: true+ created_at: '2026-07-21T16:18:53.358Z'+ updated_at: '2026-07-21T16:18:53.358Z'+ schema:+ "$ref": "#/components/schemas/OptionType"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Name can't be blank and Presentation can't be blank+ details:+ name:+ - can't be blank+ presentation:+ - can't be blank+ 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:+ example:+ id: opt_UkLWZg9DAJ+ name: foo-size-5+ label: Size+ position: 1+ kind: dropdown+ metadata: {}+ filterable: true+ created_at: '2026-07-21T16:18:53.836Z'+ updated_at: '2026-07-21T16:18:53.836Z'+ schema:+ "$ref": "#/components/schemas/OptionType"+ '404':+ description: option type not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Option type not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update an option type+ tags:+ - 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:+ example:+ id: opt_UkLWZg9DAJ+ name: foo-size-7+ label: Updated Label+ position: 1+ kind: dropdown+ metadata: {}+ filterable: true+ created_at: '2026-07-21T16:18:54.450Z'+ updated_at: '2026-07-21T16:18:54.741Z'+ schema:+ "$ref": "#/components/schemas/OptionType"+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Presentation can't be blank+ details:+ presentation:+ - can't be blank+ 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}/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.++ **Required scope:** `write_gift_cards` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.giftCards.apply('or_UkLWZg9DAJ', {+ code: 'GIFT-XXXX-YYYY',+ })+ - lang: bash+ label: Spree CLI+ source: spree api post /orders/{order_id}/gift_cards -d '{"code":"GIFT-XXXX-YYYY"}'+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '201':+ description: gift card applied+ content:+ application/json:+ example:+ id: gc_UkLWZg9DAJ+ code: 4A0046AC6D4B7F99+ 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-07-21T16:19:04.847Z'+ updated_at: '2026-07-21T16:19:05.235Z'+ customer_id:+ created_by_id:+ requestBody:+ content:+ application/json:+ schema:+ type: object+ required:+ - code+ properties:+ code:+ type: string+ description: Gift card code+ example: GIFT-XXXX-YYYY+ "/api/v3/admin/orders/{order_id}/gift_cards/{id}":+ delete:+ summary: Remove a gift card from an order+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Removes the gift card from the order.++ **Required scope:** `write_gift_cards` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.giftCards.remove('or_UkLWZg9DAJ', 'gc_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api delete /orders/{order_id}/gift_cards/{id}+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Gift card ID+ schema:+ type: string+ responses:+ '204':+ description: gift card removed+ "/api/v3/admin/orders/{order_id}/items":+ get:+ summary: List order items+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns all line items for an 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: items } = await client.orders.items.list('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api get /orders/{order_id}/items+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: 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:+ example:+ data:+ - id: li_UkLWZg9DAJ+ variant_id: variant_gbHJdmfrXB+ preorder: false+ preorder_ships_at:+ quantity: 2+ currency: USD+ name: Product 175966+ slug: product-175966+ 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-1+ label: S+ position: 1+ color_code:+ option_type_name: foo-size-10+ option_type_label: Size+ image_url:+ metadata: {}+ created_at: '2026-07-21T16:19:05.979Z'+ updated_at: '2026-07-21T16:19:05.979Z'+ digital_links: []+ metadata: {}+ created_at: '2026-07-21T16:19:06.268Z'+ updated_at: '2026-07-21T16:19:06.268Z'+ cost_price: '17.0'+ tax_category_id: taxcat_UkLWZg9DAJ+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ post:+ summary: Add an item+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Adds a new line item to the order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const item = await client.orders.items.create('or_UkLWZg9DAJ', {+ variant_id: 'variant_k5nR8xLq',+ quantity: 2,+ })+ - lang: bash+ label: Spree CLI+ source: spree api post /orders/{order_id}/items -d '{"variant_id":"variant_k5nR8xLq","quantity":2}'+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '201':+ description: item added+ content:+ application/json:+ example:+ id: li_gbHJdmfrXB+ variant_id: variant_VqXmZF31wY+ preorder: false+ preorder_ships_at:+ quantity: 3+ currency: USD+ name: Product 195000+ slug: product-195000+ 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-3+ label: S+ position: 1+ color_code:+ option_type_name: foo-size-12+ option_type_label: Size+ image_url:+ metadata: {}+ created_at: '2026-07-21T16:19:07.227Z'+ updated_at: '2026-07-21T16:19:07.227Z'+ digital_links: []+ metadata: {}+ created_at: '2026-07-21T16:19:07.263Z'+ updated_at: '2026-07-21T16:19:07.263Z'+ 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: Show an item+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns details of a specific line item.++ **Required scope:** `read_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ 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}+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: 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:+ example:+ id: li_UkLWZg9DAJ+ variant_id: variant_gbHJdmfrXB+ preorder: false+ preorder_ships_at:+ quantity: 2+ currency: USD+ name: Product 205422+ slug: product-205422+ 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-4+ label: S+ position: 1+ color_code:+ option_type_name: foo-size-13+ option_type_label: Size+ image_url:+ metadata: {}+ created_at: '2026-07-21T16:19:07.368Z'+ updated_at: '2026-07-21T16:19:07.368Z'+ digital_links: []+ metadata: {}+ created_at: '2026-07-21T16:19:07.675Z'+ updated_at: '2026-07-21T16:19:07.675Z'+ cost_price: '17.0'+ tax_category_id: taxcat_UkLWZg9DAJ+ patch:+ summary: Update an item+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Updates an order item quantity or metadata.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ 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}'+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: 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:+ example:+ id: li_UkLWZg9DAJ+ variant_id: variant_gbHJdmfrXB+ preorder: false+ preorder_ships_at:+ quantity: 5+ currency: USD+ name: Product 216417+ slug: product-216417+ 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-5+ label: S+ position: 1+ color_code:+ option_type_name: foo-size-14+ option_type_label: Size+ image_url:+ metadata: {}+ created_at: '2026-07-21T16:19:08.068Z'+ updated_at: '2026-07-21T16:19:08.068Z'+ digital_links: []+ metadata: {}+ created_at: '2026-07-21T16:19:08.364Z'+ updated_at: '2026-07-21T16:19:08.801Z'+ cost_price: '17.0'+ tax_category_id: taxcat_UkLWZg9DAJ+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ quantity:+ type: integer+ delete:+ summary: Remove an item+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Removes an item from the order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ await client.orders.items.delete('or_UkLWZg9DAJ', 'li_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api delete /orders/{order_id}/items/{id}+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ - name: id+ in: path+ required: true+ description: Item ID+ schema:+ type: string+ responses:+ '204':+ description: line item removed+ "/api/v3/admin/orders/{order_id}/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.++ **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 order = await client.orders.storeCredits.apply('or_UkLWZg9DAJ', {+ amount: '25.00',+ })+ - lang: bash+ label: Spree CLI+ source: spree api post /orders/{order_id}/store_credits -d '{"amount":"25.00"}'+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '201':+ description: store credit applied+ content:+ application/json:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R883152615+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 1+ 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"+ store_credit_total: '50.0'+ display_store_credit_total: "-$50.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at:+ approved_at:+ created_at: '2026-07-21T16:19:16.412Z'+ updated_at: '2026-07-21T16:19:16.477Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id:+ created_by_id:+ customer_id: cus_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+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Removes any applied store credit from the order.++ **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.orders.storeCredits.remove('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api delete /orders/{order_id}/store_credits+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ 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.++ **Required scope:** `read_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: orders, meta } = await client.orders.list({+ status_eq: 'complete',+ completed_at_gt: '2026-01-01',+ sort: '-completed_at',+ limit: 25,+ })+ - lang: bash+ label: Spree CLI+ source: spree api get /orders -d '{"status_eq":"complete","completed_at_gt":"2026-01-01","sort":"-completed_at","limit":25}'+ parameters:+ - name: x-spree-api-key+ in: header+ 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:+ example:+ data:+ - id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R592496422+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 0+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at:+ approved_at:+ created_at: '2026-07-21T16:19:18.275Z'+ updated_at: '2026-07-21T16:19:18.275Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id:+ created_by_id:+ customer_id: cus_UkLWZg9DAJ+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ '401':+ description: unauthorized+ content:+ application/json:+ example:+ error:+ code: authentication_required+ message: Authentication required+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ post:+ summary: Create a draft order+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ 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.',+ internal_note: 'VIP customer — handle with care.',+ 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_iso: 'US',+ state_abbr: '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_iso: 'US',+ state_abbr: 'NY',+ phone: '+1 212 555 1234',+ },+ // billing_address_id: 'addr_UkLWZg9DAJ',++ // Optional. Invalid codes are non-fatal — the order is created either way.+ coupon_code: 'WELCOME10',+ })+ - lang: bash+ label: Spree CLI+ source: spree api post /orders -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":"VIP customer — handle with care.","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_iso":"US","state_abbr":"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_iso":"US","state_abbr":"NY","phone":"+1+ 212 555 1234"},"coupon_code":"WELCOME10"}'+ description: |-+ Creates a new draft order in one shot. Customer, items, addresses, currency,+ market, channel, locale, notes, metadata, and a coupon code can all be+ provided inline.++ Setting `preferred_stock_location_id` pins the order's preferred fulfillment+ location — Order Routing's built-in `PreferredLocation` rule consumes it+ when picking which stock location ships each shipment.++ Invalid coupon codes are non-fatal — the order is created and the failure+ is reported on the service result (not in the API response body for now).+++ **Required scope:** `write_orders` (for API-key authentication).+ parameters:+ - name: x-spree-api-key+ in: header+ 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:+ example:+ id: or_gbHJdmfrXB+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R840671923+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 0+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at:+ approved_at:+ created_at: '2026-07-21T16:19:20.059Z'+ updated_at: '2026-07-21T16:19:20.064Z'+ preferred_stock_location_id: sloc_UkLWZg9DAJ+ tags: []+ internal_note:+ approver_id:+ canceler_id:+ created_by_id:+ 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_iso:+ type: string+ state_abbr:+ 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_iso:+ type: string+ state_abbr:+ type: string+ phone:+ type: string+ billing_address_id:+ type: string+ description: Existing customer address ID+ items:+ type: array+ items:+ type: object+ required:+ - variant_id+ - quantity+ properties:+ variant_id:+ type: string+ description: Variant ID+ quantity:+ type: integer+ example: 1+ metadata:+ type: object+ coupon_code:+ type: string+ description: Optional. Applied non-fatally; invalid codes do not+ block creation.+ "/api/v3/admin/orders/{id}":+ get:+ summary: Show an order+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns full order details including admin-only fields.++ **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 order = await client.orders.get('or_UkLWZg9DAJ', {+ expand: ['items', 'fulfillments', 'payments', 'customer'],+ })+ - lang: bash+ label: Spree CLI+ source: spree api get /orders/{id} -d '{"expand":["items","fulfillments","payments","customer"]}'+ parameters:+ - name: x-spree-api-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:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R741865733+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 0+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at:+ approved_at:+ created_at: '2026-07-21T16:19:20.358Z'+ updated_at: '2026-07-21T16:19:20.358Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id:+ created_by_id:+ customer_id: cus_UkLWZg9DAJ+ '404':+ description: order not found+ content:+ application/json:+ example:+ error:+ code: order_not_found+ message: Order not found+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ patch:+ summary: Update an order+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Updates an order. Supports updating email, addresses, special instructions, and line items.++ **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 order = await client.orders.update('or_UkLWZg9DAJ', {+ email: '[email protected]',+ internal_note: 'VIP — gift wrap on next order',+ })+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"VIP+ — gift wrap on next order"}'+ parameters:+ - name: x-spree-api-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:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R240411830+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 0+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at:+ approved_at:+ created_at: '2026-07-21T16:19:21.493Z'+ updated_at: '2026-07-21T16:19:21.792Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id:+ created_by_id:+ customer_id: cus_UkLWZg9DAJ+ requestBody:+ content:+ application/json:+ schema:+ type: object+ properties:+ email:+ type: string+ special_instructions:+ 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.+ ship_address:+ type: object+ properties:+ firstname:+ type: string+ lastname:+ type: string+ address1:+ type: string+ city:+ type: string+ zipcode:+ type: string+ country_iso:+ type: string+ state_abbr:+ type: string+ phone:+ type: string+ bill_address:+ type: object+ properties:+ firstname:+ type: string+ lastname:+ type: string+ address1:+ type: string+ city:+ type: string+ zipcode:+ type: string+ country_iso:+ type: string+ state_abbr:+ type: string+ phone:+ type: string+ items:+ type: array+ items:+ type: object+ required:+ - variant_id+ properties:+ variant_id:+ type: string+ description: Variant ID+ quantity:+ type: integer+ example: 1+ metadata:+ type: object+ delete:+ summary: Delete a draft order+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Deletes a draft order. Completed orders cannot be deleted.++ **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.delete('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api delete /orders/{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: 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.++ Set `notify_customer: true` to send the order confirmation email.+++ **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 order = await client.orders.complete('or_UkLWZg9DAJ', {+ notify_customer: true,+ })+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{id}/complete -d '{"notify_customer":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: id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '200':+ description: order completed+ content:+ application/json:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R220508188+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 1+ fulfillment_status: ready+ payment_status: paid+ completed_at: '2026-07-21T16:19:22.723Z'+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ status: draft+ last_ip_address:+ considered_risky: false+ confirmation_delivered: false+ store_owner_notification_delivered:+ payment_total: '110.0'+ display_payment_total: "$110.00"+ metadata: {}+ canceled_at:+ approved_at:+ created_at: '2026-07-21T16:19:22.666Z'+ updated_at: '2026-07-21T16:19:22.748Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id:+ created_by_id:+ customer_id: cus_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+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Cancels a completed order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.cancel('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{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: id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '200':+ description: order canceled+ content:+ application/json:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R330548825+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 1+ fulfillment_status: canceled+ payment_status: void+ completed_at: '2026-07-21T16:19:24.007Z'+ 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: "-0.0"+ display_amount_due: "$0.00"+ delivery_total: '10.0'+ display_delivery_total: "$10.00"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at: '2026-07-21T16:19:24.315Z'+ approved_at:+ created_at: '2026-07-21T16:19:23.948Z'+ updated_at: '2026-07-21T16:19:24.379Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id: admin_UkLWZg9DAJ+ created_by_id:+ customer_id: cus_UkLWZg9DAJ+ "/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).++ **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 order = await client.orders.approve('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{id}/approve -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: id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '200':+ description: order approved+ content:+ application/json:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R896664199+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 1+ fulfillment_status:+ payment_status:+ completed_at: '2026-07-21T16:19:24.745Z'+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at:+ approved_at: '2026-07-21T16:19:25.034Z'+ created_at: '2026-07-21T16:19:24.692Z'+ updated_at: '2026-07-21T16:19:24.744Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id: admin_UkLWZg9DAJ+ canceler_id:+ created_by_id:+ customer_id: cus_UkLWZg9DAJ+ "/api/v3/admin/orders/{id}/resume":+ patch:+ summary: Resume a canceled order+ tags:+ - Orders+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Resumes a previously canceled order.++ **Required scope:** `write_orders` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const order = await client.orders.resume('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{id}/resume -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: id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '200':+ description: order resumed+ content:+ application/json:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R724643208+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 1+ fulfillment_status: canceled+ payment_status: void+ completed_at: '2026-07-21T16:19:25.412Z'+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at: '2026-07-21T16:19:25.710Z'+ approved_at:+ created_at: '2026-07-21T16:19:25.324Z'+ updated_at: '2026-07-21T16:19:25.810Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id: admin_UkLWZg9DAJ+ created_by_id:+ customer_id: cus_UkLWZg9DAJ+ "/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.++ **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.resendConfirmation('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api post /orders/{id}/resend_confirmation -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: id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ responses:+ '200':+ description: confirmation resent+ content:+ application/json:+ example:+ id: or_UkLWZg9DAJ+ market_id:+ channel_id: ch_UkLWZg9DAJ+ number: R511935916+ email: [email protected]+ customer_note:+ currency: USD+ locale: en+ total_quantity: 1+ fulfillment_status:+ payment_status:+ completed_at: '2026-07-21T16:19:26.159Z'+ 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"+ store_credit_total: '0.0'+ display_store_credit_total: "$0.00"+ covered_by_store_credit: false+ gift_card:+ market:+ 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: {}+ canceled_at:+ approved_at:+ created_at: '2026-07-21T16:19:26.101Z'+ updated_at: '2026-07-21T16:19:26.159Z'+ preferred_stock_location_id:+ tags: []+ internal_note:+ approver_id:+ canceler_id:+ created_by_id:+ customer_id: cus_UkLWZg9DAJ+ "/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.++ **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: paymentMethods } = await client.paymentMethods.list()+ - lang: bash+ label: Spree CLI+ source: spree api get /payment_methods+ 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:+ example:+ data:+ - id: pm_UkLWZg9DAJ+ name: Check+ description:+ type: check+ session_required: false+ source_required: false+ metadata: {}+ active: true+ auto_capture:+ storefront_visible: true+ position: 1+ created_at: '2026-07-21T16:19:27.618Z'+ updated_at: '2026-07-21T16:19:27.618Z'+ 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+ 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.++ **Required scope:** `read_settings` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: types } = await client.paymentMethods.types()+ - lang: bash+ label: Spree CLI+ source: spree api get /payment_methods/types+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: provider types found+ content:+ application/json:+ example:+ data:+ - type: bogus+ label: Bogus+ description:+ preference_schema:+ - key: dummy_secret_key+ type: password+ default:+ - key: dummy_key+ type: string+ default: PUBLICKEY123+ - type: custom_payment_source_method+ label: Custom Payment Source Method+ description:+ preference_schema: []+ "/api/v3/admin/payment_methods/{id}":+ get:+ summary: Show a payment method+ tags:+ - Payment Methods+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns a payment method by ID.++ **Required scope:** `read_settings` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const paymentMethod = await client.paymentMethods.get('pm_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api get /payment_methods/{id}+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ - name: id+ in: path+ required: true+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand. Use dot notation for+ nested expand (max 4 levels).+ schema:+ type: string+ - name: fields+ in: query+ required: false+ description: Comma-separated list of fields to include (e.g., name,type,active).+ id is always included.+ schema:+ type: string+ responses:+ '200':+ description: payment method found+ content:+ application/json:+ example:+ id: pm_UkLWZg9DAJ+ name: Check+ description:+ type: check+ session_required: false+ source_required: false+ metadata: {}+ active: true+ auto_capture:+ storefront_visible: true+ position: 1+ created_at: '2026-07-21T16:19:28.255Z'+ updated_at: '2026-07-21T16:19:28.255Z'+ preferences: {}+ preference_schema: []+ "/api/v3/admin/orders/{order_id}/payments":+ get:+ summary: List payments+ tags:+ - Payments+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns all payments for an order.++ **Required scope:** `read_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: payments } = await client.orders.payments.list('or_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api get /orders/{order_id}/payments+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authentication+ schema:+ type: string+ - name: order_id+ in: path+ required: true+ description: Order ID+ schema:+ type: string+ - name: expand+ in: query+ required: false+ description: Comma-separated associations to expand (e.g., payment_method,+ source). Use dot notation for nested expand (max 4 levels).+ 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:+ example:+ data:+ - id: py_UkLWZg9DAJ+ payment_method_id: pm_UkLWZg9DAJ+ response_code: BGS-d5969bc1543f+ number: PM7RYHXU+ amount: '110.0'+ display_amount: "$110.00"+ status: completed+ 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-07-21T16:19:09.909Z'+ updated_at: '2026-07-21T16:19:09.915Z'+ metadata: {}+ avs_response:+ cvv_response_code:+ cvv_response_message:+ created_at: '2026-07-21T16:19:09.913Z'+ updated_at: '2026-07-21T16:19:09.913Z'+ captured_amount: '0.0'+ order_id: or_UkLWZg9DAJ+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ post:+ summary: Create a payment+ tags:+ - Payments+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Creates a new payment for the order.++ **Required scope:** `write_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ 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"}'+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ 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:+ example:+ id: py_gbHJdmfrXB+ payment_method_id: pm_EfhxLZ9ck8+ response_code:+ number: PLPM9MJE+ amount: '110.0'+ display_amount: "$110.00"+ status: checkout+ source_type:+ source_id:+ source:+ metadata: {}+ avs_response:+ cvv_response_code:+ cvv_response_message:+ created_at: '2026-07-21T16:19:11.479Z'+ updated_at: '2026-07-21T16:19:11.479Z'+ captured_amount: '0.0'+ order_id: or_gbHJdmfrXB+ requestBody:+ content:+ application/json:+ schema:+ type: object+ required:+ - payment_method_id+ properties:+ payment_method_id:+ type: string+ description: Payment method ID+ amount:+ type: string+ example: '99.99'+ source_id:+ type: string+ description: Payment source ID+ "/api/v3/admin/orders/{order_id}/payments/{id}":+ get:+ summary: Show a payment+ tags:+ - Payments+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns details of a specific payment.++ **Required scope:** `read_payments` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ 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}+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: 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:+ example:+ id: py_UkLWZg9DAJ+ payment_method_id: pm_UkLWZg9DAJ+ response_code: BGS-919cc01d439a+ number: P716LS9V+ amount: '110.0'+ display_amount: "$110.00"+ status: completed+ 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-07-21T16:19:11.908Z'+ updated_at: '2026-07-21T16:19:11.911Z'+ metadata: {}+ avs_response:+ cvv_response_code:+ cvv_response_message:+ created_at: '2026-07-21T16:19:11.910Z'+ updated_at: '2026-07-21T16:19:11.910Z'+ captured_amount: '0.0'+ order_id: or_UkLWZg9DAJ+ "/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.++ **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',+ })++ const payment = await client.orders.payments.capture('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{order_id}/payments/{id}/capture -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: Payment ID+ schema:+ type: string+ responses:+ '200':+ description: payment captured+ content:+ application/json:+ example:+ id: py_UkLWZg9DAJ+ payment_method_id: pm_UkLWZg9DAJ+ response_code: BGS-420b21550686+ number: P312IK5O+ amount: '110.0'+ display_amount: "$110.00"+ status: completed+ 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-07-21T16:19:12.722Z'+ updated_at: '2026-07-21T16:19:12.726Z'+ metadata: {}+ avs_response:+ cvv_response_code:+ cvv_response_message:+ created_at: '2026-07-21T16:19:12.724Z'+ updated_at: '2026-07-21T16:19:13.064Z'+ captured_amount: '110.0'+ order_id: or_UkLWZg9DAJ+ '422':+ description: capture failed+ content:+ application/json:+ example:+ error:+ code: processing_error+ message: 'Bogus Gateway: Forced failure'+ schema:+ "$ref": "#/components/schemas/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.++ **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',+ })++ const payment = await client.orders.payments.void('or_UkLWZg9DAJ', 'pay_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api patch /orders/{order_id}/payments/{id}/void -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: Payment ID+ schema:+ type: string+ responses:+ '200':+ description: payment voided+ content:+ application/json:+ example:+ id: py_UkLWZg9DAJ+ payment_method_id: pm_UkLWZg9DAJ+ response_code: void-BGS-ae858b14e194+ number: POEU9JIB+ amount: '110.0'+ display_amount: "$110.00"+ status: void+ 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-07-21T16:19:14.291Z'+ updated_at: '2026-07-21T16:19:14.296Z'+ metadata: {}+ avs_response:+ cvv_response_code:+ cvv_response_message:+ created_at: '2026-07-21T16:19:14.294Z'+ updated_at: '2026-07-21T16:19:14.644Z'+ captured_amount: '0.0'+ order_id: or_UkLWZg9DAJ+ "/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.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: priceLists } = await client.priceLists.list()+ - lang: bash+ label: Spree CLI+ source: spree api get /price_lists+ parameters:+ - name: x-spree-api-key+ in: header+ 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:+ example:+ data:+ - id: pl_UkLWZg9DAJ+ name: Wholesale+ description:+ status: draft+ position: 1+ match_policy: all+ starts_at:+ ends_at:+ deleted_at:+ created_at: '2026-07-21T16:19:28.557Z'+ updated_at: '2026-07-21T16:19:28.557Z'+ currently_active: false+ products_count: 0+ prices_count: 0+ product_ids: []+ - id: pl_gbHJdmfrXB+ name: Holiday+ description:+ status: draft+ position: 2+ match_policy: all+ starts_at:+ ends_at:+ deleted_at:+ created_at: '2026-07-21T16:19:28.559Z'+ updated_at: '2026-07-21T16:19:28.559Z'+ currently_active: false+ products_count: 0+ prices_count: 0+ product_ids: []+ 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/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.++ **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',+ })++ // 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)`), so there's no need to+ // pre-declare `product_ids` separately.+ const priceList = await client.priceLists.create({+ name: 'EU wholesale',+ description: 'Tiered pricing for verified B2B customers',+ match_policy: 'all',+ starts_at: '2026-06-01T00:00:00Z',+ ends_at: '2026-09-01T00:00:00Z',+ rules: [+ {+ type: 'customer_group_rule',+ preferences: { customer_group_ids: ['cg_aBc123'] },+ },+ {+ type: 'volume_rule',+ preferences: { min_quantity: 10 },+ },+ ],+ prices: [+ {+ variant_id: 'variant_xY9',+ currency: 'USD',+ amount: '19.99',+ compare_at_amount: '24.99',+ },+ {+ variant_id: 'variant_aB7',+ currency: 'USD',+ amount: '21.99',+ },+ ],+ })+ - lang: bash+ label: Spree CLI+ source: spree api post /price_lists -d '{"name":"EU wholesale","description":"Tiered+ pricing for verified B2B customers","match_policy":"all","starts_at":"2026-06-01T00:00:00Z","ends_at":"2026-09-01T00:00:00Z","rules":[{"type":"customer_group_rule","preferences":{"customer_group_ids":["cg_aBc123"]}},{"type":"volume_rule","preferences":{"min_quantity":10}}],"prices":[{"variant_id":"variant_xY9","currency":"USD","amount":"19.99","compare_at_amount":"24.99"},{"variant_id":"variant_aB7","currency":"USD","amount":"21.99"}]}'+ parameters:+ - name: x-spree-api-key+ in: header+ 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, no product_ids)+ content:+ application/json:+ example:+ id: pl_EfhxLZ9ck8+ name: EU wholesale+ description:+ status: draft+ position: 3+ match_policy: all+ starts_at:+ ends_at:+ deleted_at:+ created_at: '2026-07-21T16:19:29.595Z'+ updated_at: '2026-07-21T16:19:29.597Z'+ currently_active: false+ products_count: 1+ prices_count: 2+ product_ids:+ - prod_UkLWZg9DAJ+ 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+ product_ids:+ type: array+ items:+ type: string+ description: Prefixed product ids to seed the list with.+ example:+ - prod_aBc123+ 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 alternative to `product_ids`: ship+ the exact per-variant prices the list should contain. Each row+ upserts on the unique key `(variant_id, currency, price_list_id)`.+ Mix-and-match with `product_ids` is supported but typically unnecessary+ — `prices` alone tells the server which variants belong to the+ list and what the override amount is.'+ 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+ starts_at:+ ends_at:+ deleted_at:+ created_at: '2026-07-21T16:19:29.908Z'+ updated_at: '2026-07-21T16:19:29.908Z'+ currently_active: false+ products_count: 0+ prices_count: 0+ product_ids: []+ 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+ starts_at:+ ends_at:+ deleted_at:+ created_at: '2026-07-21T16:19:31.534Z'+ updated_at: '2026-07-21T16:19:31.835Z'+ currently_active: false+ products_count: 0+ prices_count: 0+ product_ids: []+ 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+ product_ids:+ type: array+ items:+ type: string+ description: Prefixed product ids — reconciles list membership (adds+ + removes).+ example:+ - prod_aBc123+ 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+ starts_at:+ ends_at:+ deleted_at:+ created_at: '2026-07-21T16:19:32.140Z'+ updated_at: '2026-07-21T16:19:32.425Z'+ currently_active: true+ products_count: 0+ prices_count: 0+ product_ids: []+ 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 1+ description:+ status: inactive+ position: 1+ match_policy: all+ starts_at:+ ends_at:+ deleted_at:+ created_at: '2026-07-21T16:19:32.435Z'+ updated_at: '2026-07-21T16:19:32.716Z'+ currently_active: false+ products_count: 0+ prices_count: 0+ product_ids: []+ 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_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-07-21T16:19:32.768Z'+ updated_at: '2026-07-21T16:19:32.768Z'+ - 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-07-21T16:19:32.772Z'+ updated_at: '2026-07-21T16:19:32.772Z'+ 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/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-07-21T16:19:33.415Z'+ updated_at: '2026-07-21T16:19:33.415Z'+ 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-07-21T16:19:33.476Z'+ updated_at: '2026-07-21T16:19:33.476Z'+ 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-07-21T16:19:34.252Z'+ updated_at: '2026-07-21T16:19:34.541Z'+ 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::Metafields::ShortText+ field_type: short_text+ key: custom.title+ value: wool+ created_at: '2026-07-21T16:19:36.078Z'+ updated_at: '2026-07-21T16:19:36.078Z'+ 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::Metafields::LongText+ field_type: long_text+ key: custom.description+ value: A longer description+ created_at: '2026-07-21T16:19:36.703Z'+ updated_at: '2026-07-21T16:19:36.703Z'+ 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: Metafield definition has already been taken+ details:+ metafield_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::Metafields::ShortText+ field_type: short_text+ key: custom.title+ value: wool+ created_at: '2026-07-21T16:19:37.082Z'+ updated_at: '2026-07-21T16:19:37.082Z'+ 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::Metafields::ShortText+ field_type: short_text+ key: custom.title+ value: cotton+ created_at: '2026-07-21T16:19:37.413Z'+ updated_at: '2026-07-21T16:19:37.709Z'+ 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: Veritatis ad odio fuga earum mollitia dolore nobis. Quae+ dolor animi modi voluptatum ipsum. Dolorem similique doloremque+ odit nulla nobis accusamus voluptatibus. Aspernatur culpa id+ fugit in eum consectetur esse quam. Nisi tenetur occaecati iusto+ autem modi.+ - key: slug+ type: string+ source: espresso-machine+ - key: meta_description+ type: string+ source:+ - key: meta_title+ type: string+ source:+ default_locale: en+ supported_locales:+ - de+ - en+ - fr+ "/api/v3/admin/products":+ get:+ summary: List products+ tags:+ - Products+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns a paginated list of products for the current store.++ **Required scope:** `read_products` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const { data: products } = await client.products.list({+ 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 627176+ slug: product-627176+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on:+ preorder_ships_at:+ purchasable: true+ preorder: false+ in_stock: false+ backorderable: true+ available: true+ description: Quibusdam ut distinctio quo voluptates quaerat. Ratione+ sed temporibus dolorem alias necessitatibus. Aperiam facere molestias+ eius occaecati repellendus excepturi. Enim reprehenderit fuga+ esse magni ab cum. Non eligendi possimus minima dolor incidunt.+ Modi eaque reiciendis quam quas natus. Veniam nihil reprehenderit+ nesciunt esse fuga sunt blanditiis. Velit culpa eveniet omnis+ sunt adipisci. Impedit voluptates quaerat tenetur perspiciatis.+ Ut aut quae necessitatibus voluptate dolorem iusto molestiae.+ Natus ratione saepe ex deserunt. Voluptatibus dignissimos corrupti+ ad nihil occaecati a necessitatibus. Fugit dignissimos qui molestias+ omnis porro. Voluptate doloremque officiis architecto repellendus+ expedita. Ratione veniam occaecati rem cum facere. Neque dicta+ consequatur eaque accusamus culpa voluptatum. Libero magni vel+ provident perspiciatis. Fuga voluptatibus doloremque laborum non.+ description_html: |-+ Quibusdam ut distinctio quo voluptates quaerat. Ratione sed temporibus dolorem alias necessitatibus. Aperiam facere molestias eius occaecati repellendus excepturi. Enim reprehenderit fuga esse magni ab cum.+ Non eligendi possimus minima dolor incidunt. Modi eaque reiciendis quam quas natus. Veniam nihil reprehenderit nesciunt esse fuga sunt blanditiis. Velit culpa eveniet omnis sunt adipisci. Impedit voluptates quaerat tenetur perspiciatis.+ Ut aut quae necessitatibus voluptate dolorem iusto molestiae. Natus ratione saepe ex deserunt. Voluptatibus dignissimos corrupti ad nihil occaecati a necessitatibus. Fugit dignissimos qui molestias omnis porro.+ Voluptate doloremque officiis architecto repellendus expedita. Ratione veniam occaecati rem cum facere. Neque dicta consequatur eaque accusamus culpa voluptatum. Libero magni vel provident perspiciatis. Fuga voluptatibus doloremque laborum non.+ default_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-07-21T16:19:38.407Z'+ updated_at: '2026-07-21T16:19:38.407Z'+ original_price:+ status: active+ metadata: {}+ deleted_at:+ created_at: '2026-07-21T16:19:38.398Z'+ updated_at: '2026-07-21T16:19:38.413Z'+ 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',+ description: 'Soft, organic cotton.',+ 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_items: [{ 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_items: [{ 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":"Soft,+ organic cotton.","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_items":[{"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_items":[{"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+ thumbnail_url:+ tags: []+ price:+ original_price:+ status: draft+ metadata: {}+ deleted_at:+ created_at: '2026-07-21T16:19:39.081Z'+ updated_at: '2026-07-21T16:19:39.082Z'+ 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_items:` (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_items:+ 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 668804+ slug: product-668804+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on:+ preorder_ships_at:+ purchasable: true+ preorder: false+ in_stock: false+ backorderable: true+ available: true+ description: Ducimus facilis id aspernatur libero unde. Magni rem+ excepturi consequuntur odit architecto. Quidem quasi eveniet rerum+ ab. Ipsum corrupti ullam possimus cum fugit neque fuga numquam.+ Esse error labore minima possimus id aliquam velit totam. Cupiditate+ rerum sint culpa repellat. At aspernatur dicta quibusdam molestias+ itaque. Reiciendis sunt repellendus similique ipsum quaerat cum+ nostrum. Asperiores earum illum a nobis totam. Fugit esse nulla+ dolor inventore labore blanditiis tempora. Natus reprehenderit placeat+ iste sed modi at. Similique est at illo dolore facere fugiat nam+ a. Cum deserunt eveniet ad illum suscipit ipsa. Amet consequatur+ aspernatur doloribus distinctio in dolorum modi perferendis.+ description_html: |-+ Ducimus facilis id aspernatur libero unde. Magni rem excepturi consequuntur odit architecto. Quidem quasi eveniet rerum ab.+ Ipsum corrupti ullam possimus cum fugit neque fuga numquam. Esse error labore minima possimus id aliquam velit totam. Cupiditate rerum sint culpa repellat.+ At aspernatur dicta quibusdam molestias itaque. Reiciendis sunt repellendus similique ipsum quaerat cum nostrum. Asperiores earum illum a nobis totam.+ Fugit esse nulla dolor inventore labore blanditiis tempora. Natus reprehenderit placeat iste sed modi at. Similique est at illo dolore facere fugiat nam a. Cum deserunt eveniet ad illum suscipit ipsa. Amet consequatur aspernatur doloribus distinctio in dolorum modi perferendis.+ default_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-07-21T16:19:39.478Z'+ updated_at: '2026-07-21T16:19:39.478Z'+ original_price:+ status: active+ metadata: {}+ deleted_at:+ created_at: '2026-07-21T16:19:39.467Z'+ updated_at: '2026-07-21T16:19:39.486Z'+ 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-686816+ meta_title:+ meta_description:+ meta_keywords:+ variant_count: 0+ available_on:+ preorder_ships_at:+ purchasable: true+ preorder: false+ in_stock: false+ backorderable: true+ available: true+ description: At numquam delectus explicabo laborum. Quo incidunt a+ laborum ex vel impedit doloremque. Voluptatem officiis maxime facilis+ error ipsum hic. Ea ipsum aliquam error sint quisquam incidunt ut.+ Sint quis eum commodi explicabo. Saepe asperiores placeat ullam+ distinctio voluptas doloremque. Ut dignissimos commodi dolore atque+ fugit dolorum eius deserunt. Reiciendis odit consectetur maiores+ earum. Aperiam dolorem iure corporis perspiciatis fuga exercitationem+ vitae quos.+ description_html: |-+ At numquam delectus explicabo laborum. Quo incidunt a laborum ex vel impedit doloremque. Voluptatem officiis maxime facilis error ipsum hic. Ea ipsum aliquam error sint quisquam incidunt ut.+ Sint quis eum commodi explicabo. Saepe asperiores placeat ullam distinctio voluptas doloremque. Ut dignissimos commodi dolore atque fugit dolorum eius deserunt. Reiciendis odit consectetur maiores earum. Aperiam dolorem iure corporis perspiciatis fuga exercitationem vitae quos.+ default_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-07-21T16:19:40.180Z'+ updated_at: '2026-07-21T16:19:40.180Z'+ original_price:+ status: active+ metadata: {}+ deleted_at:+ created_at: '2026-07-21T16:19:40.165Z'+ updated_at: '2026-07-21T16:19:40.494Z'+ 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_items:` (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_items:+ 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+ "/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: unknown import type+ 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 (taxon) 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_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 channelscontent:application/json:example:- error:- code: validation_error- message: Type can't be blank- details:- type:- - can't be blank+ product_count: 1+ channel_count: 1+ removed: 1+ schema:+ type: object+ properties:+ product_count:+ type: integer+ channel_count:+ type: integer+ removed:+ type: integerrequestBody:content:application/json:schema:type: objectrequired:- - type- - attachment+ - ids+ - channel_idsproperties:- type:- type: string- enum:- - Spree::Imports::Products- - Spree::Imports::Customers- - Spree::Imports::ProductTranslations- example: Spree::Imports::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+ 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 productstags:- - Imports+ - Productssecurity:- api_key: []bearer_auth: []description: |-- Returns a CSV header row for the given import type, including the custom field columns available for the model.+ 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'- **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).+ 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-keyin: header@@ -20483,33 +15963,63 @@ paths:required: trueschema:type: string- - name: type- in: query- required: true- description: Registered import type, e.g. Spree::Imports::Products.- schema:- type: stringresponses:'200':- description: CSV template+ description: products deletedcontent:- application/json: {}- text/csv:+ application/json:+ example:+ product_count: 1schema:- type: string- format: binary- "/api/v3/admin/imports/{id}":+ 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}/coupon_codes":+ parameters:+ - name: promotion_id+ in: path+ required: true+ schema:+ type: stringget:- summary: Show an import+ summary: List coupon codes for a promotiontags:- - Imports+ - Promotionssecurity:- 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`.+ 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:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).+ **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_codesparameters:- name: x-spree-api-keyin: header@@ -20521,160 +16031,67 @@ paths:required: trueschema:type: string- - name: id- in: path- required: true- schema:- type: stringresponses:'200':- description: import found+ description: coupon codes foundcontent:application/json:example:- id: imp_UkLWZg9DAJ- number: IM969734710- type: Spree::Imports::Products- rows_count: 0- created_at: '2026-07-20T06:57:05.813Z'- updated_at: '2026-07-20T06:57:05.819Z'- status: pending- owner_type: Spree::Store- owner_id: store_UkLWZg9DAJ- user_id: admin_UkLWZg9DAJ- processing_errors:- preferred_delimiter: ","- original_filename: products_import.csv- original_byte_size: 3612- 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: shipping_category- label: Shipping Category- required: false- - name: image1_src- label: Image 1 URL- required: false- - name: image2_src- label: Image 2 URL- required: false- - name: image3_src- label: Image 3 URL- required: false- - name: option1_name- label: Option 1 Name- required: false- - name: option1_value- label: Option 1 Value- required: false- - name: option2_name- label: Option 2 Name- required: false- - name: option2_value- label: Option 2 Value- required: false- - name: option3_name- label: Option 3 Name- required: false- - name: option3_value- label: Option 3 Value- required: false- - name: category1- label: Category 1- required: false- - name: category2- label: Category 2- required: false- - name: category3- label: Category 3- required: false- csv_headers: []- sample_row: {}- mappings: []- delete:- summary: Delete an import+ data:+ - id: coupon_UkLWZg9DAJ+ code: AAA111+ state: unused+ created_at: '2026-07-21T16:18:20.004Z'+ updated_at: '2026-07-21T16:18:20.004Z'+ promotion_id: promo_UkLWZg9DAJ+ order_id:+ - id: coupon_gbHJdmfrXB+ code: BBB222+ state: unused+ created_at: '2026-07-21T16:18:20.006Z'+ updated_at: '2026-07-21T16:18:20.006Z'+ 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 promotiontags:- - Imports+ - Promotionssecurity:- api_key: []bearer_auth: []- description: |-- Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.+ 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',+ })- **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).+ const { data: actions } = await client.promotions.actions.list('promo_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api get /promotions/{promotion_id}/promotion_actionsparameters:- name: x-spree-api-keyin: header@@ -20686,26 +16103,61 @@ paths:required: trueschema:type: string- - name: id- in: path- required: true- schema:- type: stringresponses:- '204':- description: import deleted- "/api/v3/admin/imports/{id}/download":- get:- summary: Download the originally uploaded file+ '200':+ description: actions found+ content:+ application/json:+ example:+ data:+ - id: pact_UkLWZg9DAJ+ created_at: '2026-07-21T16:19:44.771Z'+ updated_at: '2026-07-21T16:19:44.771Z'+ 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 promotiontags:- - Imports+ - Promotionssecurity:- 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.+ 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:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).+ **Required scope:** `write_promotions` (for API-key authentication).+ x-codeSamples:+ - lang: javascript+ label: Spree Admin SDK+ source: |-+ import { createAdminClient } from '@spree/admin-sdk'++ const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+ })++ const 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-keyin: header@@ -20717,36 +16169,79 @@ paths:required: trueschema:type: string- - name: id- in: path- required: true- schema:- type: stringresponses:- '200':- description: CSV file+ '201':+ description: action createdcontent:- application/json: {}- text/csv:- schema:- type: string- format: binary- "/api/v3/admin/imports/{id}/complete_mapping":- patch:- summary: Complete mapping and start processing+ application/json:+ example:+ id: pact_UkLWZg9DAJ+ created_at: '2026-07-21T16:19:45.352Z'+ updated_at: '2026-07-21T16:19:45.352Z'+ 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 promotiontags:- - Imports+ - Promotionssecurity:- 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.+ 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',+ })- **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).+ 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-keyin: header@@ -20758,331 +16253,5169 @@ paths:required: trueschema:type: string- - name: id- in: path+ 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: headerrequired: trueschema:type: stringresponses:'200':- description: mapping completed, processing queued+ description: rules foundcontent:application/json:example:- id: imp_gbHJdmfrXB- number: IM443644020- type: Spree::Imports::Products- rows_count: 0- created_at: '2026-07-20T06:57:06.726Z'- updated_at: '2026-07-20T06:57:06.795Z'- status: completed_mapping- owner_type: Spree::Store- owner_id: store_UkLWZg9DAJ- user_id: admin_UkLWZg9DAJ- processing_errors:- preferred_delimiter: ","- original_filename: products_import.csv- original_byte_size: 3612- 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+ data:+ - id: prorule_UkLWZg9DAJ+ created_at: '2026-07-21T16:19:45.997Z'+ updated_at: '2026-07-21T16:19:45.997Z'+ type: currency+ promotion_id: promo_UkLWZg9DAJ+ preferences:+ currency: USD+ preference_schema:+ - key: currency+ type: string+ default: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: shipping_category- label: Shipping Category- 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: shipping_category- file_column:- required: false- - id: immap_3uWpPTcf5W- schema_field: image1_src- file_column: image1_src- required: false- - id: immap_D6Psx31WaT- schema_field: image2_src- file_column: image2_src- required: false- - id: immap_msx3nOJap6- schema_field: image3_src- file_column: image3_src- required: false- - id: immap_5CQZnCRf8J- schema_field: option1_name- file_column: option1_name- required: false- - id: immap_M2nyloHRUQ- schema_field: option1_value- file_column: option1_value- required: false- - id: immap_prklVeMgbn- schema_field: option2_name- file_column: option2_name- required: false- - id: immap_so8jaGonyx- schema_field: option2_value- file_column: option2_value- required: false- - id: immap_rsClYtECFI- schema_field: option3_name- file_column: option3_name- required: false- - id: immap_8DR0I7fEbw- schema_field: option3_value- file_column: option3_value- required: false- - id: immap_aAtNvLSUAr- schema_field: category1- file_column: category1- required: false- - id: immap_QiA48cIW7A- schema_field: category2- file_column: category2- required: false- - id: immap_QDA48cIW7A- schema_field: category3- file_column: category3- required: false+ product_ids:+ category_ids:+ customer_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-07-21T16:19:46.565Z'+ updated_at: '2026-07-21T16:19:46.565Z'+ type: currency+ promotion_id: promo_UkLWZg9DAJ+ preferences:+ currency: EUR+ preference_schema:+ - key: currency+ type: string+ default:+ label: Currency+ product_ids:+ category_ids:+ customer_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-07-21T16:19:46.870Z'+ updated_at: '2026-07-21T16:19:47.161Z'+ type: currency+ promotion_id: promo_UkLWZg9DAJ+ preferences:+ currency: GBP+ preference_schema:+ - key: currency+ type: string+ default:+ label: Currency+ product_ids:+ category_ids:+ customer_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-07-21T16:19:47.463Z'+ 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-07-21T16:19:47.463Z'+ updated_at: '2026-07-21T16:19:47.463Z'+ 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-07-21T16:19:48.386Z'+ 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-07-21T16:19:48.386Z'+ updated_at: '2026-07-21T16:19:48.414Z'+ 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-07-21T16:19:48.716Z'+ 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-07-21T16:19:48.716Z'+ updated_at: '2026-07-21T16:19:48.716Z'+ 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-07-21T16:19:49.595Z'+ 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-07-21T16:19:49.595Z'+ updated_at: '2026-07-21T16:19:49.873Z'+ 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_isos+ type: array+ default: []+ - key: country_id+ type: integer+ default:+ - key: country_iso+ 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: match_policy+ type: string+ default: any+ - key: eligible_values+ type: array+ default: []+ - 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-3e14306f0379+ amount: '5.0'+ payment_id: py_UkLWZg9DAJ+ refund_reason_id: rr_UkLWZg9DAJ+ reimbursement_id:+ metadata: {}+ created_at: '2026-07-21T16:19:16.095Z'+ updated_at: '2026-07-21T16:19:16.095Z'+ 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_credit_categories":+ get:+ summary: List store credit categories+ tags:+ - Settings+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns the configured store credit categories. Categories classify+ store credits (e.g., "Goodwill", "Gift Card", "Refund") and surface+ in the admin UI as a dropdown when issuing or editing a store+ credit. Category names matching `Spree::Config[:non_expiring_credit_types]`+ are flagged via `non_expiring: true`.+++ **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: categories } = await client.storeCreditCategories.list()+ - lang: bash+ label: Spree CLI+ source: spree api get /store_credit_categories+ parameters:+ - name: x-spree-api-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: store credit categories found+ content:+ application/json:+ example:+ data:+ - id: sccat_UkLWZg9DAJ+ name: Goodwill+ created_at: '2026-07-21T16:19:53.459Z'+ updated_at: '2026-07-21T16:19:53.459Z'+ non_expiring: false+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ "$ref": "#/components/schemas/StoreCreditCategory"+ 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/store_credit_categories/{id}":+ parameters:+ - name: id+ in: path+ required: true+ description: Store credit category ID+ schema:+ type: string+ get:+ summary: Get a store credit category+ tags:+ - Settings+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns a single store credit category 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 category = await client.storeCreditCategories.get('sccat_UkLWZg9DAJ')+ - lang: bash+ label: Spree CLI+ source: spree api get /store_credit_categories/{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: store credit category found+ content:+ application/json:+ example:+ id: sccat_UkLWZg9DAJ+ name: Goodwill+ created_at: '2026-07-21T16:19:53.767Z'+ updated_at: '2026-07-21T16:19:53.767Z'+ non_expiring: false+ schema:+ "$ref": "#/components/schemas/StoreCreditCategory"+ '404':+ description: store credit category not found+ content:+ application/json:+ example:+ error:+ code: record_not_found+ message: Store credit category not found+ 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.++ **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+ 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_unit_system: imperial+ preferred_storefront_access: public+ preferred_guest_checkout: true+ preferred_order_routing_strategy: Spree::OrderRouting::Strategy::Rules+ created_at: '2026-07-21T16:18:06.722Z'+ updated_at: '2026-07-21T16:19:54.373Z'+ 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+ 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+ 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_unit_system: imperial+ preferred_storefront_access: public+ preferred_guest_checkout: true+ preferred_order_routing_strategy: Spree::OrderRouting::Strategy::Rules+ created_at: '2026-07-21T16:18:06.722Z'+ updated_at: '2026-07-21T16:19:55.059Z'+ 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+ 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::LegacyUser+ "/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: category+ fields:+ - key: name+ type: string+ - key: pretty_name+ type: string+ - key: description+ type: html+ - key: permalink+ type: string+ readable: true+ - resource_type: taxonomy+ fields:+ - key: name+ type: string+ readable: false+ - 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: false+ "/api/v3/admin/translations/batch":+ post:+ summary: Batch upsert translations+ tags:+ - Settings+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.++ **Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).+ parameters:+ - name: x-spree-api-key+ in: header+ required: true+ schema:+ type: string+ - name: Authorization+ in: header+ required: true+ schema:+ type: string+ responses:+ '200':+ description: translations upserted+ content:+ application/json:+ example:+ data:+ - resource_id: opt_UkLWZg9DAJ+ resource_type: option_type+ translations:+ de:+ label: Größe+ translated_field_count: 1+ fr:+ label:+ translated_field_count: 0+ default_locale: en+ supported_locales:+ - de+ - en+ - fr+ - resource_id: optval_UkLWZg9DAJ+ resource_type: option_value+ translations:+ de:+ label: Klein+ translated_field_count: 1+ fr:+ label:+ translated_field_count: 0+ default_locale: en+ supported_locales:+ - de+ - en+ - fr+ '422':+ description: unsupported locale rolls back the whole batch+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: 'Unsupported locale(s): es'+ details:+ translations:+ '0':+ - 'Unsupported locale(s): es'+ requestBody:+ content:+ application/json:+ schema:+ type: object+ required:+ - translations+ properties:+ translations:+ type: array+ items:+ type: object+ required:+ - resource_type+ - resource_id+ - values+ properties:+ resource_type:+ type: string+ description: Translatable resource type token, e.g. `option_type`+ resource_id:+ type: string+ description: Prefixed id of the record+ values:+ type: object+ description: 'Map of locale code to { field: value }'+ additionalProperties:+ type: object+ additionalProperties: true+ "/api/v3/admin/admin_users":+ get:+ summary: List staff+ tags:+ - Staff+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns admin users with at least one role assignment on the current store.++ **Required scope:** `read_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: 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: admin_UkLWZg9DAJ+ email: [email protected]+ first_name: Pamella+ last_name: Witting+ full_name: Pamella Witting+ selected_locale:+ created_at: '2026-07-21T16:18:07.048Z'+ updated_at: '2026-07-21T16:18:07.048Z'+ avatar_url:+ roles:+ - id: role_UkLWZg9DAJ+ name: admin+ 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_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 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: admin_UkLWZg9DAJ+ email: [email protected]+ first_name: Assunta+ last_name: Cartwright+ full_name: Assunta Cartwright+ selected_locale:+ created_at: '2026-07-21T16:18:07.394Z'+ updated_at: '2026-07-21T16:18:07.394Z'+ avatar_url:+ roles:+ - id: role_UkLWZg9DAJ+ name: admin+ 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_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 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: admin_UkLWZg9DAJ+ email: [email protected]+ first_name: Renamed+ last_name: Anderson+ full_name: Renamed Anderson+ selected_locale:+ created_at: '2026-07-21T16:18:07.705Z'+ updated_at: '2026-07-21T16:18:07.728Z'+ avatar_url:+ roles:+ - id: role_UkLWZg9DAJ+ name: admin+ 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_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.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_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: 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-07-21T16:18:48.027Z'+ updated_at: '2026-07-21T16:18:48.027Z'+ expires_at: '2026-08-04T16:18:48.024Z'+ role_id: role_UkLWZg9DAJ+ role_name: admin+ inviter_email: [email protected]+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=zoVQo1FnsKDouctsTgq3BtVq"+ 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_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 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-07-21T16:18:48.333Z'+ updated_at: '2026-07-21T16:18:48.333Z'+ expires_at: '2026-08-04T16:18:48.329Z'+ role_id: role_UkLWZg9DAJ+ role_name: admin+ inviter_email: [email protected]+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=x7dwYrZifC2piDGmNs4jTJdq"+ 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_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.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_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 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-07-21T16:18:48.938Z'+ updated_at: '2026-07-21T16:18:48.938Z'+ expires_at: '2026-08-04T16:18:48.934Z'+ role_id: role_UkLWZg9DAJ+ role_name: admin+ inviter_email: [email protected]+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=NHJUiXXtQVcwZf4XRrU92juk"+ invitee_exists: false+ store:+ id: store_UkLWZg9DAJ+ name: Spree Test Store+ "/api/v3/admin/roles":+ get:+ summary: List roles+ tags:+ - Staff+ security:+ - api_key: []+ bearer_auth: []+ description: |-+ Returns the roles available for staff role pickers. Roles are global, not per-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: 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+ created_at: '2026-07-21T16:19:50.760Z'+ updated_at: '2026-07-21T16:19:50.760Z'+ meta:+ page: 1+ limit: 25+ count: 1+ pages: 1+ from: 1+ to: 1+ in: 1+ previous:+ next:+ "/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+ state_abbr: STATE_ABBR_50+ name: Brooklyn warehouse+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_iso: US+ country_name: United States of America+ state_text: STATE_ABBR_50+ 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+ pickup_ready_in_minutes:+ pickup_instructions:+ created_at: '2026-07-21T16:19:51.065Z'+ updated_at: '2026-07-21T16:19:51.065Z'+ 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_iso: 'US',+ state_abbr: '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_iso":"US","state_abbr":"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+ state_abbr:+ name: Manhattan store+ address1:+ city:+ zipcode:+ country_iso:+ country_name:+ state_text:+ 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+ pickup_ready_in_minutes: 30+ pickup_instructions:+ created_at: '2026-07-21T16:19:51.712Z'+ updated_at: '2026-07-21T16:19:51.712Z'+ 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_iso:+ type: string+ nullable: true+ description: ISO-3166 alpha-2 country code (e.g. "US").+ state_abbr:+ 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+ state_abbr: STATE_ABBR_54+ name: Brooklyn warehouse+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_iso: US+ country_name: United States of America+ state_text: STATE_ABBR_54+ 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+ pickup_ready_in_minutes:+ pickup_instructions:+ created_at: '2026-07-21T16:19:52.014Z'+ updated_at: '2026-07-21T16:19:52.014Z'+ 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+ state_abbr: STATE_ABBR_56+ name: Renamed warehouse+ address1: 1600 Pennsylvania Ave NW+ city: Washington+ zipcode: '20500'+ country_iso: US+ country_name: United States of America+ state_text: STATE_ABBR_56+ 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+ pickup_ready_in_minutes: 45+ pickup_instructions:+ created_at: '2026-07-21T16:19:52.587Z'+ updated_at: '2026-07-21T16:19:52.864Z'+ 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_iso:+ type: string+ nullable: true+ state_abbr:+ 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 master 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_items'],+ })+ - lang: bash+ label: Spree CLI+ source: spree api get /products/{product_id}/variants -d '{"expand":["prices","stock_items"]}'+ parameters:+ - name: x-spree-api-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_items, 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-103+ options_text: ''+ 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:+ price:+ id:+ amount:+ amount_in_cents: 0+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$0.00"+ display_compare_at_amount:+ price_list_id:+ original_price:+ option_values: []+ metadata: {}+ position: 1+ cost_price: '17.0'+ cost_currency: USD+ barcode:+ weight_unit: lb+ dimensions_unit:+ backorder_limit:+ deleted_at:+ created_at: '2026-07-21T16:19:57.398Z'+ updated_at: '2026-07-21T16:19:57.407Z'+ preorderable: false+ tax_category_id: taxcat_UkLWZg9DAJ+ available_stock: 0+ reserved_quantity: 0+ total_on_hand: 0+ product_name: Product 841126+ - id: variant_gbHJdmfrXB+ product_id: prod_UkLWZg9DAJ+ sku: SKU-104+ 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: 7.75+ height: 37.54+ width: 46.51+ depth: 4.56+ 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:+ option_values:+ - id: optval_UkLWZg9DAJ+ option_type_id: opt_UkLWZg9DAJ+ name: size-19+ label: S+ position: 1+ color_code:+ option_type_name: foo-size-28+ option_type_label: Size+ image_url:+ metadata: {}+ created_at: '2026-07-21T16:19:57.419Z'+ updated_at: '2026-07-21T16:19:57.419Z'+ metadata: {}+ position: 2+ cost_price: '17.0'+ cost_currency: USD+ barcode:+ weight_unit: lb+ dimensions_unit:+ backorder_limit:+ deleted_at:+ created_at: '2026-07-21T16:19:57.417Z'+ updated_at: '2026-07-21T16:19:57.427Z'+ preorderable: false+ tax_category_id: taxcat_UkLWZg9DAJ+ available_stock: 0+ reserved_quantity: 0+ total_on_hand: 0+ product_name: Product 841126+ 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_items: [{ 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_items":[{"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:+ price:+ id: price_EfhxLZ9ck8+ amount: '24.99'+ amount_in_cents: 2499+ compare_at_amount:+ compare_at_amount_in_cents:+ currency: USD+ display_amount: "$24.99"+ display_compare_at_amount:+ price_list_id:+ original_price:+ 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-07-21T16:19:58.073Z'+ updated_at: '2026-07-21T16:19:58.073Z'+ metadata: {}+ position: 3+ cost_price:+ cost_currency: USD+ barcode:+ weight_unit: lb+ dimensions_unit:+ backorder_limit:+ deleted_at:+ created_at: '2026-07-21T16:19:58.077Z'+ updated_at: '2026-07-21T16:19:58.078Z'+ preorderable: false+ tax_category_id: taxcat_UkLWZg9DAJ+ available_stock: 0+ reserved_quantity: 0+ total_on_hand: 0+ product_name: Product 857805+ '422':+ description: validation error+ content:+ application/json:+ example:+ error:+ code: validation_error+ message: Option value variants can't be blank+ details:+ option_value_variants:+ - can't be blank+ schema:+ "$ref": "#/components/schemas/ErrorResponse"+ requestBody:+ content:+ application/json:+ schema:+ type: object+ required:+ - options+ 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: Required. A variant created here is always non-master,+ so it must declare at least one option pair (e.g. size + color)+ or creation fails with 422. One pair per option type the variant+ 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_items:+ 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_items'],+ })+ - lang: bash+ label: Spree CLI+ source: spree api get /products/{product_id}/variants/{id} -d '{"expand":["prices","stock_items"]}'+ parameters:+ - name: x-spree-api-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_items, 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-110+ 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: 178.95+ height: 48.7+ width: 171.11+ depth: 127.92+ 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:+ option_values:+ - id: optval_UkLWZg9DAJ+ option_type_id: opt_UkLWZg9DAJ+ name: size-22+ label: S+ position: 1+ color_code:+ option_type_name: foo-size-31+ option_type_label: Size+ image_url:+ metadata: {}+ created_at: '2026-07-21T16:19:58.532Z'+ updated_at: '2026-07-21T16:19:58.532Z'+ metadata: {}+ position: 2+ cost_price: '17.0'+ cost_currency: USD+ barcode:+ weight_unit: lb+ dimensions_unit:+ backorder_limit:+ deleted_at:+ created_at: '2026-07-21T16:19:58.530Z'+ updated_at: '2026-07-21T16:19:58.541Z'+ preorderable: false+ tax_category_id: taxcat_UkLWZg9DAJ+ available_stock: 0+ reserved_quantity: 0+ total_on_hand: 0+ product_name: Product 874284+ '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_items: [+ { 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_items":[{"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: 31.4+ height: 153.68+ width: 127.55+ depth: 15.16+ 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:+ option_values:+ - id: optval_UkLWZg9DAJ+ option_type_id: opt_UkLWZg9DAJ+ name: size-24+ label: S+ position: 1+ color_code:+ option_type_name: foo-size-33+ option_type_label: Size+ image_url:+ metadata: {}+ created_at: '2026-07-21T16:19:59.246Z'+ updated_at: '2026-07-21T16:19:59.246Z'+ metadata: {}+ position: 2+ cost_price: '17.0'+ cost_currency: USD+ barcode:+ weight_unit: lb+ dimensions_unit:+ backorder_limit:+ deleted_at:+ created_at: '2026-07-21T16:19:59.243Z'+ updated_at: '2026-07-21T16:19:59.548Z'+ preorderable: false+ tax_category_id: taxcat_UkLWZg9DAJ+ available_stock: 0+ reserved_quantity: 0+ total_on_hand: 0+ product_name: Product 895071+ 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_items:+ 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_gbHJdmfrXB+ event_name: order.created+ event_id:+ response_code: 500+ execution_time: 200+ error_type:+ request_errors:+ response_body:+ success: false+ created_at: '2026-07-21T16:19:59.969Z'+ updated_at: '2026-07-21T16:19:59.969Z'+ delivered_at: '2026-07-21T16:19:59.969Z'+ payload:+ event: order.created+ data:+ id: 1+ webhook_endpoint_id: whe_UkLWZg9DAJ+ webhook_endpoint_url: https://shop.example.com/webhooks+ - 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-07-21T16:19:59.968Z'+ updated_at: '2026-07-21T16:19:59.968Z'+ delivered_at: '2026-07-21T16:19:59.968Z'+ 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-07-21T16:20:00.610Z'+ updated_at: '2026-07-21T16:20:00.610Z'+ delivered_at: '2026-07-21T16:20:00.610Z'+ 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-07-21T16:20:01.655Z'+ updated_at: '2026-07-21T16:20:01.655Z'+ 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-07-21T16:20:01.905Z'+ updated_at: '2026-07-21T16:20:01.905Z'+ 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.completed', '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.completed","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.completed+ disabled_reason:+ created_at: '2026-07-21T16:20:02.925Z'+ updated_at: '2026-07-21T16:20:02.925Z'+ disabled_at:+ secret_key: d52fe30a29ef500158971b0c30f759f900a60df5bed1f239a1d42e4d1366d274+ 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.completed+ - 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-07-21T16:20:03.250Z'+ updated_at: '2026-07-21T16:20:03.250Z'+ 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.completed', 'order.canceled', 'order.paid'],+ })+ - lang: bash+ label: Spree CLI+ source: spree api patch /webhook_endpoints/{id} -d '{"name":"Order pipeline+ (v2)","subscriptions":["order.completed","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-07-21T16:20:03.856Z'+ updated_at: '2026-07-21T16:20:04.134Z'+ 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: objectproperties:- mappings:+ name:+ type: string+ url:+ type: string+ active:+ type: boolean+ subscriptions: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+ type: string+ delete:+ summary: Delete a webhook endpointtags:- - Imports+ - Webhookssecurity:- 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.+ Soft-deletes the endpoint and stops future deliveries.- **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).+ **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-keyin: header@@ -21092,163 +21425,126 @@ paths:- name: Authorizationin: headerrequired: true- schema:- type: string- - name: id- in: path- required: true+ description: Bearer token for admin authenticationschema:type: stringresponses:- '200':- description: retry queued- content:- application/json:- example:- id: imp_gbHJdmfrXB- number: IM754753148- type: Spree::Imports::Products- rows_count: 1- created_at: '2026-07-20T06:57:07.089Z'- updated_at: '2026-07-20T06:57:07.117Z'- status: processing- owner_type: Spree::Store- owner_id: store_UkLWZg9DAJ- user_id: admin_UkLWZg9DAJ- processing_errors:- preferred_delimiter: ","- original_filename: products_import.csv- original_byte_size: 3612- 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: shipping_category- label: Shipping Category- required: false- - name: image1_src- label: Image 1 URL- required: false- - name: image2_src- label: Image 2 URL- required: false- - name: image3_src- label: Image 3 URL- required: false- - name: option1_name- label: Option 1 Name- required: false- - name: option1_value- label: Option 1 Value- required: false- - name: option2_name- label: Option 2 Name- required: false- - name: option2_value- label: Option 2 Value- required: false- - name: option3_name- label: Option 3 Name- required: false- - name: option3_value- label: Option 3 Value- required: false- - name: category1- label: Category 1- required: false- - name: category2- label: Category 2- required: false- - name: category3- label: Category 3- required: false- csv_headers: []- sample_row: {}- mappings: []- "/api/v3/admin/imports/{import_id}/rows":- get:- summary: List import rows+ '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-07-21T16:20:05.097Z'+ updated_at: '2026-07-21T16:20:05.097Z'+ delivered_at:+ payload:+ id: cde241e0-7df4-4071-896c-7730c21de91e+ name: webhook.test+ created_at: '2026-07-21T16:20:05Z'+ data:+ message: This is a test webhook from Spree.+ metadata:+ spree_version: 5.6.0.rc4+ 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 endpointtags:- - Imports+ - Webhookssecurity:- 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`.+ Re-enables an endpoint that was manually or automatically disabled.- **Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).+ **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-keyin: header@@ -21258,49 +21554,121 @@ paths:- name: Authorizationin: headerrequired: true+ description: Bearer token for admin authenticationschema:type: string- - name: import_id- in: path+ 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-07-21T16:20:05.111Z'+ updated_at: '2026-07-21T16:20:05.551Z'+ 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: headerrequired: trueschema:type: string- - name: q[status_eq]- in: query- required: false- description: 'Filter rows by status: pending, processing, completed, failed.'+ - name: Authorization+ in: header+ required: true+ description: Bearer token for admin authenticationschema:type: stringresponses:'200':- description: rows found+ description: webhook endpoint disabledcontent:application/json:example:- data:- - id: imrow_gbHJdmfrXB- row_number: 2- status: failed- validation_errors: boom- item_type:- created_at: '2026-07-20T06:57:07.407Z'- updated_at: '2026-07-20T06:57:07.407Z'- import_id: imp_UkLWZg9DAJ- 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:+ 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-07-21T16:20:05.577Z'+ updated_at: '2026-07-21T16:20:05.920Z'+ disabled_at: '2026-07-21T16:20:05.920Z'+ 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:@@ -21313,8 +21681,12 @@ tags:description: CORS allowlist for storefront and admin client origins- name: API Keysdescription: Secret and publishable API keys+- name: Categories+ description: Hierarchical product categories — tree management, repositioning, and+ product assignments- name: Channels- description: Sales channels and product publication across channels+ description: Sales channels, product publication across channels, and per-channel+ order routing rules- name: Custom Fieldsdescription: Custom field definitions for products, variants, customers, and otherresources@@ -21329,6 +21701,9 @@ tags:description: Order fulfillments — shipments, fulfill, cancel, resume, split- name: Gift Cardsdescription: Gift cards and gift card batches+- name: Imports+ description: Async CSV imports of admin resources, with per-row status and failed-row+ retry- name: Marketsdescription: Markets — geographic groupings of countries used for pricing, tax,and fulfillment rules@@ -21362,47 +21737,6 @@ tags:under a product- name: Webhooksdescription: Webhook endpoints and webhook delivery history-x-tagGroups:-- name: Authentication- tags:- - Authentication-- name: Products & Catalog- tags:- - Products- - Variants- - Option Types- - Custom Fields- - Channels-- name: Pricing- tags:- - Pricing- - Markets-- name: Orders & Fulfillment- tags:- - Orders- - Payments- - Fulfillments- - Refunds-- name: Customers- tags:- - Customers- - Customer Groups-- name: Promotions & Gift Cards- tags:- - Promotions- - Gift Cards-- name: Data- tags:- - Exports-- name: Configuration- tags:- - Settings- - Stock Locations- - Payment Methods- - Staff- - API Keys- - Allowed Origins- - Webhookscomponents:securitySchemes:api_key:@@ -23386,6 +23720,44 @@ components:- created_at- updated_atx-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: trueOrder:type: objectproperties:@@ -24847,6 +25219,8 @@ components:type: stringpreferred_guest_checkout:type: boolean+ preferred_order_routing_strategy:+ type: stringcreated_at:type: stringupdated_at:@@ -24895,6 +25269,7 @@ components:- preferred_unit_system- preferred_storefront_access- preferred_guest_checkout+ - preferred_order_routing_strategy- created_at- updated_at- url@@ -25118,8 +25493,6 @@ components:success:type: booleannullable: true- payload:- type: objectcreated_at:type: stringupdated_at:@@ -25127,6 +25500,8 @@ components:delivered_at:type: stringnullable: true+ payload:+ type: objectwebhook_endpoint_id:type: stringwebhook_endpoint_url:@@ -25141,10 +25516,10 @@ components:- request_errors- response_body- success- - payload- created_at- updated_at- delivered_at+ - payload- webhook_endpoint_id- webhook_endpoint_urlx-typelizer: truediff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yamlindex 1c6057892e..b2f8079c10 100644--- a/docs/api-reference/store.yaml+++ b/docs/api-reference/store.yaml@@ -87,16 +87,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjljMThmNGM2LWRlNWItNDBhNC04NjEwLTk5ZWUyM2Y3NDVmYSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NTM0MzA5fQ.6H3jMthadEPFzcp8JZgrbG3l1r-0FComIp-7sjOkUWI- refresh_token: hmAnPkSZxiVfN5hQSYQm7KYJ+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImFiNzZhNjQzLTY0ZmYtNDJmMy1iYTRjLTcxNzc5NjUwZGVjYyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NjU0NDExfQ.th8X6tMByJ5GFE7rBtUx7BeMQ5F-VWUPMmgkL7Xp8q4+ refresh_token: yc2xFoGugFWxKRnFoGaLmVwFuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Selina- last_name: Kuvalis+ first_name: Candi+ last_name: Schummphone:accepts_email_marketing: false- full_name: Selina Kuvalis+ full_name: Candi Schummavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -194,16 +194,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImVkNDU3MjJkLTk0NWItNGZmMS1hMTBiLTNkMjk2ZTk5MTJmNyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NTM0MzEwfQ.12ZvWYuoHWlnB7gPFDZgWE0Ic9Xqh84ctFGNoOybpas- refresh_token: x7Lhv2Ss9kBMFejKj35jqaQo+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjZiNWNiMGExLWNhN2YtNDI4MC05ZDg1LTE5ODdlZmE2M2JmOSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NjU0NDEyfQ.qOPFDsCKQnXSo1Vd79BFjCQB1iYxgAMw5NbiS2wQC84+ refresh_token: eCPfFnyVYDYwYM6tqrHZz1Rduser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Lydia- last_name: Gaylord+ first_name: Stephanie+ last_name: Reichelphone:accepts_email_marketing: false- full_name: Lydia Gaylord+ full_name: Stephanie Reichelavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -393,16 +393,16 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFiMDZjODc5LWM4N2ItNDczYi1iZDJhLTBkZTFjOGNkZDBkZSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NTM0MzIzfQ.UTyTpU_ECzZ1iHA3QQR2XuGmVS3kQtPo1ePjUUJt0Yw- refresh_token: 1iF2ZJ3x2T8suY5zzimv82Fq+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImEyZTRiZjg1LTk5N2MtNDdkZS1iOGY3LTk3MDk4YzZiYzYyNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NjU0NDI2fQ.5R12jnwlyHXq1P2L46dY3nxPWY5dKfgi2JyLI-qjzxg+ refresh_token: xgGeG4wdBFf9AhhoBbBYtMTiuser:id: cus_UkLWZg9DAJemail: [email protected]- first_name: Teodora- last_name: Zulauf+ first_name: Chasidy+ last_name: Blockphone:accepts_email_marketing: false- full_name: Teodora Zulauf+ full_name: Chasidy Blockavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses: []@@ -804,8 +804,8 @@ paths:example:data:- id: prod_UkLWZg9DAJ- name: Product 1524033- slug: product-1524033+ name: Product 1525934+ slug: product-1525934meta_title:meta_description:meta_keywords:@@ -834,8 +834,8 @@ paths:price_list_id:original_price:- id: prod_gbHJdmfrXB- name: Product 1534332- slug: product-1534332+ name: Product 153345+ slug: product-153345meta_title:meta_description:meta_keywords:@@ -847,16 +847,19 @@ paths:in_stock: falsebackorderable: trueavailable: true- description: Aut adipisci quibusdam accusamus expedita ab. Odit- pariatur quibusdam a nesciunt quod voluptatibus mollitia ad. Modi- eos iste magnam assumenda quam. Tempore similique repellat laudantium- ducimus. Explicabo quos tenetur nobis delectus porro mollitia- ipsam.- description_html: Aut adipisci quibusdam accusamus expedita ab.- Odit pariatur quibusdam a nesciunt quod voluptatibus mollitia- ad. Modi eos iste magnam assumenda quam. Tempore similique repellat- laudantium ducimus. Explicabo quos tenetur nobis delectus porro- mollitia ipsam.+ description: Modi tenetur numquam voluptates ratione eaque voluptatibus+ facere. Facere incidunt beatae laboriosam asperiores praesentium+ vel consequuntur quibusdam. Molestias id ipsam rem alias at ad+ assumenda consequatur. Mollitia natus ducimus facere illo aperiam+ saepe reiciendis. Doloremque modi inventore tenetur nihil. Sit+ provident rerum dignissimos illo iusto voluptate. Exercitationem+ dolor eaque possimus voluptatem nisi eveniet earum dolorem. Dolore+ facere ut eum excepturi cum molestias. Mollitia exercitationem+ minima perferendis dolorem quasi. Ut tenetur aliquam libero molestias+ magni doloremque aliquid dolorem.+ description_html: |-+ Modi tenetur numquam voluptates ratione eaque voluptatibus facere. Facere incidunt beatae laboriosam asperiores praesentium vel consequuntur quibusdam. Molestias id ipsam rem alias at ad assumenda consequatur. Mollitia natus ducimus facere illo aperiam saepe reiciendis. Doloremque modi inventore tenetur nihil.+ Sit provident rerum dignissimos illo iusto voluptate. Exercitationem dolor eaque possimus voluptatem nisi eveniet earum dolorem. Dolore facere ut eum excepturi cum molestias. Mollitia exercitationem minima perferendis dolorem quasi. Ut tenetur aliquam libero molestias magni doloremque aliquid dolorem.default_variant_id: variant_EfhxLZ9ck8thumbnail_url:tags: []@@ -958,8 +961,8 @@ paths:application/json:example:id: prod_UkLWZg9DAJ- name: Product 1803521- slug: product-1803521+ name: Product 180822+ slug: product-180822meta_title:meta_description:meta_keywords:@@ -993,7 +996,7 @@ paths:amount_in_cents: 999currency: USDdisplay_amount: "$9.99"- recorded_at: '2026-07-05T06:59:22Z'+ recorded_at: '2026-07-06T16:22:42Z'schema:"$ref": "#/components/schemas/Product"'404':@@ -1233,9 +1236,9 @@ paths:- id: cart_gbHJdmfrXBmarket_id:channel_id: ch_UkLWZg9DAJ- number: R559934696- token: SWyi6Xnc8s491q9yX38WHHqia95sWuvvTMV- email: [email protected]+ number: R342007989+ token: VS7APqPxHRMsNq5MGjzUnLDqWdnR3pkAWaJ+ email: [email protected]customer_note:currency: USDlocale: en@@ -1279,8 +1282,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 923654- slug: product-923654+ name: Product 921529+ slug: product-921529options_text: ''price: '10.0'display_price: "$10.00"@@ -1305,7 +1308,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H85053120087+ number: H45075660320tracking: U10000tracking_url:cost: '100.0'@@ -1334,7 +1337,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Blythe Beahan+ name: Dewitt Cruickshankaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1405,9 +1408,9 @@ paths:- id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R354829125- token: oEx8WrpxutXH4sfy3QSWxKxLRR6LrkB9Ruu- email: [email protected]+ number: R495129612+ token: Z82RbRQLtzf85HGQSptDokZACx8yh99x8HG+ email: [email protected]customer_note:currency: USDlocale: en@@ -1451,8 +1454,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 91196- slug: product-91196+ name: Product 917362+ slug: product-917362options_text: ''price: '10.0'display_price: "$10.00"@@ -1477,7 +1480,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H73938182983+ number: H07522527247tracking: U10000tracking_url:cost: '100.0'@@ -1506,7 +1509,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Blythe Beahan+ name: Dewitt Cruickshankaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -1650,8 +1653,8 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R257765413- token: SN8FwGqtYYFVTdEo3uNKead8s4i8N8muHz8+ number: R257847599+ token: g5bgjgci2Cd6pSfS7nJDQsV8SED1bvREHkzemail:customer_note:currency: USD@@ -1807,16 +1810,16 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R978497785- token: S2fezdM65stJqJLErtGrDocKgJiv7Jwngty- email: [email protected]+ number: R756323828+ token: xPgVauGASkDehw4w1KFe6diPx4RG4Su6c2f+ email: [email protected]customer_note:currency: USDlocale: entotal_quantity: 0warnings:- code: line_item_removed- message: Product 968179 was removed because it was sold out+ message: Product 964208 was removed because it was sold outline_item_id: li_UkLWZg9DAJvariant_id: variant_UkLWZg9DAJitem_total: '0.0'@@ -1979,9 +1982,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R368041354- token: maK9BFEWyBAf3uSiZrLf9b2jxM5Hzcczohc- email: [email protected]+ number: R807663331+ token: adDXkz1zdhq9t54a1RH9pju1nxteWguuP8p+ email: [email protected]customer_note: Leave at doorcurrency: USDlocale: en@@ -2027,8 +2030,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 979703- slug: product-979703+ name: Product 973836+ slug: product-973836options_text: ''price: '19.99'display_price: "$19.99"@@ -2053,7 +2056,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H06113541600+ number: H72063751672tracking:tracking_url:cost: '10.0'@@ -2082,7 +2085,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Gema Gerlach+ name: Barabara Yostaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2327,9 +2330,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R465909685- token: ccYwuB3UzU34SAPCQhaJSMmbtRgtjFcqYuC- email: [email protected]+ number: R852645698+ token: wpKwLJ9pbxKykmxMzCU29fEnj13umouWTxM+ email: [email protected]customer_note:currency: USDlocale: en@@ -2373,8 +2376,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 991797- slug: product-991797+ name: Product 992524+ slug: product-992524options_text: ''price: '10.0'display_price: "$10.00"@@ -2399,7 +2402,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H73360485066+ number: H77553200603tracking: U10000tracking_url:cost: '100.0'@@ -2428,7 +2431,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Mohammad Johns+ name: Jeanelle Huelsaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2573,15 +2576,15 @@ paths:id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R074353110- email: [email protected]+ number: R339098687+ email: [email protected]customer_note:currency: USDlocale: entotal_quantity: 1fulfillment_status: backorderpayment_status: paid- completed_at: '2026-07-20T06:58:36.765Z'+ completed_at: '2026-07-21T16:20:19.426Z'item_total: '19.99'display_item_total: "$19.99"adjustment_total: '0.0'@@ -2613,8 +2616,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1027826- slug: product-1027826+ name: Product 1027544+ slug: product-1027544options_text: ''price: '19.99'display_price: "$19.99"@@ -2639,7 +2642,7 @@ paths:digital_links: []fulfillments:- id: ful_gbHJdmfrXB- number: H42129838682+ number: H01647913406tracking:tracking_url:cost: '10.0'@@ -2668,7 +2671,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Alejandro Barton+ name: Casie Strackeaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -2697,8 +2700,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: BGS-ccbd8ddbf360- number: PCJS29EY+ response_code: BGS-d60cccf8ad16+ number: PKV9QA41amount: '29.99'display_amount: "$29.99"status: completed@@ -2837,9 +2840,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R031332742- token: 3v1rZK3QouCFRNCgGYTqW1xaeAkdya2rJRD- email: [email protected]+ number: R729368018+ token: gVnZL99E49c4G6Yyp9PzFng2n2ZXX48CCaX+ email: [email protected]customer_note:currency: USDlocale: en@@ -2890,8 +2893,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1212085- slug: product-1212085+ name: Product 1218988+ slug: product-1218988options_text: ''price: '10.0'display_price: "$10.00"@@ -2916,7 +2919,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H90931418984+ number: H27197612367tracking: U10000tracking_url:cost: '100.0'@@ -2945,7 +2948,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Tijuana Kiehn+ name: Alicia Kuvalisaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3100,9 +3103,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R709730286- token: cz8CrtnVBwzW1uo4EDePsVzA2n163ZarZGA- email: [email protected]+ number: R837055202+ token: ynr1cN84XFaGhrBztZ7JdF44DFKsLuqBLtd+ email: [email protected]customer_note:currency: USDlocale: en@@ -3146,8 +3149,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1238006- slug: product-1238006+ name: Product 1233716+ slug: product-1233716options_text: ''price: '10.0'display_price: "$10.00"@@ -3172,7 +3175,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H39803900065+ number: H18878420324tracking: U10000tracking_url:cost: '100.0'@@ -3201,7 +3204,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Rhea Jerde+ name: Jenifer Sanfordaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3345,9 +3348,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R116842212- token: Exign8V5gXztDApCkBSj9KDzkADbXh2Gd5n- email: [email protected]+ number: R232244636+ token: 8jj23MK5pmbL5SQkDhyzkTbbSyovPZctTHC+ email: [email protected]customer_note:currency: USDlocale: en@@ -3393,8 +3396,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1251469- slug: product-1251469+ name: Product 1254790+ slug: product-1254790options_text: ''price: '10.0'display_price: "$10.00"@@ -3419,7 +3422,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H28744187331+ number: H92946793801tracking: U10000tracking_url:cost: '100.0'@@ -3448,7 +3451,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Jerrell Swaniawski+ name: Idalia Kertzmannaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3606,9 +3609,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R957270534- token: yLxURFVzueKC6PBPYoFL4f9Tb728TVTF3hK- email: [email protected]+ number: R680731425+ token: jwMuqQRHS39he1xEFAfUJvvEytbMWDxvvV8+ email: [email protected]customer_note:currency: USDlocale: en@@ -3649,8 +3652,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1276735- slug: product-1276735+ name: Product 1279749+ slug: product-1279749options_text: ''price: '10.0'display_price: "$10.00"@@ -3675,7 +3678,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H77710785227+ number: H54318322800tracking: U10000tracking_url:cost: '100.0'@@ -3704,7 +3707,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Colby Krajcik+ name: Tyisha Swiftaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -3733,8 +3736,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260720065855116536- number: PCMJ1P1X+ response_code: 1-SC-20260721162039441482+ number: PL7TNINMamount: '50.0'display_amount: "$50.00"status: checkout@@ -3914,9 +3917,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R610731091- token: YEvQkswQotFpWsBfq5C73KcHQiZv4qzcyY7- email: [email protected]+ number: R740288025+ token: JUg9Upygd8RLUPBW4BvpVKYPBg8GCGGoaD6+ email: [email protected]customer_note:currency: USDlocale: en@@ -3960,8 +3963,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1312650- slug: product-1312650+ name: Product 1312118+ slug: product-1312118options_text: ''price: '10.0'display_price: "$10.00"@@ -3986,7 +3989,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H06498776597+ number: H93043543546tracking: U10000tracking_url:cost: '100.0'@@ -4015,7 +4018,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Yaeko Okuneva+ name: Kip Rathaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -4044,8 +4047,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260720065857619656- number: POEO5L7L+ response_code: 1-SC-20260721162042057199+ number: P1O3NKS2amount: '50.0'display_amount: "$50.00"status: invalid@@ -4176,9 +4179,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R511205738- token: aDLj3SX6a3XwA4Utmpk8pou4kMUunMssZwP- email: [email protected]+ number: R004099846+ token: Knp5XSnseniFgNT1ie7x4AsSyfH9k3wjkyv+ email: [email protected]customer_note:currency: USDlocale: en@@ -4228,8 +4231,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1342359- slug: product-1342359+ name: Product 1341957+ slug: product-1341957options_text: ''price: '10.0'display_price: "$10.00"@@ -4258,8 +4261,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1358747- slug: product-1358747+ name: Product 1356516+ slug: product-1356516options_text: ''price: '19.99'display_price: "$19.99"@@ -4403,9 +4406,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R895021433- token: oaVJ4rhjfG8RMTHGBkQuQTvXhihzg1ZHVeb- email: [email protected]+ number: R265564023+ token: rLoUv1N9ih7v1HHnLHFNbMz74hy745LRj86+ email: [email protected]customer_note:currency: USDlocale: en@@ -4452,8 +4455,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1385004- slug: product-1385004+ name: Product 1385705+ slug: product-1385705options_text: ''price: '10.0'display_price: "$10.00"@@ -4577,9 +4580,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R697478225- token: U7k3u92idxnrph2nmobsmmTKUkJ4Q3a5Yo7- email: [email protected]+ number: R725463425+ token: rUu1ard9oJ9uaXHwejmNfDTEkz4cmNsStD6+ email: [email protected]customer_note:currency: USDlocale: en@@ -4726,9 +4729,9 @@ paths:id: ps_gbHJdmfrXBstatus: pendingcurrency: USD- external_id: bogus_f5970bccd1d2e496f9e2df3a+ external_id: bogus_081cef0f43a38dc9a23e37b2external_data:- client_secret: bogus_secret_2756b4bd68e99a4f+ client_secret: bogus_secret_a9e3e4aa9cb10c44customer_external_id:expires_at:amount: '110.0'@@ -4826,7 +4829,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_8f47847cc40a8cbf7ac48adf+ external_id: bogus_1c83f5b4634029b929befd45external_data:client_secret: secret_123customer_external_id:@@ -4888,7 +4891,7 @@ paths:id: ps_UkLWZg9DAJstatus: pendingcurrency: USD- external_id: bogus_d38dc12107c87f70b7184b2e+ external_id: bogus_863405b319c7d4c7878ee868external_data:client_secret: secret_123customer_external_id:@@ -4990,7 +4993,7 @@ paths:id: ps_UkLWZg9DAJstatus: completedcurrency: USD- external_id: bogus_abdd5b1bc7661044ec25e898+ external_id: bogus_ab1f491c431fc7c14942b273external_data:client_secret: secret_123customer_external_id:@@ -5088,7 +5091,7 @@ paths:id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJresponse_code:- number: P04XI63Y+ number: PQXDCJKRamount: '110.0'display_amount: "$110.00"status: checkout@@ -5195,9 +5198,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R411337296- token: 9as191w1KNzL89VEXYcbtxTKBsBQHs6jnKp- email: [email protected]+ number: R748692900+ token: ExTC9aN1JGUqdcW9bJjimNYK6bnNmtEydrh+ email: [email protected]customer_note:currency: USDlocale: en@@ -5238,8 +5241,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 2002470- slug: product-2002470+ name: Product 2004532+ slug: product-2004532options_text: ''price: '10.0'display_price: "$10.00"@@ -5264,7 +5267,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H66674729045+ number: H39641127215tracking: U10000tracking_url:cost: '100.0'@@ -5293,7 +5296,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Rickie Torp+ name: Tawny Boehmaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5322,8 +5325,8 @@ paths:payments:- id: py_UkLWZg9DAJpayment_method_id: pm_UkLWZg9DAJ- response_code: 1-SC-20260720065928328833- number: PYIMEG7R+ response_code: 1-SC-20260721162248221498+ number: P5RKE43Tamount: '10.0'display_amount: "$10.00"status: checkout@@ -5467,9 +5470,9 @@ paths:id: cart_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R791669896- token: ChfMRyUkuSQjToc4YjhHUCLgXVZfsn8SLBf- email: [email protected]+ number: R465837888+ token: NfyNCVCWeFDYXiwKYwxy4wx9uXassVWCQAi+ email: [email protected]customer_note:currency: USDlocale: en@@ -5513,8 +5516,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 2024256- slug: product-2024256+ name: Product 202786+ slug: product-202786options_text: ''price: '10.0'display_price: "$10.00"@@ -5539,7 +5542,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H81050159943+ number: H67232884262tracking: U10000tracking_url:cost: '100.0'@@ -5568,7 +5571,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Sidney Fisher+ name: Shery Leschaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -5710,7 +5713,7 @@ paths:id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R815120791+ number: R711852325email: [email protected]customer_note:currency: USD@@ -5718,7 +5721,7 @@ paths:total_quantity: 1fulfillment_status:payment_status:- completed_at: '2026-07-20T06:59:10.102Z'+ completed_at: '2026-07-21T16:20:55.623Z'item_total: '10.0'display_item_total: "$10.00"adjustment_total: '0.0'@@ -5750,8 +5753,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1425292- slug: product-1425292+ name: Product 1427596+ slug: product-1427596options_text: ''price: '10.0'display_price: "$10.00"@@ -5776,7 +5779,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H02137223133+ number: H62333056142tracking: U10000tracking_url:cost: '100.0'@@ -5805,7 +5808,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Paulina Barrows+ name: Ileen Brekkeaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -6742,15 +6745,15 @@ paths:- id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R602488096- email: [email protected]+ number: R398862344+ email: [email protected]customer_note:currency: USDlocale: entotal_quantity: 1fulfillment_status:payment_status:- completed_at: '2026-07-20T06:58:44.296Z'+ completed_at: '2026-07-21T16:20:27.773Z'item_total: '10.0'display_item_total: "$10.00"adjustment_total: '0.0'@@ -6782,8 +6785,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1119914- slug: product-1119914+ name: Product 1119809+ slug: product-1119809options_text: ''price: '10.0'display_price: "$10.00"@@ -6808,7 +6811,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H94775392862+ number: H43385476115tracking: U10000tracking_url:cost: '100.0'@@ -6837,7 +6840,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Rosamond Pollich+ name: Sophie Hermannaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7000,15 +7003,15 @@ paths:id: or_UkLWZg9DAJmarket_id:channel_id: ch_UkLWZg9DAJ- number: R049918057- email: [email protected]+ number: R755711983+ email: [email protected]customer_note:currency: USDlocale: entotal_quantity: 1fulfillment_status:payment_status:- completed_at: '2026-07-20T06:58:44.996Z'+ completed_at: '2026-07-21T16:20:28.608Z'item_total: '10.0'display_item_total: "$10.00"adjustment_total: '0.0'@@ -7040,8 +7043,8 @@ paths:preorder_ships_at:quantity: 1currency: USD- name: Product 1133613- slug: product-1133613+ name: Product 1133496+ slug: product-1133496options_text: ''price: '10.0'display_price: "$10.00"@@ -7066,7 +7069,7 @@ paths:digital_links: []fulfillments:- id: ful_UkLWZg9DAJ- number: H49919599290+ number: H59093298847tracking: U10000tracking_url:cost: '100.0'@@ -7095,7 +7098,7 @@ paths:stock_location:id: sloc_UkLWZg9DAJstate_abbr: NY- name: Ivonne Gleason+ name: Malinda Williamsonaddress1: 1600 Pennsylvania Ave NWcity: Washingtonzipcode: '20500'@@ -7215,8 +7218,8 @@ paths:content:application/json:example:- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjFkZmY4MmFmLTY5ZDQtNGE0NC04NDE2LWI1MzczNTI1ODA0NCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NTM0MzI2fQ.K1WM68ijw_S43fTTGRUagBJaVoeewxInDPzAAuaqvao- refresh_token: wfeRYkb2fNuZXo54maRei6v7+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImEyMzIyNmE1LTRmZGItNGNiNS1iZjllLTk1ZjNkOWEyYTkwYiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg0NjU0NDMwfQ.Cxyk-QP-NTPScoDVq37Goh9tAKe5WI3_uA1Le6TdVv0+ refresh_token: wNUQgozZCPBq46sjCR6uYn99user:id: cus_UkLWZg9DAJemail: [email protected]@@ -7233,10 +7236,10 @@ paths:newsletter_subscriber:id: sub_UkLWZg9DAJemail: [email protected]- created_at: '2026-07-20T06:58:46.198Z'- updated_at: '2026-07-20T06:58:46.199Z'+ created_at: '2026-07-21T16:20:29.876Z'+ updated_at: '2026-07-21T16:20:29.878Z'verified: true- verified_at: '2026-07-20T06:58:46Z'+ verified_at: '2026-07-21T16:20:29Z'customer_id: cus_UkLWZg9DAJcustomer_groups: []schema:@@ -7339,12 +7342,12 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]- first_name: Nola- last_name: Toy+ email: [email protected]+ first_name: Kathrine+ last_name: Yostphone: 555-555-0199accepts_email_marketing: false- full_name: Nola Toy+ full_name: Kathrine Yostavailable_store_credit_total: '0'display_available_store_credit_total: "$0.00"addresses:@@ -7480,7 +7483,7 @@ paths:application/json:example:id: cus_UkLWZg9DAJ- email: [email protected]+ email: [email protected]first_name: Updatedlast_name: Namephone: 555-555-0199@@ -7671,7 +7674,7 @@ paths:example:data:- id: gc_UkLWZg9DAJ- code: CE747A2902E0F8E6+ code: F5FF4BFD9C5C9A38status: activecurrency: USDamount: '10.0'@@ -7767,7 +7770,7 @@ paths:application/json:example:id: gc_UkLWZg9DAJ- code: A85DF7530D5427D2+ code: 2FA5A3CC7B0E77B3status: activecurrency: USDamount: '10.0'@@ -7839,8 +7842,8 @@ paths:example:id: pss_gbHJdmfrXBstatus: pending- external_id: bogus_seti_5917b4c5313a6144a001f309- external_client_secret: bogus_seti_secret_276edea39079a17f+ external_id: bogus_seti_59a8f0cb4097daca5377ad0e+ external_client_secret: bogus_seti_secret_d79d0cb5e151cbf1external_data: {}payment_method_id: pm_UkLWZg9DAJpayment_source_id:@@ -7939,8 +7942,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: pending- external_id: seti_test_db6f308c532481227c001535- external_client_secret: seti_secret_f71e16082a1cfe98ed3d8094+ external_id: seti_test_f9f0bd37a53046a006fe4795+ external_client_secret: seti_secret_e47007878c2b2ca3ca3a686dexternal_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -8016,8 +8019,8 @@ paths:example:id: pss_UkLWZg9DAJstatus: completed- external_id: seti_test_6277a5f68ea454abc328de35- external_client_secret: seti_secret_3ab47824489c4e90391a2e52+ external_id: seti_test_544613606c84fda77853c3dc+ external_client_secret: seti_secret_fab5517e19d16c860e4d704bexternal_data:client_secret: secret_123payment_method_id: pm_UkLWZg9DAJ@@ -8958,7 +8961,7 @@ paths:data:- id: wl_UkLWZg9DAJname: My Wishlist- token: EkGxSWB17nCseQYJoBp642fT+ token: xtTAEirKdUyHVmeVjEvpWkCDis_default: falseis_private: truemeta:@@ -9034,7 +9037,7 @@ paths:example:id: wl_gbHJdmfrXBname: Birthday Ideas- token: YgLGByFdHn5x4npJg2qryZYp+ token: ecn6DbXfgwBmXYxxi29izAKEis_default: falseis_private: trueschema:@@ -9130,7 +9133,7 @@ paths:example:id: wl_UkLWZg9DAJname: My Wishlist- token: T53yXsSRd1tCrW5ocQtYkcB5+ token: m5StTE9sAQNmwr8sEJgXx4Kris_default: falseis_private: trueschema:@@ -9192,7 +9195,7 @@ paths:example:id: wl_UkLWZg9DAJname: Updated Name- token: NDYqPdkWYVCnXCMvRVtA3NQ2+ token: vMrpCQxBoVg6pAhPnA7DJfCsis_default: falseis_private: trueschema:@@ -9473,11 +9476,11 @@ paths:application/json:example:id: sub_UkLWZg9DAJ- email: [email protected]- created_at: '2026-07-20T06:59:05.321Z'- updated_at: '2026-07-20T06:59:05.324Z'+ email: [email protected]+ created_at: '2026-07-21T16:20:50.582Z'+ updated_at: '2026-07-21T16:20:50.583Z'verified: true- verified_at: '2026-07-20T06:59:05Z'+ verified_at: '2026-07-21T16:20:50Z'customer_id: cus_UkLWZg9DAJschema:"$ref": "#/components/schemas/NewsletterSubscriber"@@ -9556,10 +9559,10 @@ paths:example:id: sub_UkLWZg9DAJemail: [email protected]- created_at: '2026-07-20T06:59:05.343Z'- updated_at: '2026-07-20T06:59:05.347Z'+ created_at: '2026-07-21T16:20:50.607Z'+ updated_at: '2026-07-21T16:20:50.613Z'verified: true- verified_at: '2026-07-20T06:59:05Z'+ verified_at: '2026-07-21T16:20:50Z'customer_id:schema:"$ref": "#/components/schemas/NewsletterSubscriber"@@ -9729,7 +9732,7 @@ paths:body_html: ''- id: pol_OIJLhNcSbfname: Privacy Policy- slug: privacy-policy-13c46914-2a75-4c79-8151-67de9795911e+ slug: privacy-policy-8800ef1a-581d-4c89-9e7f-3e199290b6c2body: We respect your privacy.body_html: |<div class="trix-content">@@ -9990,37 +9993,6 @@ tags:description: Store policies (return policy, privacy policy, terms of service)- name: Digitalsdescription: Digital product downloads-x-tagGroups:-- name: Authentication- tags:- - Authentication-- name: Product Catalog- tags:- - Product Catalog-- name: Carts- tags:- - Carts-- name: Orders- tags:- - Orders-- name: Customers- tags:- - Customers-- name: Markets- tags:- - Markets-- name: Wishlists- tags:- - Wishlists-- name: Newsletter Subscribers- tags:- - Newsletter Subscribers-- name: Policies- tags:- - Policies-- name: Digitals- tags:- - Digitalscomponents:securitySchemes:api_key:diff --git a/docs/docs.json b/docs/docs.jsonindex 00d8d4e028..181b76c5ba 100644--- a/docs/docs.json+++ b/docs/docs.json@@ -246,6 +246,7 @@"developer/storefront/nextjs/quickstart","developer/storefront/nextjs/architecture","developer/storefront/nextjs/customization",+ "developer/storefront/nextjs/wholesale","developer/storefront/nextjs/deployment"]}diff --git a/docs/plans/6.0-order-routing.md b/docs/plans/6.0-order-routing.mdindex 2e9260df89..2469ce0ac4 100644--- a/docs/plans/6.0-order-routing.md+++ b/docs/plans/6.0-order-routing.md@@ -1,10 +1,10 @@# Order Routing-**Status:** Phase 1 shipped in 5.5 (Channel + OrderRoutingRule + strategy base/Rules/Reducer/Legacy); Phase 2+ pending in 6.0-**Target:** Spree 5.5 (Phase 1 ✓) → 6.0 (Phase 2+)+**Status:** Phase 1 shipped in 5.5 (Channel + OrderRoutingRule + strategy base/Rules/Reducer/Legacy); rules admin (Admin API v3 + React dashboard editor, no legacy Rails admin — see decisions.md 2026-07-21) shipped in 5.6; rest of Phase 2+ pending in 6.0+**Target:** Spree 5.5 (Phase 1 ✓) → 5.6 (rules admin ✓) → 6.0 (Phase 2+)**Depends on:** none for Phase 1; 6.0 phases extend `6.0-channels-catalogs-b2b.md`, `6.0-stock-reservations.md`, `6.0-typed-stock-movements.md`, `6.0-cart-order-split.md`**Author:** Damian + Claude-**Last updated:** 2026-05-20+**Last updated:** 2026-07-21## Summary@@ -576,17 +576,22 @@ class Spree::Channel < Spree.base_classend```-### Admin API (Phase 2 — defer to channels)+### Admin API + dashboard editor (shipped in 5.6)-Phase 1 ships no admin UI for routing rules. The 5.5 default seed (3 rules per store) covers the customer's wedge case. Admin API + SPA settings page land in Phase 2 when channels are present and merchants have a real reason to tune per-channel routing.+Phase 1 shipped no admin UI for routing rules — the 5.5 default seed (3 rules per store) covered the wedge case, plus a small admin API change:-Phase 1 admin API change is small:--```+```textPATCH /api/v3/admin/orders/:id { preferred_stock_location_id: "sloc_..." }```-— exposing the new column on the existing `Order` admin endpoint.+The rules-management slice of Phase 2 shipped in 5.6, **React dashboard only — no legacy Rails admin UI** (decisions.md 2026-07-21):++- **Admin API v3**: nested CRUD `/api/v3/admin/channels/:channel_id/order_routing_rules` (mirrors promotion rules: `SubclassedResource`, `scoped_resource :settings`, flat params `type`/`active`/`position`/`preferences`) + top-level `GET /order_routing_rules/types` discovery driven by `subclasses_with_preference_schema` over `Spree.order_routing.rules`. Create without `position` appends at the end of the channel's list; updating `position` reorders around it (`acts_as_list`). The STI `type` is immutable after create — delete and re-create to change kind.+- **One rule per kind per channel** — a duplicate signal would either be a no-op or fight itself in the reducer walk. Enforced by a unique DB index on `(channel_id, type)` + model uniqueness validation, and the dashboard picker only offers kinds not yet on the channel (mirrors `PromotionRule`'s per-promotion type uniqueness).+- **`@spree/admin-sdk`**: `client.channels.orderRoutingRules.{list,get,create,update,delete}` + `client.orderRoutingRules.types()`.+- **Dashboard**: routing-rules editor embedded in the channel edit sheet (`OrderRoutingRulesSection`) — dnd-kit drag-to-reorder, per-rule active switches, "Add rule" picker fed by the types endpoint, per-rule preference editing via the schema-driven `PreferencesForm`. Plugin-registered rule kinds appear automatically with their preference schemas (answers old Open Question 3 — no separate `config_schema` needed). The section renders only when the channel's **effective** strategy is `Rules` — the channel override, falling back to the store preference (now exposed as `preferred_order_routing_strategy` on the admin Store serializer).++Remaining Phase 2 scope (new rule kinds, Channel FK additions) is unchanged below.## Migration Path@@ -620,7 +625,7 @@ PATCH /api/v3/admin/orders/:id { preferred_stock_location_id: "sloc_..." }- `Channel.default_catalog_id` FK (added when `Catalog` ships).- `CompanyLocation.preferred_stock_location_id` FK.- `Spree::Admin::User.preferred_stock_location_id` FK (staff sign-in default).-- Admin API + SPA settings page for channels and per-channel routing rules.+- ~~Admin API + SPA settings page for channels and per-channel routing rules.~~ Shipped in 5.6 (see "Admin API + dashboard editor" above).- New rule kinds: `closest_location`, `stay_in_market`, `ranked_locations`, `metafield`.### Phase 3 — 6.0, with `6.0-stock-reservations.md` + `6.0-typed-stock-movements.md`@@ -684,7 +689,7 @@ The reservation/routing handoff. See "Reservation-first allocation (Phase 3)" ab2. **Rule conflict UX.** When rules disagree (preferred vs in-market), the merchant might be surprised by the priority order's effect. Defer to Phase 2 admin UI design — likely a "rule preview" with sample addresses.-3. **Custom rules in admin UI.** Plugin-registered kinds need to render in the admin SPA. Likely a `config_schema` method on rule classes that returns a JSON schema for the rule's `config` field. Defer to Phase 2.+3. ~~**Custom rules in admin UI.**~~ Resolved in 5.6: no separate `config_schema` — the existing `Spree::PreferenceSchema` (`preference :name, :type` declarations → `preference_schema` on the `/types` payload) drives the dashboard's schema-driven `PreferencesForm`, same as promotion rules/actions. Plugin rule kinds render automatically once registered.4. **Reservation-aware eligibility.** Phase 1 routing reads raw `count_on_hand` from `Spree::StockItem` — neither `OrderRouting::Strategy::Rules#eligible_locations` (existence check) nor `Rules::MinimizeSplits` (coverage check) subtract active `Spree::StockReservation` quantities. Reservations still protect at the `Quantifier` layer (`can_supply?` gates entry) and at order completion (`AvailabilityValidator`), so a routing decision against reservation-held stock fails closed rather than oversells. Going through `Quantifier` per location × variant adds a SUM query per cell, which is too costly for the eligibility hot path. Revisit when `6.0-typed-stock-movements.md` lands the `allocated_count` column on `Spree::StockItem` — that lets `available_count` become a single SQL expression and routing can join it directly without per-pair queries.diff --git a/docs/plans/decisions.md b/docs/plans/decisions.mdindex a58295756a..2b9a2fdaca 100644--- a/docs/plans/decisions.md+++ b/docs/plans/decisions.md@@ -1,3 +1,18 @@+## 2026-07-21: Order routing rules get admin management in the React dashboard only++Per-channel `Spree::OrderRoutingRule` management (the Phase 2 "Admin API + SPA+settings page" slice of `6.0-order-routing.md`) ships ahead of the rest of+Phase 2: Admin API v3 CRUD nested under channels+(`/channels/:channel_id/order_routing_rules`) + top-level+`/order_routing_rules/types` discovery, `@spree/admin-sdk` resource, and a+routing-rules editor inside the dashboard's channel edit sheet (drag-to-reorder,+active toggles, schema-driven preference forms via `PreferencesForm`).++**No legacy Rails admin UI** — routing rules are managed exclusively in the+React dashboard. The legacy admin's channel form keeps only the strategy+override select it already had. New admin surfaces target the SPA; the legacy+admin is in maintenance mode for 6.0.+## 2026-07-20: Wholesale applicant company name stays in metadata until 6.1 Company accountsThe gated wholesale portal's apply form collects a company name. Considereddiff --git a/packages/admin-sdk/examples/order-routing-rules/create.ts b/packages/admin-sdk/examples/order-routing-rules/create.tsnew file mode 100644index 0000000000..4656220844--- /dev/null+++ b/packages/admin-sdk/examples/order-routing-rules/create.ts@@ -0,0 +1,15 @@+import { createAdminClient } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+})++// region:example+const rule = await client.channels.orderRoutingRules.create('ch_UkLWZg9DAJ', {+ type: 'preferred_location',+})++// endregion:example++export { rule }diff --git a/packages/admin-sdk/examples/order-routing-rules/delete.ts b/packages/admin-sdk/examples/order-routing-rules/delete.tsnew file mode 100644index 0000000000..3ef9f5054d--- /dev/null+++ b/packages/admin-sdk/examples/order-routing-rules/delete.ts@@ -0,0 +1,10 @@+import { createAdminClient } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+})++// region:example+await client.channels.orderRoutingRules.delete('ch_UkLWZg9DAJ', 'orule_k5nR8xLq')+// endregion:examplediff --git a/packages/admin-sdk/examples/order-routing-rules/list.ts b/packages/admin-sdk/examples/order-routing-rules/list.tsnew file mode 100644index 0000000000..627fa962fc--- /dev/null+++ b/packages/admin-sdk/examples/order-routing-rules/list.ts@@ -0,0 +1,13 @@+import { createAdminClient } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+})++// region:example+const { data: rules } = await client.channels.orderRoutingRules.list('ch_UkLWZg9DAJ')++// endregion:example++export { rules }diff --git a/packages/admin-sdk/examples/order-routing-rules/types.ts b/packages/admin-sdk/examples/order-routing-rules/types.tsnew file mode 100644index 0000000000..9cbd710b37--- /dev/null+++ b/packages/admin-sdk/examples/order-routing-rules/types.ts@@ -0,0 +1,13 @@+import { createAdminClient } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+})++// region:example+const { data: ruleTypes } = await client.orderRoutingRules.types()++// endregion:example++export { ruleTypes }diff --git a/packages/admin-sdk/examples/order-routing-rules/update.ts b/packages/admin-sdk/examples/order-routing-rules/update.tsnew file mode 100644index 0000000000..81ac231bc1--- /dev/null+++ b/packages/admin-sdk/examples/order-routing-rules/update.ts@@ -0,0 +1,16 @@+import { createAdminClient } from '@spree/admin-sdk'++const client = createAdminClient({+ baseUrl: 'https://your-store.com',+ secretKey: 'sk_xxx',+})++// region:example+const rule = await client.channels.orderRoutingRules.update('ch_UkLWZg9DAJ', 'orule_k5nR8xLq', {+ active: false,+ position: 2,+})++// endregion:example++export { rule }diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.tsindex 88c4957792..1965a2dc12 100644--- a/packages/admin-sdk/src/admin-client.ts+++ b/packages/admin-sdk/src/admin-client.ts@@ -118,6 +118,8 @@ import type {OrderCancelParams,OrderCompleteParams,OrderCreateParams,+ OrderRoutingRuleCreateParams,+ OrderRoutingRuleUpdateParams,OrderUpdateParams,PasswordResetParams,PasswordResetRequestParams,@@ -182,6 +184,7 @@ import type {Media,OptionType,Order,+ OrderRoutingRule,Payment,PaymentMethod,Price,@@ -2051,6 +2054,65 @@ export class AdminClient {...options,body: params,}),++ /**+ * Order routing rules — the channel's prioritized list of signals the+ * `Rules` routing strategy walks when choosing fulfillment locations.+ * Rule kinds are discovered via `client.orderRoutingRules.types()`.+ */+ orderRoutingRules: {+ list: (+ channelId: string,+ params?: ListParams & Record<string, unknown>,+ options?: RequestOptions,+ ): Promise<PaginatedResponse<OrderRoutingRule>> =>+ this.request<PaginatedResponse<OrderRoutingRule>>(+ 'GET',+ `/channels/${channelId}/order_routing_rules`,+ { ...options, params: params ? transformListParams(params) : undefined },+ ),++ get: (channelId: string, id: string, options?: RequestOptions): Promise<OrderRoutingRule> =>+ this.request<OrderRoutingRule>(+ 'GET',+ `/channels/${channelId}/order_routing_rules/${id}`,+ options,+ ),++ create: (+ channelId: string,+ params: OrderRoutingRuleCreateParams,+ options?: RequestOptions,+ ): Promise<OrderRoutingRule> =>+ this.request<OrderRoutingRule>('POST', `/channels/${channelId}/order_routing_rules`, {+ ...options,+ body: params,+ }),++ update: (+ channelId: string,+ id: string,+ params: OrderRoutingRuleUpdateParams,+ options?: RequestOptions,+ ): Promise<OrderRoutingRule> =>+ this.request<OrderRoutingRule>(+ 'PATCH',+ `/channels/${channelId}/order_routing_rules/${id}`,+ { ...options, body: params },+ ),++ delete: (channelId: string, id: string, options?: RequestOptions): Promise<void> =>+ this.request<void>('DELETE', `/channels/${channelId}/order_routing_rules/${id}`, options),+ },+ }++ readonly orderRoutingRules = {+ types: (options?: RequestOptions): Promise<{ data: ResourceTypeDefinition[] }> =>+ this.request<{ data: ResourceTypeDefinition[] }>(+ 'GET',+ '/order_routing_rules/types',+ options,+ ),}// ============================================diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.tsindex b58d56a907..2b162cd444 100644--- a/packages/admin-sdk/src/params.ts+++ b/packages/admin-sdk/src/params.ts@@ -1309,6 +1309,22 @@ export interface PromotionActionUpdateParams {line_items?: PromotionActionLineItemParams[]}+export interface OrderRoutingRuleCreateParams {+ /** Wire shorthand for the rule subclass (e.g. `'preferred_location'`), from `GET /order_routing_rules/types`. */+ type: string+ active?: boolean+ /** 1-based priority in the channel's rule list. Omit to append at the end. */+ position?: number+ preferences?: Record<string, unknown>+}++export interface OrderRoutingRuleUpdateParams {+ active?: boolean+ /** Assigning a new position reorders the rest of the channel's list around it. */+ position?: number+ preferences?: Record<string, unknown>+}+export interface PromotionRuleCreateParams {/** Wire shorthand for the rule subclass (e.g. `'currency'`, `'item_total'`). */type: stringdiff --git a/packages/admin-sdk/src/types/generated/OrderRoutingRule.ts b/packages/admin-sdk/src/types/generated/OrderRoutingRule.tsnew file mode 100644index 0000000000..88766ba0f2--- /dev/null+++ b/packages/admin-sdk/src/types/generated/OrderRoutingRule.ts@@ -0,0 +1,19 @@+// Typelizer digest ed28efbed6eef00b787ae85890f81e74+//+// DO NOT MODIFY: This file was automatically generated by Typelizer.++interface OrderRoutingRule {+ id: string;+ position: number;+ active: boolean;+ created_at: string;+ updated_at: string;+ type: string;+ channel_id: string;+ preferences: Record<string, unknown>;+ preference_schema: Array<{ key: string; type: string; default: unknown }>;+ label: string;+ description: string;+}++export default OrderRoutingRule;diff --git a/packages/admin-sdk/src/types/generated/Store.ts b/packages/admin-sdk/src/types/generated/Store.tsindex b6ae143682..b300da8de8 100644--- a/packages/admin-sdk/src/types/generated/Store.ts+++ b/packages/admin-sdk/src/types/generated/Store.ts@@ -1,4 +1,4 @@-// Typelizer digest ac11ff87fab602441781cd2f8511be7f+// Typelizer digest e03ce3e5b77d8ed022300064cd897e1e//// DO NOT MODIFY: This file was automatically generated by Typelizer.import type {SetupTask} from '@/types'@@ -21,6 +21,7 @@ interface Store {preferred_unit_system: string;preferred_storefront_access: string;preferred_guest_checkout: boolean;+ preferred_order_routing_strategy: string;created_at: string;updated_at: string;url: string;diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.tsindex a2a50f4ddf..d6629c9db3 100644--- a/packages/admin-sdk/src/types/generated/index.ts+++ b/packages/admin-sdk/src/types/generated/index.ts@@ -1,4 +1,4 @@-// Typelizer digest 108b841194781c0ae25dd5cedb2dcbdb+// Typelizer digest e1064363e254ce9d7c1214b4382289c0//// DO NOT MODIFY: This file was automatically generated by Typelizer.export type { default as Address } from './Address'@@ -33,6 +33,7 @@ export type { default as Media } from './Media'export type { default as NewsletterSubscriber } from './NewsletterSubscriber'export type { default as OptionType } from './OptionType'export type { default as OptionValue } from './OptionValue'+export type { default as OrderRoutingRule } from './OrderRoutingRule'export type { default as Order } from './Order'export type { default as PaymentMethod } from './PaymentMethod'export type { default as Payment } from './Payment'diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.tsindex adf76ac6ab..a9a2dba94d 100644--- a/packages/admin-sdk/src/types/index.ts+++ b/packages/admin-sdk/src/types/index.ts@@ -41,6 +41,7 @@ export type { default as Media } from './generated/Media'export type { default as OptionType } from './generated/OptionType'export type { default as OptionValue } from './generated/OptionValue'export type { default as Order } from './generated/Order'+export type { default as OrderRoutingRule } from './generated/OrderRoutingRule'export type { default as Payment } from './generated/Payment'export type { default as PaymentMethod } from './generated/PaymentMethod'export type { default as PaymentSource } from './generated/PaymentSource'diff --git a/packages/admin-sdk/tests/order-routing-rules.test.ts b/packages/admin-sdk/tests/order-routing-rules.test.tsnew file mode 100644index 0000000000..0a4b3b65e4--- /dev/null+++ b/packages/admin-sdk/tests/order-routing-rules.test.ts@@ -0,0 +1,110 @@+import { HttpResponse, http } from 'msw'+import { describe, expect, it } from 'vitest'+import { API_PREFIX, createTestClient, paginated } from './helpers'+import { server } from './mocks/server'++const sampleRule = {+ id: 'orule_abc123',+ type: 'preferred_location',+ channel_id: 'ch_abc123',+ position: 1,+ active: true,+ label: 'Preferred location',+ description: 'Fulfill from the location pinned on the order, when one is set',+ preferences: {},+ preference_schema: [],+ created_at: '2026-07-01T00:00:00Z',+ updated_at: '2026-07-01T00:00:00Z',+}++describe('channels.orderRoutingRules', () => {+ it('GETs /channels/:channelId/order_routing_rules', async () => {+ server.use(+ http.get(`${API_PREFIX}/channels/ch_abc123/order_routing_rules`, () =>+ HttpResponse.json(paginated([sampleRule])),+ ),+ )++ const res = await createTestClient().channels.orderRoutingRules.list('ch_abc123')++ expect(res.data).toHaveLength(1)+ expect(res.data[0]?.id).toBe('orule_abc123')+ })++ it('POSTs the create body verbatim', async () => {+ let body: unknown+ server.use(+ http.post(`${API_PREFIX}/channels/ch_abc123/order_routing_rules`, async ({ request }) => {+ body = await request.json()+ return HttpResponse.json(sampleRule, { status: 201 })+ }),+ )++ await createTestClient().channels.orderRoutingRules.create('ch_abc123', {+ type: 'preferred_location',+ })++ expect(body).toEqual({ type: 'preferred_location' })+ })++ it('PATCHes active and position updates', async () => {+ let body: unknown+ server.use(+ http.patch(+ `${API_PREFIX}/channels/ch_abc123/order_routing_rules/orule_abc123`,+ async ({ request }) => {+ body = await request.json()+ return HttpResponse.json({ ...sampleRule, active: false, position: 2 })+ },+ ),+ )++ const res = await createTestClient().channels.orderRoutingRules.update(+ 'ch_abc123',+ 'orule_abc123',+ { active: false, position: 2 },+ )++ expect(body).toEqual({ active: false, position: 2 })+ expect(res.active).toBe(false)+ })++ it('DELETEs and resolves on 204', async () => {+ server.use(+ http.delete(+ `${API_PREFIX}/channels/ch_abc123/order_routing_rules/orule_abc123`,+ () => new HttpResponse(null, { status: 204 }),+ ),+ )++ await expect(+ createTestClient().channels.orderRoutingRules.delete('ch_abc123', 'orule_abc123'),+ ).resolves.toBeUndefined()+ })+})++describe('orderRoutingRules', () => {+ describe('types', () => {+ it('GETs /order_routing_rules/types', async () => {+ server.use(+ http.get(`${API_PREFIX}/order_routing_rules/types`, () =>+ HttpResponse.json({+ data: [+ {+ type: 'preferred_location',+ label: 'Preferred location',+ description: null,+ preference_schema: [],+ },+ ],+ }),+ ),+ )++ const res = await createTestClient().orderRoutingRules.types()++ expect(res.data).toHaveLength(1)+ expect(res.data[0]?.type).toBe('preferred_location')+ })+ })+})diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.jsonindex b2faf6ba15..344265739b 100644--- a/packages/cli/src/generated/admin-spec.json+++ b/packages/cli/src/generated/admin-spec.json@@ -1 +1 @@-{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It 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/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/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}}}}}}}},"/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"}}}}}}},"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/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, definition is admin-only (was `display_on: back_end`)"}}}}}}}},"/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"}}}}}}},"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_iso":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_abbr":{"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., category, 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","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"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 / category / 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"},"category_id":{"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":["Spree::Exports::Products","Spree::Exports::Orders","Spree::Exports::Customers","Spree::Exports::ProductTranslations","Spree::Exports::GiftCards","Spree::Exports::CouponCodes","Spree::Exports::NewsletterSubscribers"]},"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}/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}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled 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 resumed","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[state_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[state_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/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_isos` 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_isos":{"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_isos"]}}}}}},"/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_isos` 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_isos":{"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}/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_iso":{"type":"string"},"state_abbr":{"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_iso":{"type":"string"},"state_abbr":{"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"},"special_instructions":{"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."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"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**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":{}}}}}},"/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}/resume":{"patch":{"summary":"Resume a canceled order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a previously canceled 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":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order resumed","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, no product_ids)","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"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids to seed the list with."},"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 alternative to `product_ids`: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)`. Mix-and-match with `product_ids` is supported but typically unnecessary — `prices` alone tells the server which variants belong to the list and what the override amount is.","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"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids — reconciles list membership (adds + removes)."},"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_items:` (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_items":{"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_items:` (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_items":{"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"}}}},"/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 (taxon) 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_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/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_credit_categories":{"get":{"summary":"List store credit categories","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured store credit categories. Categories classify\nstore credits (e.g., \"Goodwill\", \"Gift Card\", \"Refund\") and surface\nin the admin UI as a dropdown when issuing or editing a store\ncredit. Category names matching `Spree::Config[:non_expiring_credit_types]`\nare flagged via `non_expiring: true`.\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":"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":"store credit categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditCategory"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credit_categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Store credit category ID","schema":{"type":"string"}}],"get":{"summary":"Get a store credit category","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single store credit category 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":"store credit category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCreditCategory"}}}},"404":{"description":"store credit category 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","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/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_settings` (for API-key authentication).","parameters":[{"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_settings` (for API-key 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_settings` (for API-key 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_settings` (for API-key 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_settings` (for API-key authentication).","parameters":[{"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_settings` (for API-key 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_settings` (for API-key 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_settings` (for API-key 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/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the roles available for staff role pickers. Roles are global, not per-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"}}],"responses":{"200":{"description":"roles found","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_iso":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_abbr":{"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_iso":{"type":"string","nullable":true},"state_abbr":{"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 master 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_items, 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","required":["options"],"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":"Required. A variant created here is always non-master, so it must declare at least one option pair (e.g. size + color) or creation fails with 422. One pair per option type the variant 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_items":{"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_items, 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_items":{"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/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"},"hide_from_nav":{"type":"boolean"}},"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"},"hide_from_nav":{"type":"boolean"}}}}}}},"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 a product to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies a product under the category (appended to the end).\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":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/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/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":["Spree::Imports::Products","Spree::Imports::Customers","Spree::Imports::ProductTranslations"]},"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. Spree::Imports::Products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/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":{}}}}}}},"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"]},"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"]},"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)"}},"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"]},"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"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"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_iso":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_name":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true}},"required":["id","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_iso","state_text","state_abbr","quick_checkout","is_default_billing","is_default_shipping","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"Adjustment":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"display_amount":{"type":"string"},"included":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","label","display_amount","included","created_at","updated_at","amount","order_id"],"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"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles"],"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},"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"}},"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","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"}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at"],"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},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["iso","iso3","name","states_required","zipcode_required","created_at","updated_at"],"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","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"}},"login":{"type":"string","nullable":true},"metadata":{"type":"object"},"last_sign_in_at":{"type":"string","nullable":true},"current_sign_in_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"sign_in_count":{"type":"number"},"failed_attempts":{"type":"number"},"last_sign_in_ip":{"type":"string","nullable":true},"current_sign_in_ip":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"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"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","login","metadata","last_sign_in_at","current_sign_in_at","created_at","updated_at","sign_in_count","failed_attempts","last_sign_in_ip","current_sign_in_ip","tags","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},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","code","created_at","updated_at"],"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"},"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"},"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","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","created_at","updated_at"],"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"},"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","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"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},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"type":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","type","format","created_at","updated_at","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"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},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"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},"order":{"$ref":"#/components/schemas/Order"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","number","tracking","tracking_url","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","items","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id"],"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},"item_type":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","item_type","created_at","updated_at","import_id","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"type":{"type":"string","nullable":true},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string"},"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"},"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","type","rows_count","created_at","updated_at","status","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"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"},"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},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","variant_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","created_at","updated_at","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_isos":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_isos","supported_locales","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},"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},"created_at":{"type":"string"},"updated_at":{"type":"string"},"viewable_id":{"type":"string"},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string"}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","created_at","updated_at","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},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"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"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"}},"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},"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"},"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},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"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/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}},"return_authorizations":{"type":"array","items":{"$ref":"#/components/schemas/ReturnAuthorization"}},"reimbursements":{"type":"array","items":{"$ref":"#/components/schemas/Reimbursement"}}},"required":["id","market_id","channel_id","number","email","customer_note","currency","locale","total_quantity","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","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","tags","internal_note","approver_id","canceler_id","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},"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","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"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"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","amount","display_amount","status","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},"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"},"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"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"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"},"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},"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},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_category_id":{"type":"string","nullable":true},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}},"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","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","tax_category_id"],"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},"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"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_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},"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},"reimbursement_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"},"reimbursement":{"$ref":"#/components/schemas/Reimbursement"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","reimbursement_id","metadata","created_at","updated_at"],"x-typelizer":true},"Reimbursement":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reimbursement_status":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"customer_return_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","reimbursement_status","total","order_id","customer_return_id","created_at","updated_at"],"x-typelizer":true},"ReturnAuthorization":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"return_authorization_reason_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","order_id","stock_location_id","return_authorization_reason_id","created_at","updated_at"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","created_at","updated_at"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["abbr","name","created_at","updated_at"],"x-typelizer":true},"StockItem":{"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},"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","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"state_abbr":{"type":"string","nullable":true},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"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"},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","state_abbr","name","address1","city","zipcode","country_iso","country_name","state_text","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","pickup_ready_in_minutes","pickup_instructions","created_at","updated_at"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_item_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_item_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},"StoreCreditCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"non_expiring":{"type":"boolean"}},"required":["id","name","created_at","updated_at","non_expiring"],"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},"category_id":{"type":"string","nullable":true},"category_name":{"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","category_id","category_name"],"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"},"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_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","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},"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},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"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},"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},"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"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"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","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name"],"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},"payload":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","payload","created_at","updated_at","delivered_at","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/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"},"hide_from_nav":{"type":"boolean"}},"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"},"hide_from_nav":{"type":"boolean"}}}}}}},"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 a product to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies a product under the category (appended to the end).\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":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/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}}}}}}}},"/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"}}}}}}},"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, definition is admin-only (was `display_on: back_end`)"}}}}}}}},"/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"}}}}}}},"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_iso":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_abbr":{"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., category, 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","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"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 / category / 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"},"category_id":{"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":["Spree::Exports::Products","Spree::Exports::Orders","Spree::Exports::Customers","Spree::Exports::ProductTranslations","Spree::Exports::GiftCards","Spree::Exports::CouponCodes","Spree::Exports::NewsletterSubscribers"]},"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}/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}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled 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 resumed","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[state_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[state_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":["Spree::Imports::Products","Spree::Imports::Customers","Spree::Imports::ProductTranslations"]},"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. Spree::Imports::Products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/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_isos` 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_isos":{"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_isos"]}}}}}},"/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_isos` 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_isos":{"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}/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_iso":{"type":"string"},"state_abbr":{"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_iso":{"type":"string"},"state_abbr":{"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"},"special_instructions":{"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."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"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**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":{}}}}}},"/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}/resume":{"patch":{"summary":"Resume a canceled order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a previously canceled 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":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order resumed","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, no product_ids)","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"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids to seed the list with."},"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 alternative to `product_ids`: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)`. Mix-and-match with `product_ids` is supported but typically unnecessary — `prices` alone tells the server which variants belong to the list and what the override amount is.","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"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids — reconciles list membership (adds + removes)."},"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_items:` (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_items":{"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_items:` (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_items":{"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"}}}},"/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 (taxon) 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_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/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_credit_categories":{"get":{"summary":"List store credit categories","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured store credit categories. Categories classify\nstore credits (e.g., \"Goodwill\", \"Gift Card\", \"Refund\") and surface\nin the admin UI as a dropdown when issuing or editing a store\ncredit. Category names matching `Spree::Config[:non_expiring_credit_types]`\nare flagged via `non_expiring: true`.\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":"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":"store credit categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditCategory"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credit_categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Store credit category ID","schema":{"type":"string"}}],"get":{"summary":"Get a store credit category","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single store credit category 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":"store credit category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCreditCategory"}}}},"404":{"description":"store credit category 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","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/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_settings` (for API-key authentication).","parameters":[{"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_settings` (for API-key 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_settings` (for API-key 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_settings` (for API-key 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_settings` (for API-key authentication).","parameters":[{"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_settings` (for API-key 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_settings` (for API-key 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_settings` (for API-key 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/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the roles available for staff role pickers. Roles are global, not per-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"}}],"responses":{"200":{"description":"roles found","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_iso":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_abbr":{"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_iso":{"type":"string","nullable":true},"state_abbr":{"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 master 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_items, 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","required":["options"],"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":"Required. A variant created here is always non-master, so it must declare at least one option pair (e.g. size + color) or creation fails with 422. One pair per option type the variant 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_items":{"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_items, 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_items":{"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"}}}}}}}}},"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"]},"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"]},"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)"}},"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"]},"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"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"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_iso":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_name":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true}},"required":["id","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_iso","state_text","state_abbr","quick_checkout","is_default_billing","is_default_shipping","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"Adjustment":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"display_amount":{"type":"string"},"included":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","label","display_amount","included","created_at","updated_at","amount","order_id"],"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"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles"],"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},"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"}},"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","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"}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at"],"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},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["iso","iso3","name","states_required","zipcode_required","created_at","updated_at"],"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","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"}},"login":{"type":"string","nullable":true},"metadata":{"type":"object"},"last_sign_in_at":{"type":"string","nullable":true},"current_sign_in_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"sign_in_count":{"type":"number"},"failed_attempts":{"type":"number"},"last_sign_in_ip":{"type":"string","nullable":true},"current_sign_in_ip":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"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"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","login","metadata","last_sign_in_at","current_sign_in_at","created_at","updated_at","sign_in_count","failed_attempts","last_sign_in_ip","current_sign_in_ip","tags","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},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","code","created_at","updated_at"],"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"},"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"},"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","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","created_at","updated_at"],"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"},"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","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"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},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"type":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","type","format","created_at","updated_at","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"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},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"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},"order":{"$ref":"#/components/schemas/Order"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","number","tracking","tracking_url","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","items","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id"],"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},"item_type":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","item_type","created_at","updated_at","import_id","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"type":{"type":"string","nullable":true},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"status":{"type":"string"},"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"},"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","type","rows_count","created_at","updated_at","status","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"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"},"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},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","variant_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","created_at","updated_at","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_isos":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_isos","supported_locales","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},"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},"created_at":{"type":"string"},"updated_at":{"type":"string"},"viewable_id":{"type":"string"},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string"}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","created_at","updated_at","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},"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},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"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"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"}},"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},"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"},"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},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"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/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}},"return_authorizations":{"type":"array","items":{"$ref":"#/components/schemas/ReturnAuthorization"}},"reimbursements":{"type":"array","items":{"$ref":"#/components/schemas/Reimbursement"}}},"required":["id","market_id","channel_id","number","email","customer_note","currency","locale","total_quantity","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","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","tags","internal_note","approver_id","canceler_id","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},"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","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"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"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","amount","display_amount","status","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},"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"},"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"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"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"},"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},"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},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_category_id":{"type":"string","nullable":true},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}},"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","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","tax_category_id"],"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},"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"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_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},"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},"reimbursement_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"},"reimbursement":{"$ref":"#/components/schemas/Reimbursement"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","reimbursement_id","metadata","created_at","updated_at"],"x-typelizer":true},"Reimbursement":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reimbursement_status":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"customer_return_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","reimbursement_status","total","order_id","customer_return_id","created_at","updated_at"],"x-typelizer":true},"ReturnAuthorization":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"return_authorization_reason_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","order_id","stock_location_id","return_authorization_reason_id","created_at","updated_at"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","created_at","updated_at"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["abbr","name","created_at","updated_at"],"x-typelizer":true},"StockItem":{"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},"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","metadata","created_at","updated_at","allocated_count","available_count"],"x-typelizer":true},"StockLocation":{"type":"object","properties":{"id":{"type":"string"},"state_abbr":{"type":"string","nullable":true},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"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"},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","state_abbr","name","address1","city","zipcode","country_iso","country_name","state_text","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","pickup_ready_in_minutes","pickup_instructions","created_at","updated_at"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_item_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_item_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},"StoreCreditCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"non_expiring":{"type":"boolean"}},"required":["id","name","created_at","updated_at","non_expiring"],"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},"category_id":{"type":"string","nullable":true},"category_name":{"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","category_id","category_name"],"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"},"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_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_order_routing_strategy","created_at","updated_at","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},"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},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"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},"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},"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"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"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","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name"],"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/cli/src/generated/resource-paths.json b/packages/cli/src/generated/resource-paths.jsonindex 26ab7fad14..58f12a8237 100644--- a/packages/cli/src/generated/resource-paths.json+++ b/packages/cli/src/generated/resource-paths.json@@ -1 +1 @@-["/admin_users","/allowed_origins","/api_keys","/auth","/categories","/channels","/custom_field_definitions","/customer_groups","/customers","/exports","/gift_card_batches","/gift_cards","/imports","/invitations","/locales","/markets","/me","/option_types","/orders","/payment_methods","/price_lists","/prices","/products","/promotion_actions","/promotion_rules","/promotions","/roles","/stock_locations","/store","/store_credit_categories","/tags","/translatable_resources","/translations","/webhook_endpoints"]\ No newline at end of file+["/admin_users","/allowed_origins","/api_keys","/auth","/categories","/channels","/custom_field_definitions","/customer_groups","/customers","/exports","/gift_card_batches","/gift_cards","/imports","/invitations","/locales","/markets","/me","/option_types","/order_routing_rules","/orders","/payment_methods","/price_lists","/prices","/products","/promotion_actions","/promotion_rules","/promotions","/roles","/stock_locations","/store","/store_credit_categories","/tags","/translatable_resources","/translations","/webhook_endpoints"]\ No newline at end of filediff --git a/packages/dashboard-core/src/lib/permissions.ts b/packages/dashboard-core/src/lib/permissions.tsindex 7b1ac2dd3b..28e08f75e7 100644--- a/packages/dashboard-core/src/lib/permissions.ts+++ b/packages/dashboard-core/src/lib/permissions.ts@@ -16,6 +16,7 @@ export const Subject = {AllowedOrigin: 'Spree::AllowedOrigin',Store: 'Spree::Store',Channel: 'Spree::Channel',+ OrderRoutingRule: 'Spree::OrderRoutingRule',// Categories are Spree::Category < Spree::Taxon; abilities are published under// the Spree::Taxon subject, so the value stays 'Spree::Taxon' while the key// reads as the user-facing resource name.diff --git a/packages/dashboard/e2e/channels-settings.spec.ts b/packages/dashboard/e2e/channels-settings.spec.tsindex 6dd809b7e9..aaf842b869 100644--- a/packages/dashboard/e2e/channels-settings.spec.ts+++ b/packages/dashboard/e2e/channels-settings.spec.ts@@ -90,6 +90,70 @@ test.describe('settings / channels', () => {await expect(rowButton(page, updated)).toBeVisible({ timeout: 15_000 })})+ test('manages order routing rules on a channel', async ({ page }) => {+ const creds = await login(page)+ await gotoIndex(page, CHANNELS_PATH(creds.store_id), ADD_CTA)++ const suffix = Date.now()+ const name = `E2E Channel Routing ${suffix}`++ await createChannel(page, { name })+ await expect(rowButton(page, name)).toBeVisible({ timeout: 15_000 })++ await rowButton(page, name).click()+ await expect(page.getByRole('heading', { name })).toBeVisible({ timeout: 15_000 })++ // A new channel seeds its three default rules in priority order.+ const ruleRow = (label: string | RegExp) => page.locator('li', { hasText: label })+ await expect(ruleRow(/preferred location/i)).toBeVisible({ timeout: 15_000 })+ await expect(ruleRow(/minimize splits/i)).toBeVisible()+ await expect(ruleRow(/default location/i)).toBeVisible()++ // Every built-in kind is already on the channel — nothing left to add.+ await expect(page.getByRole('button', { name: /add rule/i })).toHaveCount(0)++ // The editor only applies to the Rules strategy — switching to Legacy hides it.+ // Wait for the select popup to fully close after each pick so a lingering+ // overlay can't intercept the next click. (No Escape here — the popup+ // closes on selection, and a stray Escape would close the sheet instead.)+ await page.locator('#preferred_order_routing_strategy').click()+ await page.getByRole('option', { name: /^legacy$/i }).click()+ await expect(page.getByRole('listbox')).toBeHidden()+ await expect(page.getByText(/order routing rules/i)).toHaveCount(0)+ await page.locator('#preferred_order_routing_strategy').click()+ await page.getByRole('option', { name: /^rules \(ordered\)$/i }).click()+ await expect(page.getByRole('listbox')).toBeHidden()+ await expect(ruleRow(/preferred location/i)).toBeVisible()++ // Toggle a rule off — the switch state must survive the refetch.+ const preferredSwitch = ruleRow(/preferred location/i).getByRole('switch')+ await expect(preferredSwitch).toBeChecked()+ await preferredSwitch.click()+ await expect(preferredSwitch).not.toBeChecked({ timeout: 15_000 })++ // Delete a rule (confirm dialog on top of the sheet).+ await ruleRow(/default location/i)+ .getByRole('button', { name: /^delete$/i })+ .click()+ await expect(page.getByRole('heading', { name: /delete routing rule\?/i })).toBeVisible()+ await page+ .getByRole('dialog')+ .filter({ hasText: /delete routing rule\?/i })+ .getByRole('button', { name: /^delete$/i })+ .click()+ await expect(ruleRow(/default location/i)).toHaveCount(0, { timeout: 15_000 })++ // Deleting freed up a kind, so the add button reappears — and the picker+ // offers only the missing kind.+ await page.getByRole('button', { name: /add rule/i }).click()+ await expect(page.getByRole('button', { name: /minimize splits/i })).toHaveCount(0)+ await page.getByRole('button', { name: /prefer the stock location marked as default/i }).click()+ await expect(ruleRow(/default location/i)).toBeVisible({ timeout: 15_000 })++ // All kinds used again — the add affordance goes away.+ await expect(page.getByRole('button', { name: /add rule/i })).toHaveCount(0)+ })+test('deletes a non-default channel', async ({ page }) => {const creds = await login(page)await gotoIndex(page, CHANNELS_PATH(creds.store_id), ADD_CTA)diff --git a/packages/dashboard/src/components/spree/order-routing-rules-section.tsx b/packages/dashboard/src/components/spree/order-routing-rules-section.tsxnew file mode 100644index 0000000000..eb58a38412--- /dev/null+++ b/packages/dashboard/src/components/spree/order-routing-rules-section.tsx@@ -0,0 +1,340 @@+import {+ closestCenter,+ DndContext,+ type DragEndEvent,+ KeyboardSensor,+ PointerSensor,+ useSensor,+ useSensors,+} from '@dnd-kit/core'+import {+ arrayMove,+ SortableContext,+ sortableKeyboardCoordinates,+ useSortable,+ verticalListSortingStrategy,+} from '@dnd-kit/sortable'+import { CSS } from '@dnd-kit/utilities'+import type { OrderRoutingRule, PaginatedResponse, ResourceTypeDefinition } from '@spree/admin-sdk'+import {+ Can,+ PreferencesForm,+ Subject,+ usePermissions,+ useResourceKeyBuilder,+} from '@spree/dashboard-core'+import { Button, DragHandle, Switch, useConfirm } from '@spree/dashboard-ui'+import { useQueryClient } from '@tanstack/react-query'+import { PlusIcon, SlidersHorizontalIcon, Trash2Icon } from 'lucide-react'+import { type CSSProperties, useMemo, useState } from 'react'+import { useTranslation } from 'react-i18next'+import {+ useCreateOrderRoutingRule,+ useDeleteOrderRoutingRule,+ useOrderRoutingRules,+ useOrderRoutingRuleTypes,+ useUpdateOrderRoutingRule,+} from '../../hooks/use-order-routing-rules'+import { typeDescription, typeLabel } from '../../lib/type-labels'++/**+ * Per-channel routing-rules editor rendered inside the channel edit sheet.+ * Rules persist through direct per-rule mutations (not the surrounding+ * channel form), so every button here must stay `type="button"` — the+ * section lives inside the channel form element.+ */+export function OrderRoutingRulesSection({ channelId }: { channelId: string }) {+ const { t } = useTranslation()+ const { data, isLoading } = useOrderRoutingRules(channelId)+ const { data: typesData } = useOrderRoutingRuleTypes()+ const createMutation = useCreateOrderRoutingRule(channelId)+ const updateMutation = useUpdateOrderRoutingRule(channelId)+ const deleteMutation = useDeleteOrderRoutingRule(channelId)+ const confirm = useConfirm()+ const queryClient = useQueryClient()+ const buildKey = useResourceKeyBuilder()+ const { permissions } = usePermissions()++ const rules = data?.data ?? []+ // Rule kinds are unique per channel (DB-enforced) — only offer what's left.+ const availableTypes = useMemo(() => {+ const usedTypes = new Set(rules.map((r) => r.type))+ return (typesData?.data ?? []).filter((t) => !usedTypes.has(t.type))+ }, [rules, typesData])+ const canUpdate = permissions.can('update', Subject.OrderRoutingRule)++ const [showPicker, setShowPicker] = useState(false)+ const [editingId, setEditingId] = useState<string | null>(null)++ const sensors = useSensors(+ useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),+ useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),+ )++ function handleDragEnd(event: DragEndEvent) {+ const { active, over } = event+ if (!over || active.id === over.id) return+ const fromIndex = rules.findIndex((r) => r.id === active.id)+ const toIndex = rules.findIndex((r) => r.id === over.id)+ if (fromIndex === -1 || toIndex === -1) return++ // Reorder the cache first so the row doesn't snap back while the PATCH+ // runs; the mutation's invalidation then restores canonical positions.+ // On failure, restore the pre-drag snapshot — success-only invalidation+ // would otherwise leave the never-persisted order on screen.+ const listKey = buildKey('channels', channelId, 'order-routing-rules')+ const snapshot = queryClient.getQueryData<PaginatedResponse<OrderRoutingRule>>(listKey)+ const next = arrayMove(rules, fromIndex, toIndex).map((r, i) => ({ ...r, position: i + 1 }))+ queryClient.setQueryData(listKey, (prev: PaginatedResponse<OrderRoutingRule> | undefined) =>+ prev ? { ...prev, data: next } : prev,+ )+ updateMutation.mutate(+ { id: String(active.id), params: { position: toIndex + 1 } },+ { onError: () => queryClient.setQueryData(listKey, snapshot) },+ )+ }++ async function handleDelete(rule: OrderRoutingRule) {+ const ok = await confirm({+ title: t('admin.pages.channels.order_routing_rules.delete_confirm.title'),+ message: t('admin.pages.channels.order_routing_rules.delete_confirm.message', {+ name: typeLabel('order_routing_rule_types', rule.type, rule.label),+ }),+ variant: 'destructive',+ confirmLabel: t('admin.actions.delete'),+ })+ if (!ok) return+ if (editingId === rule.id) setEditingId(null)+ await deleteMutation.mutateAsync(rule.id).catch(() => undefined)+ }++ return (+ <div className="flex flex-col gap-2 border-t pt-4">+ <div>+ <span className="text-sm font-medium">+ {t('admin.pages.channels.order_routing_rules.title')}+ </span>+ <p className="text-xs text-muted-foreground">+ {t('admin.pages.channels.order_routing_rules.help')}+ </p>+ </div>++ {isLoading ? (+ <p className="text-sm text-muted-foreground">{t('admin.common.loading')}</p>+ ) : rules.length === 0 ? (+ <p className="text-sm text-muted-foreground">+ {t('admin.pages.channels.order_routing_rules.empty')}+ </p>+ ) : (+ <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>+ <SortableContext items={rules.map((r) => r.id)} strategy={verticalListSortingStrategy}>+ <ul className="flex flex-col gap-1">+ {rules.map((rule) => (+ <SortableRuleRow+ key={rule.id}+ rule={rule}+ canUpdate={canUpdate}+ canDestroy={permissions.can('destroy', Subject.OrderRoutingRule)}+ editing={editingId === rule.id}+ onToggleActive={(active) =>+ updateMutation.mutate({ id: rule.id, params: { active } })+ }+ onToggleEdit={() => setEditingId(editingId === rule.id ? null : rule.id)}+ onSavePreferences={(preferences) => {+ updateMutation.mutate({ id: rule.id, params: { preferences } })+ setEditingId(null)+ }}+ onDelete={() => handleDelete(rule)}+ />+ ))}+ </ul>+ </SortableContext>+ </DndContext>+ )}++ {!isLoading && availableTypes.length > 0 && (+ <Can I="create" a={Subject.OrderRoutingRule}>+ {showPicker ? (+ <RuleTypePicker+ types={availableTypes}+ disabled={createMutation.isPending}+ onPick={(type) => {+ createMutation.mutate({ type: type.type })+ setShowPicker(false)+ }}+ onCancel={() => setShowPicker(false)}+ />+ ) : (+ <Button+ type="button"+ variant="outline"+ size="sm"+ className="self-start"+ onClick={() => setShowPicker(true)}+ >+ <PlusIcon className="size-4" />+ {t('admin.pages.channels.order_routing_rules.add_cta')}+ </Button>+ )}+ </Can>+ )}+ </div>+ )+}++function SortableRuleRow({+ rule,+ canUpdate,+ canDestroy,+ editing,+ onToggleActive,+ onToggleEdit,+ onSavePreferences,+ onDelete,+}: {+ rule: OrderRoutingRule+ canUpdate: boolean+ canDestroy: boolean+ editing: boolean+ onToggleActive: (active: boolean) => void+ onToggleEdit: () => void+ onSavePreferences: (preferences: Record<string, unknown>) => void+ onDelete: () => void+}) {+ const { t } = useTranslation()+ const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({+ id: rule.id,+ disabled: !canUpdate,+ })+ const style: CSSProperties = { transform: CSS.Transform.toString(transform), transition }+ const hasPreferences = rule.preference_schema.length > 0+ const label = typeLabel('order_routing_rule_types', rule.type, rule.label)+ const description = typeDescription('order_routing_rule_types', rule.type, rule.description)++ return (+ <li+ ref={setNodeRef}+ style={style}+ className={`rounded-md border bg-card ${isDragging ? 'relative z-10 opacity-80 shadow-lg' : ''}`}+ >+ <div className="flex items-center gap-2 p-2">+ {canUpdate && (+ <span className="w-6 touch-none">+ <DragHandle attributes={attributes} listeners={listeners} />+ </span>+ )}+ <div className="min-w-0 flex-1">+ <span className="block truncate text-sm" title={description || undefined}>+ {label}+ </span>+ </div>+ {hasPreferences && canUpdate && (+ <Button+ type="button"+ variant="ghost"+ size="icon-sm"+ aria-label={t('admin.pages.channels.order_routing_rules.edit_preferences')}+ onClick={onToggleEdit}+ >+ <SlidersHorizontalIcon className="size-4" />+ </Button>+ )}+ <Switch+ checked={rule.active}+ onCheckedChange={onToggleActive}+ disabled={!canUpdate}+ aria-label={t('admin.pages.channels.order_routing_rules.active_toggle')}+ />+ {canDestroy && (+ <Button+ type="button"+ variant="ghost"+ size="icon-sm"+ aria-label={t('admin.actions.delete')}+ onClick={onDelete}+ >+ <Trash2Icon className="size-4 text-destructive" />+ </Button>+ )}+ </div>+ {editing && hasPreferences && (+ <RulePreferencesEditor rule={rule} onSave={onSavePreferences} onCancel={onToggleEdit} />+ )}+ </li>+ )+}++function RulePreferencesEditor({+ rule,+ onSave,+ onCancel,+}: {+ rule: OrderRoutingRule+ onSave: (preferences: Record<string, unknown>) => void+ onCancel: () => void+}) {+ const { t } = useTranslation()+ const [values, setValues] = useState<Record<string, unknown>>(rule.preferences ?? {})++ return (+ <div className="flex flex-col gap-3 border-t p-3">+ <PreferencesForm schema={rule.preference_schema} values={values} onChange={setValues} />+ <div className="flex justify-end gap-2">+ <Button type="button" variant="outline" size="sm" onClick={onCancel}>+ {t('admin.actions.cancel')}+ </Button>+ <Button type="button" size="sm" onClick={() => onSave(values)}>+ {t('admin.actions.save')}+ </Button>+ </div>+ </div>+ )+}++function RuleTypePicker({+ types,+ disabled,+ onPick,+ onCancel,+}: {+ types: ResourceTypeDefinition[]+ disabled: boolean+ onPick: (type: ResourceTypeDefinition) => void+ onCancel: () => void+}) {+ const { t } = useTranslation()++ return (+ <div className="flex flex-col gap-1 rounded-md border p-2">+ <span className="px-1 text-xs font-medium text-muted-foreground">+ {t('admin.pages.channels.order_routing_rules.picker_title')}+ </span>+ {types.map((type) => {+ const description = typeDescription(+ 'order_routing_rule_types',+ type.type,+ type.description ?? '',+ )+ return (+ <button+ key={type.type}+ type="button"+ disabled={disabled}+ className="rounded-md px-2 py-1.5 text-left hover:bg-accent disabled:opacity-50"+ onClick={() => onPick(type)}+ >+ <span className="block text-sm">+ {typeLabel('order_routing_rule_types', type.type, type.label)}+ </span>+ {description && (+ <span className="block text-xs text-muted-foreground">{description}</span>+ )}+ </button>+ )+ })}+ <Button type="button" variant="ghost" size="sm" className="self-start" onClick={onCancel}>+ {t('admin.actions.cancel')}+ </Button>+ </div>+ )+}diff --git a/packages/dashboard/src/hooks/use-order-routing-rules.ts b/packages/dashboard/src/hooks/use-order-routing-rules.tsnew file mode 100644index 0000000000..0ce298e13b--- /dev/null+++ b/packages/dashboard/src/hooks/use-order-routing-rules.ts@@ -0,0 +1,60 @@+import type {+ OrderRoutingRule,+ OrderRoutingRuleCreateParams,+ OrderRoutingRuleUpdateParams,+} from '@spree/admin-sdk'+import { adminClient, useResourceKey, useResourceMutation } from '@spree/dashboard-core'+import { useQuery } from '@tanstack/react-query'+import i18n from 'i18next'++export function useOrderRoutingRules(channelId: string | undefined) {+ return useQuery({+ queryKey: useResourceKey('channels', channelId ?? 'noop', 'order-routing-rules'),+ queryFn: () =>+ adminClient.channels.orderRoutingRules.list(channelId as string, {+ limit: 100,+ sort: 'position',+ }),+ enabled: !!channelId,+ })+}++// The rule-kind registry is static at runtime — cache forever, not store-scoped.+export function useOrderRoutingRuleTypes() {+ return useQuery({+ queryKey: ['order-routing-rules', 'types'],+ queryFn: () => adminClient.orderRoutingRules.types(),+ staleTime: Number.POSITIVE_INFINITY,+ })+}++export function useCreateOrderRoutingRule(channelId: string) {+ return useResourceMutation<OrderRoutingRule, Error, OrderRoutingRuleCreateParams>({+ mutationFn: (params) => adminClient.channels.orderRoutingRules.create(channelId, params),+ invalidate: [['channels', channelId, 'order-routing-rules']],+ successMessage: i18n.t('admin.order_routing_rules.messages.created'),+ errorMessage: i18n.t('admin.errors.failed_to_create'),+ })+}++export function useUpdateOrderRoutingRule(channelId: string) {+ return useResourceMutation<+ OrderRoutingRule,+ Error,+ { id: string; params: OrderRoutingRuleUpdateParams }+ >({+ mutationFn: ({ id, params }) =>+ adminClient.channels.orderRoutingRules.update(channelId, id, params),+ invalidate: [['channels', channelId, 'order-routing-rules']],+ errorMessage: i18n.t('admin.errors.failed_to_update'),+ })+}++export function useDeleteOrderRoutingRule(channelId: string) {+ return useResourceMutation<void, Error, string>({+ mutationFn: (id) => adminClient.channels.orderRoutingRules.delete(channelId, id),+ invalidate: [['channels', channelId, 'order-routing-rules']],+ successMessage: i18n.t('admin.order_routing_rules.messages.deleted'),+ errorMessage: i18n.t('admin.errors.failed_to_delete'),+ })+}diff --git a/packages/dashboard/src/lib/type-labels.ts b/packages/dashboard/src/lib/type-labels.tsindex f577e87bee..f668e80dba 100644--- a/packages/dashboard/src/lib/type-labels.ts+++ b/packages/dashboard/src/lib/type-labels.ts@@ -7,13 +7,15 @@ import i18n from 'i18next'* back to the API's English string for custom/extension types that ship no* translation.*/-export type TypeFamily = 'rule_types' | 'action_types' | 'calculators'+export type TypeFamily = 'rule_types' | 'action_types' | 'calculators' | 'order_routing_rule_types'function i18nKey(family: TypeFamily, code: string, facet: 'name' | 'description'): string {// Calculators expose a single flat string (no separate description), so// their key is `admin.calculators.<code>`. Rule/action types nest// `name` and `description` under their code.if (family === 'calculators') return `admin.calculators.${code}`+ if (family === 'order_routing_rule_types')+ return `admin.order_routing_rules.types.${code}.${facet}`return `admin.promotions.${family}.${code}.${facet}`}diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.jsonindex 93e6c38f3b..d98e9ff105 100644--- a/packages/dashboard/src/locales/ar.json+++ b/packages/dashboard/src/locales/ar.json@@ -1129,6 +1129,19 @@"title": "هل تريد حذف قناة المبيعات؟","message": "ستتم إزالة {{name}}. ستفقد المنتجات والأوامر المرتبطة بها مرجع قناة المبيعات الخاصة بها."},+ "order_routing_rules": {+ "title": "قواعد توجيه الطلبات",+ "help": "عند استخدام استراتيجية التوجيه «قواعد (مرتبة)»، تُقيَّم القواعد من الأعلى إلى الأسفل — تفوز أول قاعدة تحدد موقع مخزون واحدًا، وعند التعادل تُحسم بالقاعدة التالية.",+ "empty": "لا توجد قواعد توجيه — تُوجَّه الطلبات إلى موقع المخزون الافتراضي.",+ "add_cta": "إضافة قاعدة",+ "picker_title": "إضافة قاعدة توجيه",+ "edit_preferences": "تعديل إعدادات القاعدة",+ "active_toggle": "القاعدة مفعّلة",+ "delete_confirm": {+ "title": "حذف قاعدة التوجيه؟",+ "message": "ستتم إزالة {{name}} من ترتيب التوجيه لهذه القناة."+ }+ },"search_placeholder": "البحث في قنوات البيع…","no_channels_found": "لم يتم العثور على قنوات البيع","validation": {@@ -2517,6 +2530,26 @@"deleted": "تم حذف القناة"}},+ "order_routing_rules": {+ "messages": {+ "created": "تمت إضافة قاعدة التوجيه",+ "deleted": "تمت إزالة قاعدة التوجيه"+ },+ "types": {+ "preferred_location": {+ "name": "الموقع المفضل",+ "description": "الشحن من الموقع المثبّت على الطلب إن وُجد"+ },+ "minimize_splits": {+ "name": "تقليل تقسيم الشحنات",+ "description": "يفضّل الموقع القادر على تلبية أكبر عدد من العناصر بمفرده لتجنّب تقسيم الشحنات"+ },+ "default_location": {+ "name": "الموقع الافتراضي",+ "description": "يفضّل موقع المخزون المحدد كافتراضي"+ }+ }+ },"customer_groups": {"messages": {"created": "تم إنشاء مجموعة العميل",diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.jsonindex ece38a7418..63d8169e97 100644--- a/packages/dashboard/src/locales/de.json+++ b/packages/dashboard/src/locales/de.json@@ -1081,6 +1081,19 @@"title": "Verkaufskanal löschen?","message": "{{name}} wird entfernt. Damit verknüpfte Produkte und Bestellungen verlieren ihre Verkaufskanal-Referenz."},+ "order_routing_rules": {+ "title": "Auftragsrouting-Regeln",+ "help": "Bei der Routing-Strategie „Regeln (geordnet)“ werden die Regeln von oben nach unten ausgewertet – die erste Regel, die einen Lagerort eindeutig bestimmt, gewinnt; bei Gleichstand entscheidet die nächste Regel.",+ "empty": "Keine Routing-Regeln – Bestellungen verwenden den Standard-Lagerort.",+ "add_cta": "Regel hinzufügen",+ "picker_title": "Routing-Regel hinzufügen",+ "edit_preferences": "Regel-Einstellungen bearbeiten",+ "active_toggle": "Regel aktiv",+ "delete_confirm": {+ "title": "Routing-Regel löschen?",+ "message": "{{name}} wird aus der Routing-Reihenfolge dieses Kanals entfernt."+ }+ },"search_placeholder": "Verkaufskanäle suchen…","no_channels_found": "Keine Verkaufskanäle gefunden","validation": {@@ -2517,6 +2530,26 @@"deleted": "Kanal gelöscht"}},+ "order_routing_rules": {+ "messages": {+ "created": "Routing-Regel hinzugefügt",+ "deleted": "Routing-Regel entfernt"+ },+ "types": {+ "preferred_location": {+ "name": "Bevorzugter Lagerort",+ "description": "Versand vom am Auftrag hinterlegten Lagerort, sofern gesetzt"+ },+ "minimize_splits": {+ "name": "Teillieferungen minimieren",+ "description": "Bevorzugt den Lagerort, der die meisten Artikel allein liefern kann, und vermeidet Teillieferungen"+ },+ "default_location": {+ "name": "Standard-Lagerort",+ "description": "Bevorzugt den als Standard markierten Lagerort"+ }+ }+ },"customer_groups": {"messages": {"created": "Kundengruppe erstellt",diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.jsonindex 2fe840a2a9..68d2a4a858 100644--- a/packages/dashboard/src/locales/en.json+++ b/packages/dashboard/src/locales/en.json@@ -1129,6 +1129,19 @@"title": "Delete sales channel?","message": "{{name}} will be removed. Products and orders attached to it will lose their sales-channel reference."},+ "order_routing_rules": {+ "title": "Order routing rules",+ "help": "When the routing strategy is Rules (ordered), rules are evaluated top to bottom — the first rule that singles out a stock location wins, and ties carry to the next rule.",+ "empty": "No routing rules — orders fall back to the default stock location.",+ "add_cta": "Add rule",+ "picker_title": "Add a routing rule",+ "edit_preferences": "Edit rule settings",+ "active_toggle": "Rule active",+ "delete_confirm": {+ "title": "Delete routing rule?",+ "message": "{{name}} will be removed from this channel's routing order."+ }+ },"search_placeholder": "Search sales channels…","no_channels_found": "No sales channels found","validation": {@@ -2517,6 +2530,26 @@"deleted": "Channel deleted"}},+ "order_routing_rules": {+ "messages": {+ "created": "Routing rule added",+ "deleted": "Routing rule removed"+ },+ "types": {+ "preferred_location": {+ "name": "Preferred location",+ "description": "Fulfill from the location pinned on the order, when one is set"+ },+ "minimize_splits": {+ "name": "Minimize splits",+ "description": "Prefer the location that can fulfill the most items on its own, avoiding split shipments"+ },+ "default_location": {+ "name": "Default location",+ "description": "Prefer the stock location marked as default"+ }+ }+ },"customer_groups": {"messages": {"created": "Customer group created",diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.jsonindex cfcb224f38..bf2434a2ba 100644--- a/packages/dashboard/src/locales/fr.json+++ b/packages/dashboard/src/locales/fr.json@@ -1081,6 +1081,19 @@"title": "Supprimer le canal de vente ?","message": "{{name}} sera supprimé. Les produits et commandes qui y sont rattachés perdront leur référence de canal de vente."},+ "order_routing_rules": {+ "title": "Règles de routage des commandes",+ "help": "Avec la stratégie de routage « Règles (ordonnées) », les règles sont évaluées de haut en bas — la première règle qui désigne un seul lieu de stock l'emporte ; en cas d'égalité, la règle suivante départage.",+ "empty": "Aucune règle de routage — les commandes utilisent le lieu de stock par défaut.",+ "add_cta": "Ajouter une règle",+ "picker_title": "Ajouter une règle de routage",+ "edit_preferences": "Modifier les paramètres de la règle",+ "active_toggle": "Règle active",+ "delete_confirm": {+ "title": "Supprimer la règle de routage ?",+ "message": "{{name}} sera retirée de l'ordre de routage de ce canal."+ }+ },"search_placeholder": "Rechercher des canaux de vente…","no_channels_found": "Aucun canal de vente trouvé","validation": {@@ -2517,6 +2530,26 @@"deleted": "Canal supprimé"}},+ "order_routing_rules": {+ "messages": {+ "created": "Règle de routage ajoutée",+ "deleted": "Règle de routage supprimée"+ },+ "types": {+ "preferred_location": {+ "name": "Lieu de stock préféré",+ "description": "Expédier depuis le lieu épinglé sur la commande, s'il est défini"+ },+ "minimize_splits": {+ "name": "Minimiser les envois fractionnés",+ "description": "Privilégie le lieu capable d'expédier le plus d'articles à lui seul, évitant les envois fractionnés"+ },+ "default_location": {+ "name": "Lieu de stock par défaut",+ "description": "Privilégie le lieu de stock marqué comme défaut"+ }+ }+ },"customer_groups": {"messages": {"created": "Groupe de clients créé",diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.jsonindex aeeecf2f5c..decc35a8fc 100644--- a/packages/dashboard/src/locales/pl.json+++ b/packages/dashboard/src/locales/pl.json@@ -1081,6 +1081,19 @@"title": "Usunąć kanał sprzedaży?","message": "{{name}} zostanie usunięty. Produkty i zamówienia z nim powiązane stracą odniesienie do kanału sprzedaży."},+ "order_routing_rules": {+ "title": "Reguły routingu zamówień",+ "help": "Przy strategii routingu „Reguły (uporządkowane)” reguły są oceniane od góry do dołu — wygrywa pierwsza reguła, która jednoznacznie wskaże lokalizację magazynową; przy remisie decyduje kolejna reguła.",+ "empty": "Brak reguł routingu — zamówienia trafiają do domyślnej lokalizacji magazynowej.",+ "add_cta": "Dodaj regułę",+ "picker_title": "Dodaj regułę routingu",+ "edit_preferences": "Edytuj ustawienia reguły",+ "active_toggle": "Reguła aktywna",+ "delete_confirm": {+ "title": "Usunąć regułę routingu?",+ "message": "{{name}} zostanie usunięta z kolejności routingu tego kanału."+ }+ },"search_placeholder": "Szukaj kanałów sprzedaży…","no_channels_found": "Nie znaleziono kanałów sprzedaży","validation": {@@ -2549,6 +2562,26 @@"deleted": "Kanał usunięty"}},+ "order_routing_rules": {+ "messages": {+ "created": "Dodano regułę routingu",+ "deleted": "Usunięto regułę routingu"+ },+ "types": {+ "preferred_location": {+ "name": "Preferowana lokalizacja",+ "description": "Realizuj z lokalizacji przypiętej do zamówienia, jeśli została ustawiona"+ },+ "minimize_splits": {+ "name": "Minimalizuj podziały",+ "description": "Preferuje lokalizację, która samodzielnie zrealizuje najwięcej pozycji, unikając dzielenia przesyłek"+ },+ "default_location": {+ "name": "Domyślna lokalizacja",+ "description": "Preferuje lokalizację magazynową oznaczoną jako domyślna"+ }+ }+ },"customer_groups": {"messages": {"created": "Utworzono grupę klientów",diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.jsonindex 6c6f8c8637..c864f6e1e1 100644--- a/packages/dashboard/src/locales/zh-CN.json+++ b/packages/dashboard/src/locales/zh-CN.json@@ -1129,6 +1129,19 @@"title": "删除销售渠道?","message": "{{name}} 将被移除。关联到该渠道的商品和订单将失去其销售渠道引用。"},+ "order_routing_rules": {+ "title": "订单路由规则",+ "help": "当路由策略为“规则(有序)”时,规则自上而下依次评估——第一个能唯一确定库存地点的规则胜出;平局则由下一条规则决定。",+ "empty": "暂无路由规则——订单将使用默认库存地点。",+ "add_cta": "添加规则",+ "picker_title": "添加路由规则",+ "edit_preferences": "编辑规则设置",+ "active_toggle": "规则已启用",+ "delete_confirm": {+ "title": "删除路由规则?",+ "message": "{{name}} 将从此渠道的路由顺序中移除。"+ }+ },"search_placeholder": "搜索销售渠道…","no_channels_found": "未找到销售渠道","validation": {@@ -2517,6 +2530,26 @@"deleted": "渠道已删除"}},+ "order_routing_rules": {+ "messages": {+ "created": "已添加路由规则",+ "deleted": "已移除路由规则"+ },+ "types": {+ "preferred_location": {+ "name": "首选库存地点",+ "description": "如订单已指定库存地点,则从该地点发货"+ },+ "minimize_splits": {+ "name": "减少拆单",+ "description": "优先选择能独立满足最多商品的地点,避免拆分发货"+ },+ "default_location": {+ "name": "默认库存地点",+ "description": "优先选择标记为默认的库存地点"+ }+ }+ },"customer_groups": {"messages": {"created": "客户组已创建",diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/channels.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/channels.tsxindex 70115dc4a6..155f03b6a0 100644--- a/packages/dashboard/src/routes/_authenticated/$storeId/settings/channels.tsx+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/channels.tsx@@ -8,6 +8,7 @@ import {resourceSearchSchema,Subject,usePermissions,+ useStore,} from '@spree/dashboard-core'import {Button,@@ -38,6 +39,7 @@ import { useEffect } from 'react'import { Controller, type UseFormReturn, useForm } from 'react-hook-form'import { useTranslation } from 'react-i18next'import { z } from 'zod/v4'+import { OrderRoutingRulesSection } from '../../../../components/spree/order-routing-rules-section'import {useChannel,useCreateChannel,@@ -51,6 +53,7 @@ import {channelValuesToParams,GUEST_CHECKOUT_VALUES,ORDER_ROUTING_STRATEGY_VALUES,+ RULES_ORDER_ROUTING_STRATEGY,STOREFRONT_ACCESS_VALUES,} from '../../../../schemas/channel'import '../../../../tables/channels'@@ -237,6 +240,7 @@ function EditChannelSheet({const { t } = useTranslation()const { data: channel, isLoading } = useChannel(id)const updateMutation = useUpdateChannel(id)+ const { store } = useStore()const form = useForm<ChannelFormValues>({// eslint-disable-next-line @typescript-eslint/no-explicit-any@@ -244,6 +248,13 @@ function EditChannelSheet({defaultValues: CHANNEL_DEFAULTS,})+ // The rules editor only makes sense under the Rules strategy. Resolve the+ // effective strategy live from the (unsaved) select value, falling back to+ // the store-level preference for the "inherit" option.+ const strategyOverride = form.watch('preferred_order_routing_strategy')+ const effectiveStrategy =+ strategyOverride || store?.preferred_order_routing_strategy || RULES_ORDER_ROUTING_STRATEGY+useEffect(() => {if (channel) {form.reset({@@ -282,6 +293,9 @@ function EditChannelSheet({<form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col"><div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4"><ChannelFormFields form={form} />+ {effectiveStrategy === RULES_ORDER_ROUTING_STRATEGY && (+ <OrderRoutingRulesSection channelId={id} />+ )}</div><SheetFooter><Buttondiff --git a/packages/dashboard/src/schemas/channel.ts b/packages/dashboard/src/schemas/channel.tsindex ead82550a5..d4709aeb86 100644--- a/packages/dashboard/src/schemas/channel.ts+++ b/packages/dashboard/src/schemas/channel.ts@@ -4,9 +4,11 @@ import i18n from 'i18next'import { z } from 'zod/v4'// Empty string clears the channel-level override → falls back to store.+export const RULES_ORDER_ROUTING_STRATEGY = 'Spree::OrderRouting::Strategy::Rules'+export const ORDER_ROUTING_STRATEGY_VALUES = ['',- 'Spree::OrderRouting::Strategy::Rules',+ RULES_ORDER_ROUTING_STRATEGY,'Spree::OrderRouting::Strategy::Legacy',] as constdiff --git a/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb b/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rbindex cf019f45cb..ce59c7530d 100644--- a/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb+++ b/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb@@ -86,10 +86,15 @@ module Spreeself.class._scoped_resourceend- # Override in controllers with non-REST custom actions (e.g. dashboard- # `analytics` should map to a read).+ # Maps the action to the scope kind. Consults the controller's+ # `read_actions` (ResourceController's overridable list) when defined,+ # so declaring a custom read-only action once — e.g. `types` — fixes+ # both the CanCanCan action mapping and the required scope kind.+ # Controllers outside the ResourceController hierarchy can still+ # override `action_kind` directly (e.g. dashboard `analytics`).def action_kind- READ_ACTIONS.include?(action_name) ? 'read' : 'write'+ read = respond_to?(:read_actions, true) ? read_actions : READ_ACTIONS+ read.include?(action_name) ? 'read' : 'write'end# True when authorization derives from the API key's scopes ratherdiff --git a/spree/api/app/controllers/spree/api/v3/admin/order_routing_rules_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/order_routing_rules_controller.rbnew file mode 100644index 0000000000..24df26f3c8--- /dev/null+++ b/spree/api/app/controllers/spree/api/v3/admin/order_routing_rules_controller.rb@@ -0,0 +1,65 @@+module Spree+ module Api+ module V3+ module Admin+ # CRUD for `Spree::OrderRoutingRule` STI subclasses, nested under the+ # owning channel. Same shape as PromotionRulesController — the registry+ # is `Spree.order_routing.rules` and the parent is a Channel.+ class OrderRoutingRulesController < ResourceController+ include Spree::Api::V3::Admin::SubclassedResource++ scoped_resource :settings++ subclassed_via -> { Spree.order_routing.rules },+ unknown_type_error: 'unknown_order_routing_rule_type'++ def types+ authorize! :read, model_class++ render json: { data: model_class.subclasses_with_preference_schema }+ end++ protected++ def model_class+ Spree::OrderRoutingRule+ end++ def serializer_class+ Spree.api.admin_order_routing_rule_serializer+ end++ def permitted_params+ params.permit(:type, :active, :position, preferences: {})+ end++ # `types` is read-only discovery — maps to the read scope + :show ability.+ def read_actions+ super + %w[types]+ end++ def scope+ super.ordered+ end++ def set_parent+ return if action_name == 'types'++ @parent = current_store.channels.accessible_by(current_ability, parent_ability_action)+ .find_by_prefix_id!(params[:channel_id])+ end++ def parent_association+ :order_routing_rules+ end++ private++ def build_subclassed_resource(klass, attrs)+ klass.new(attrs.merge(channel: @parent, store: @parent.store))+ end+ end+ end+ end+ end+enddiff --git a/spree/api/app/controllers/spree/api/v3/admin/payment_methods_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/payment_methods_controller.rbindex 2429d64cde..b04f4312ca 100644--- a/spree/api/app/controllers/spree/api/v3/admin/payment_methods_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/payment_methods_controller.rb@@ -51,6 +51,11 @@ module Spreeparams.permit(:name, :description, :active, :storefront_visible, :auto_capture, :position, metadata: {}, preferences: {})end+ # `types` is read-only discovery — maps to the read scope + :show ability.+ def read_actions+ super + %w[types]+ end+private# New payment methods are created through the current store.diff --git a/spree/api/app/controllers/spree/api/v3/admin/promotion_actions_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/promotion_actions_controller.rbindex ffaf25ad0a..f8161e76b4 100644--- a/spree/api/app/controllers/spree/api/v3/admin/promotion_actions_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/promotion_actions_controller.rb@@ -55,6 +55,11 @@ module Spreeparams.permit(:type, preferences: {})end+ # `types`/`calculators` are read-only discovery — read scope + :show ability.+ def read_actions+ super + %w[types calculators]+ end+def set_parentreturn if %w[types calculators].include?(action_name)diff --git a/spree/api/app/controllers/spree/api/v3/admin/promotion_rules_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/promotion_rules_controller.rbindex 239642c793..9aa9dd5bee 100644--- a/spree/api/app/controllers/spree/api/v3/admin/promotion_rules_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/promotion_rules_controller.rb@@ -33,6 +33,11 @@ module Spreeparams.permit(:type, preferences: {})end+ # `types` is read-only discovery — maps to the read scope + :show ability.+ def read_actions+ super + %w[types]+ end+def set_parentreturn if action_name == 'types'diff --git a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rbindex caf5b31f86..1f8e029987 100644--- a/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb+++ b/spree/api/app/controllers/spree/api/v3/admin/store_controller.rb@@ -42,6 +42,7 @@ module Spree:preferred_storefront_access,:preferred_storefront_url,:preferred_guest_checkout,+ :preferred_order_routing_strategy,:mail_from_address,:customer_support_email,:new_order_notifications_email,diff --git a/spree/api/app/serializers/spree/api/v3/admin/order_routing_rule_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/order_routing_rule_serializer.rbnew file mode 100644index 0000000000..221b708744--- /dev/null+++ b/spree/api/app/serializers/spree/api/v3/admin/order_routing_rule_serializer.rb@@ -0,0 +1,40 @@+# frozen_string_literal: true++module Spree+ module Api+ module V3+ module Admin+ # Serializes Spree::OrderRoutingRule (and its STI subclasses) for the+ # per-channel routing-rules editor. Same shape as PromotionRule so the+ # frontend renders both with the same schema-driven preference form.+ class OrderRoutingRuleSerializer < BaseSerializer+ typelize type: :string,+ channel_id: :string,+ position: :number,+ active: :boolean,+ preferences: 'Record<string, unknown>',+ preference_schema: "Array<{ key: string; type: string; default: unknown }>",+ label: :string,+ description: :string++ attributes :position, :active+ attributes created_at: :iso8601, updated_at: :iso8601++ attribute :type do |rule|+ rule.class.api_type+ end++ attribute :channel_id do |rule|+ rule.channel&.prefixed_id+ end++ attribute :preferences, &:serialized_preferences+ attribute :preference_schema, &:serialized_preference_schema++ attribute :label, &:human_name+ attribute :description, &:human_description+ end+ end+ end+ end+enddiff --git a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rbindex 16eefc5107..4721e144e3 100644--- a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb+++ b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb@@ -21,6 +21,7 @@ module Spreepreferred_unit_system: :string,preferred_storefront_access: :string,preferred_guest_checkout: :boolean,+ preferred_order_routing_strategy: :string,metadata: 'Record<string, unknown>'attributes :metadata,@@ -39,6 +40,7 @@ module Spree:preferred_unit_system,:preferred_storefront_access,:preferred_guest_checkout,+ :preferred_order_routing_strategy,created_at: :iso8601, updated_at: :iso8601attribute :url, &:storefront_urldiff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rbindex bd6d4ade1a..71ae6e96e5 100644--- a/spree/api/config/routes.rb+++ b/spree/api/config/routes.rb@@ -345,8 +345,15 @@ Spree::Core::Engine.add_routes dopost :add_productspost :remove_productsend++ resources :order_routing_rules, only: [:index, :show, :create, :update, :destroy]end+ # Subclass discovery for the routing-rules editor, mirroring+ # `/promotion_rules/types`. Top-level so the SPA can build the+ # "Add rule" picker without a parent channel.+ get 'order_routing_rules/types', to: 'order_routing_rules#types'+# Variants (top-level, for search/autocomplete across all products)resources :variants, only: [:index, :show], concerns: :custom_fieldablediff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rbindex ba1a3c6a33..9bf95b5f13 100644--- a/spree/api/lib/spree/api/dependencies.rb+++ b/spree/api/lib/spree/api/dependencies.rb@@ -202,6 +202,7 @@ module Spreeadmin_admin_user_serializer: 'Spree::Api::V3::Admin::AdminUserSerializer',admin_address_serializer: 'Spree::Api::V3::Admin::AddressSerializer',admin_channel_serializer: 'Spree::Api::V3::Admin::ChannelSerializer',+ admin_order_routing_rule_serializer: 'Spree::Api::V3::Admin::OrderRoutingRuleSerializer',admin_product_publication_serializer: 'Spree::Api::V3::Admin::ProductPublicationSerializer',admin_market_serializer: 'Spree::Api::V3::Admin::MarketSerializer',admin_shipping_method_serializer: 'Spree::Api::V3::Admin::DeliveryMethodSerializer',diff --git a/spree/api/spec/controllers/spree/api/v3/admin/order_routing_rules_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/order_routing_rules_controller_spec.rbnew file mode 100644index 0000000000..4d0baa17cd--- /dev/null+++ b/spree/api/spec/controllers/spree/api/v3/admin/order_routing_rules_controller_spec.rb@@ -0,0 +1,140 @@+require 'spec_helper'++RSpec.describe Spree::Api::V3::Admin::OrderRoutingRulesController, type: :controller do+ render_views++ include_context 'API v3 Admin authenticated'++ # Channels seed 3 default rules on create (preferred_location,+ # minimize_splits, default_location) — specs below lean on that seed.+ let(:channel) { store.default_channel }++ before { request.headers.merge!(headers) }++ describe 'GET #index' do+ it 'lists the channel rules ordered by position' do+ get :index, params: { channel_id: channel.prefixed_id }, as: :json++ expect(response).to have_http_status(:ok)+ data = json_response[:data]+ expect(data.map { |r| r[:type] }).to eq(%w[preferred_location minimize_splits default_location])+ expect(data.map { |r| r[:position] }).to eq([1, 2, 3])+ end++ it "404s when listing rules of another store's channel" do+ foreign_channel = create(:store).default_channel++ get :index, params: { channel_id: foreign_channel.prefixed_id }, as: :json++ expect(response).to have_http_status(:not_found)+ end+ end++ describe 'POST #create' do+ it 'appends a rule at the end of the list when no position is given' do+ channel.order_routing_rules.find_by(type: 'Spree::OrderRouting::Rules::DefaultLocation').destroy!++ post :create, params: { channel_id: channel.prefixed_id, type: 'default_location' }, as: :json++ expect(response).to have_http_status(:created)+ expect(json_response[:position]).to eq(3)+ expect(json_response[:type]).to eq('default_location')+ expect(json_response[:channel_id]).to eq(channel.prefixed_id)+ end++ it '422s on an unregistered type' do+ post :create, params: { channel_id: channel.prefixed_id, type: 'bogus_rule' }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response[:error][:code]).to eq('unknown_order_routing_rule_type')+ end++ it '422s when the channel already has a rule of that kind' do+ post :create, params: { channel_id: channel.prefixed_id, type: 'default_location' }, as: :json++ expect(response).to have_http_status(:unprocessable_content)+ expect(json_response[:error][:details][:type]).to be_present+ expect(channel.order_routing_rules.count).to eq(3)+ end++ it "404s for a channel that belongs to another store" do+ foreign_channel = create(:store).default_channel++ post :create, params: { channel_id: foreign_channel.prefixed_id, type: 'default_location' }, as: :json++ expect(response).to have_http_status(:not_found)+ expect(foreign_channel.order_routing_rules.count).to eq(3)+ end+ end++ describe 'PATCH #update' do+ let(:rule) { channel.order_routing_rules.ordered.first }++ it 'toggles active' do+ patch :update, params: { channel_id: channel.prefixed_id, id: rule.prefixed_id, active: false }, as: :json++ expect(response).to have_http_status(:ok)+ expect(json_response[:active]).to be(false)+ expect(rule.reload.active).to be(false)+ end++ it 'reorders the list when position changes' do+ patch :update, params: { channel_id: channel.prefixed_id, id: rule.prefixed_id, position: 3 }, as: :json++ expect(response).to have_http_status(:ok)+ expect(channel.order_routing_rules.ordered.map(&:type)).to eq(+ %w[Spree::OrderRouting::Rules::MinimizeSplits+ Spree::OrderRouting::Rules::DefaultLocation+ Spree::OrderRouting::Rules::PreferredLocation]+ )+ end++ it 'cannot switch the STI type' do+ patch :update, params: { channel_id: channel.prefixed_id, id: rule.prefixed_id, type: 'minimize_splits' }, as: :json++ expect(response).to have_http_status(:ok)+ expect(rule.reload.type).to eq('Spree::OrderRouting::Rules::PreferredLocation')+ end+ end++ describe 'DELETE #destroy' do+ it 'removes the rule from the channel' do+ rule = channel.order_routing_rules.ordered.last++ delete :destroy, params: { channel_id: channel.prefixed_id, id: rule.prefixed_id }, as: :json++ expect(response).to have_http_status(:no_content)+ expect(channel.order_routing_rules.count).to eq(2)+ end+ end++ describe 'GET #types' do+ it 'enumerates registered rule kinds with labels and preference schemas' do+ get :types, as: :json++ types = json_response[:data]+ expect(types.map { |t| t[:type] }).to contain_exactly('preferred_location', 'minimize_splits', 'default_location')+ entry = types.find { |t| t[:type] == 'default_location' }+ expect(entry[:label]).to eq('Default location')+ expect(entry[:description]).to be_present+ expect(entry[:preference_schema]).to eq([])+ end++ context 'with a read-only secret API key and no JWT' do+ let(:headers) { api_key_headers }+ let(:secret_api_key) { create(:api_key, :secret, store: store, scopes: ['read_settings']) }++ it 'maps type discovery to the read scope' do+ get :types, as: :json++ expect(response).to have_http_status(:ok)+ end++ it 'still requires the write scope for mutations' do+ post :create, params: { channel_id: channel.prefixed_id, type: 'default_location' }, as: :json++ expect(response).to have_http_status(:forbidden)+ end+ end+ end+enddiff --git a/spree/api/spec/integration/spree/api/v3/admin/order_routing_rules_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/order_routing_rules_spec.rbnew file mode 100644index 0000000000..5f54ba89c6--- /dev/null+++ b/spree/api/spec/integration/spree/api/v3/admin/order_routing_rules_spec.rb@@ -0,0 +1,166 @@+# frozen_string_literal: true++require 'swagger_helper'++RSpec.describe 'Admin Order Routing Rules API', type: :request, swagger_doc: 'api-reference/admin.yaml' do+ include_context 'API v3 Admin'++ let(:Authorization) { "Bearer #{admin_jwt_token}" }+ let(:channel) { store.default_channel }+ let(:channel_id) { channel.prefixed_id }++ path '/api/v3/admin/channels/{channel_id}/order_routing_rules' do+ parameter name: :channel_id, in: :path, type: :string, required: true++ get 'List order routing rules for a channel' do+ tags 'Channels'+ produces 'application/json'+ 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.'+ admin_scope :read, :settings++ admin_sdk_example 'order-routing-rules/list'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true++ response '200', 'rules found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }++ run_test! do |response|+ data = JSON.parse(response.body)['data']+ expect(data.map { |r| r['type'] }).to eq(%w[preferred_location minimize_splits default_location])+ end+ end+ end++ post 'Create an order routing rule on a channel' do+ tags 'Channels'+ produces 'application/json'+ consumes 'application/json'+ 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.'+ admin_scope :write, :settings++ admin_sdk_example 'order-routing-rules/create'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ type: { type: :string, example: 'preferred_location' },+ active: { type: :boolean },+ position: { type: :integer },+ preferences: { type: :object, additionalProperties: true }+ },+ required: ['type']+ }++ response '201', 'rule created' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { type: 'default_location' } }++ before { channel.order_routing_rules.find_by(type: 'Spree::OrderRouting::Rules::DefaultLocation').destroy! }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['type']).to eq('default_location')+ expect(data['position']).to eq(3)+ end+ end++ response '422', 'unknown rule type' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { type: 'bogus_rule' } }++ run_test! do |response|+ expect(JSON.parse(response.body)['error']['code']).to eq('unknown_order_routing_rule_type')+ end+ end+ end+ end++ path '/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}' do+ parameter name: :channel_id, in: :path, type: :string, required: true+ parameter name: :id, in: :path, type: :string, required: true++ let(:rule) { channel.order_routing_rules.ordered.first }+ let(:id) { rule.prefixed_id }++ patch 'Update an order routing rule' do+ tags 'Channels'+ produces 'application/json'+ consumes 'application/json'+ 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.'+ admin_scope :write, :settings++ admin_sdk_example 'order-routing-rules/update'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true+ parameter name: :body, in: :body, schema: {+ type: :object,+ properties: {+ active: { type: :boolean },+ position: { type: :integer },+ preferences: { type: :object, additionalProperties: true }+ }+ }++ response '200', 'rule updated' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }+ let(:body) { { active: false, position: 2 } }++ run_test! do |response|+ data = JSON.parse(response.body)+ expect(data['active']).to be(false)+ expect(data['position']).to eq(2)+ end+ end+ end++ delete 'Delete an order routing rule' do+ tags 'Channels'+ security [api_key: [], bearer_auth: []]+ admin_scope :write, :settings++ admin_sdk_example 'order-routing-rules/delete'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true++ response '204', 'rule deleted' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }++ run_test!+ end+ end+ end++ path '/api/v3/admin/order_routing_rules/types' do+ get 'List available order routing rule types' do+ tags 'Channels'+ produces 'application/json'+ 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`.'+ admin_scope :read, :settings++ admin_sdk_example 'order-routing-rules/types'++ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true+ parameter name: :Authorization, in: :header, type: :string, required: true++ response '200', 'types found' do+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }++ run_test! do |response|+ data = JSON.parse(response.body)['data']+ expect(data.map { |t| t['type'] }).to contain_exactly('preferred_location', 'minimize_splits', 'default_location')+ expect(data.first).to include('label', 'description', 'preference_schema')+ end+ end+ end+ end+enddiff --git a/spree/api/spec/serializers/spree/api/v3/admin/order_routing_rule_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/admin/order_routing_rule_serializer_spec.rbnew file mode 100644index 0000000000..4cede9e9b0--- /dev/null+++ b/spree/api/spec/serializers/spree/api/v3/admin/order_routing_rule_serializer_spec.rb@@ -0,0 +1,44 @@+# frozen_string_literal: true++require 'spec_helper'++RSpec.describe Spree::Api::V3::Admin::OrderRoutingRuleSerializer do+ let(:store) { @default_store }+ let(:channel) { store.default_channel }+ let(:rule) { channel.order_routing_rules.ordered.first }++ subject(:payload) { described_class.new(rule, params: { store: store, currency: 'USD' }).to_h }++ it 'serializes the wire shape the routing-rules editor consumes' do+ expect(payload['id']).to eq(rule.prefixed_id)+ expect(payload['type']).to eq('preferred_location')+ expect(payload['channel_id']).to eq(channel.prefixed_id)+ expect(payload['position']).to eq(1)+ expect(payload['active']).to be(true)+ expect(payload['label']).to eq('Preferred location')+ expect(payload['description']).to be_present+ expect(payload['preferences']).to eq({})+ expect(payload['preference_schema']).to eq([])+ expect(payload['created_at']).to be_present+ expect(payload['updated_at']).to be_present+ end++ describe 'preferences masking' do+ # Built-in rules declare no preferences; splice a `:password` preference+ # into the schema for the duration of the example so the masking path is+ # locked in for plugin-authored rules that carry secrets.+ let(:rule) do+ channel.order_routing_rules.ordered.first.tap do |r|+ r.preferences[:api_secret] = 'sk_rule_super_secret_value'++ stubbed_schema = [{ key: :api_secret, type: :password, default: nil }]+ allow(r.class).to receive(:preference_schema).and_return(stubbed_schema)+ end+ end++ it 'masks `:password` preferences and never leaks the plaintext' do+ expect(payload['preferences']['api_secret']).to eq("#{Spree::Preferences::Masking::TOKEN}alue")+ expect(payload.to_json).not_to include('sk_rule_super_secret_value')+ end+ end+enddiff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rbindex e13d3da03e..72b2d03c4f 100644--- a/spree/api/spec/swagger_helper.rb+++ b/spree/api/spec/swagger_helper.rb@@ -79,18 +79,6 @@ RSpec.configure do |config|{ name: 'Policies', description: 'Store policies (return policy, privacy policy, terms of service)' },{ name: 'Digitals', description: 'Digital product downloads' }],- 'x-tagGroups': [- { name: 'Authentication', tags: ['Authentication'] },- { name: 'Product Catalog', tags: ['Product Catalog'] },- { name: 'Carts', tags: ['Carts'] },- { name: 'Orders', tags: ['Orders'] },- { name: 'Customers', tags: ['Customers'] },- { name: 'Markets', tags: ['Markets'] },- { name: 'Wishlists', tags: ['Wishlists'] },- { name: 'Newsletter Subscribers', tags: ['Newsletter Subscribers'] },- { name: 'Policies', tags: ['Policies'] },- { name: 'Digitals', tags: ['Digitals'] }- ],components: {securitySchemes: {api_key: {@@ -165,17 +153,23 @@ RSpec.configure do |config|}}],+ # Authentication first, the rest alphabetical — Mintlify renders one+ # sidebar group per tag in this order, and any operation tag missing+ # from this list gets appended at the bottom of the sidebar. Keep every+ # operation tag listed.tags: [{ name: 'Authentication', description: 'Admin user login, logout, token refresh, and current user profile' },{ name: 'Allowed Origins', description: 'CORS allowlist for storefront and admin client origins' },{ name: 'API Keys', description: 'Secret and publishable API keys' },- { name: 'Channels', description: 'Sales channels and product publication across channels' },+ { name: 'Categories', description: 'Hierarchical product categories — tree management, repositioning, and product assignments' },+ { name: 'Channels', description: 'Sales channels, product publication across channels, and per-channel order routing rules' },{ name: 'Custom Fields', description: 'Custom field definitions for products, variants, customers, and other resources' },{ name: 'Customer Groups', description: 'Customer groups for segmenting customers (e.g. wholesale, VIP) used by pricing and promotions' },{ name: 'Customers', description: 'Customer profiles, addresses, credit cards, and store credits' },{ name: 'Exports', description: 'Async CSV exports of admin resources' },{ name: 'Fulfillments', description: 'Order fulfillments — shipments, fulfill, cancel, resume, split' },{ name: 'Gift Cards', description: 'Gift cards and gift card batches' },+ { name: 'Imports', description: 'Async CSV imports of admin resources, with per-row status and failed-row retry' },{ name: 'Markets', description: 'Markets — geographic groupings of countries used for pricing, tax, and fulfillment rules' },{ name: 'Option Types', description: 'Option types and option values used to build product variants (e.g. Size, Color)' },{ name: 'Orders', description: 'Orders, order items, applied gift cards, and applied store credits' },@@ -191,16 +185,6 @@ RSpec.configure do |config|{ name: 'Variants', description: 'Product variants — the individual SKUs (size/color combinations) sold under a product' },{ name: 'Webhooks', description: 'Webhook endpoints and webhook delivery history' }],- 'x-tagGroups': [- { name: 'Authentication', tags: ['Authentication'] },- { name: 'Products & Catalog', tags: ['Products', 'Variants', 'Option Types', 'Custom Fields', 'Channels'] },- { name: 'Pricing', tags: ['Pricing', 'Markets'] },- { name: 'Orders & Fulfillment', tags: ['Orders', 'Payments', 'Fulfillments', 'Refunds'] },- { name: 'Customers', tags: ['Customers', 'Customer Groups'] },- { name: 'Promotions & Gift Cards', tags: ['Promotions', 'Gift Cards'] },- { name: 'Data', tags: ['Exports'] },- { name: 'Configuration', tags: ['Settings', 'Stock Locations', 'Payment Methods', 'Staff', 'API Keys', 'Allowed Origins', 'Webhooks'] }- ],components: {securitySchemes: {api_key: {diff --git a/spree/core/app/models/spree/order_routing_rule.rb b/spree/core/app/models/spree/order_routing_rule.rbindex 83499bd7d5..e6066dd26a 100644--- a/spree/core/app/models/spree/order_routing_rule.rb+++ b/spree/core/app/models/spree/order_routing_rule.rb@@ -29,7 +29,15 @@ module Spreeattribute :active, :boolean, default: true+ # acts_as_list only assigns bottom positions in before_create — too late+ # for the presence validation below, so API creates without an explicit+ # position would 422. Default to the end of the channel's list instead.+ before_validation :set_position_to_end, on: :create, if: -> { position.blank? && channel.present? }+validates :type, :channel, presence: true+ # One instance of each rule kind per channel — a duplicate signal would+ # either be a no-op or fight itself in the reducer walk.+ validates :type, uniqueness: { scope: [:channel_id, *spree_base_uniqueness_scope] }validates :position, presence: true, numericality: { only_integer: true }validate :channel_belongs_to_store@@ -43,6 +51,25 @@ module Spreevalidate :type_must_be_registered+ # @return [String] localized display name for the rule kind, used by admin pickers+ def self.human_name+ Spree.t("order_routing_rule_types.#{api_type}.name", default: api_type.titleize)+ end++ # @return [String] localized description for the rule kind+ def self.human_description+ Spree.t("order_routing_rule_types.#{api_type}.description", default: '')+ end++ # Feeds the `description` field of `subclasses_with_preference_schema`+ # (the `/types` discovery payload), which only reads `.description`.+ def self.description+ human_description+ end++ def human_name = self.class.human_name+ def human_description = self.class.human_description+# Subclasses override. Returns an Array<LocationRanking> — one per location,# with rank=nil to abstain.#@@ -53,8 +80,24 @@ module Spreeraise NotImplementedError, "#{self.class} must implement #rank(order, locations)"end+ # Routes Spree::PreferenceSchema's subclass discovery+ # (`subclasses_with_preference_schema`, `find_by_api_type`) to the+ # order-routing rule registry.+ module ClassMethods+ private++ def registered_subclasses+ Spree.order_routing.rules+ end+ end+ extend ClassMethods+private+ def set_position_to_end+ self.position = bottom_position_in_list + 1+ end+# The +type+ presence validation already covers blank; here we only reject# a present-but-unregistered STI type so arbitrary class names can't be# persisted via the +type+ column.diff --git a/spree/core/app/models/spree/permission_sets/configuration_management.rb b/spree/core/app/models/spree/permission_sets/configuration_management.rbindex ce3d87a11b..119238a550 100644--- a/spree/core/app/models/spree/permission_sets/configuration_management.rb+++ b/spree/core/app/models/spree/permission_sets/configuration_management.rb@@ -45,8 +45,9 @@ module Spreecan :manage, Spree::ReimbursementTypecan :manage, Spree::ReturnReason- # Channels+ # Channels + per-channel order routing rulescan :manage, Spree::Channel+ can :manage, Spree::OrderRoutingRule# Restrictions on immutable typescannot [:edit, :update], Spree::RefundReason, mutable: falsediff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.ymlindex 9ddc0f99c2..87af144a8e 100644--- a/spree/core/config/locales/en.yml+++ b/spree/core/config/locales/en.yml@@ -1190,6 +1190,16 @@ en:strategies:legacy: Legacyrules: Rules (ordered)+ order_routing_rule_types:+ default_location:+ description: Prefer the stock location marked as default+ name: Default location+ minimize_splits:+ description: Prefer the location that can fulfill the most items on its own, avoiding split shipments+ name: Minimize splits+ preferred_location:+ description: Fulfill from the location pinned on the order, when one is set+ name: Preferred locationorder_summary: Order Summaryorder_total: Order Totalorders: Ordersdiff --git a/spree/core/db/migrate/20260721000001_add_unique_type_index_to_spree_order_routing_rules.rb b/spree/core/db/migrate/20260721000001_add_unique_type_index_to_spree_order_routing_rules.rbnew file mode 100644index 0000000000..a441418c55--- /dev/null+++ b/spree/core/db/migrate/20260721000001_add_unique_type_index_to_spree_order_routing_rules.rb@@ -0,0 +1,7 @@+class AddUniqueTypeIndexToSpreeOrderRoutingRules < ActiveRecord::Migration[7.2]+ def change+ add_index :spree_order_routing_rules, [:channel_id, :type],+ unique: true,+ name: 'idx_order_routing_rules_channel_type'+ end+enddiff --git a/spree/core/lib/spree/testing_support/factories/order_routing_rule_factory.rb b/spree/core/lib/spree/testing_support/factories/order_routing_rule_factory.rbnew file mode 100644index 0000000000..372a3c056a--- /dev/null+++ b/spree/core/lib/spree/testing_support/factories/order_routing_rule_factory.rb@@ -0,0 +1,14 @@+FactoryBot.define do+ # STI base can't be persisted (type must be a registered subclass), so the+ # factory defaults to DefaultLocation. Channels seed all built-in kinds on+ # create and `type` is unique per channel, so the factory clears the seeded+ # list — specs get a pristine channel whose only rule is the one built here.+ # Position defaults to the end of the channel's list via the model callback.+ factory :order_routing_rule, class: Spree::OrderRouting::Rules::DefaultLocation do+ channel { association(:channel).tap { |c| c.order_routing_rules.delete_all } }+ store { channel.store }++ factory :preferred_location_routing_rule, class: Spree::OrderRouting::Rules::PreferredLocation+ factory :minimize_splits_routing_rule, class: Spree::OrderRouting::Rules::MinimizeSplits+ end+enddiff --git a/spree/core/spec/models/spree/order_routing_rule_spec.rb b/spree/core/spec/models/spree/order_routing_rule_spec.rbindex 69c1ee6a98..7415b36a73 100644--- a/spree/core/spec/models/spree/order_routing_rule_spec.rb+++ b/spree/core/spec/models/spree/order_routing_rule_spec.rb@@ -18,6 +18,9 @@ RSpec.describe Spree::OrderRoutingRule, type: :model doendit 'is valid when instantiated as an STI subclass with a channel' do+ # The seeded rule of the same kind must go first — `type` is unique per channel.+ channel.order_routing_rules.find_by(type: 'Spree::OrderRouting::Rules::PreferredLocation').destroy!+rule = Spree::OrderRouting::Rules::PreferredLocation.new(store: store, channel: channel, position: 1)expect(rule).to be_validend@@ -38,6 +41,31 @@ RSpec.describe Spree::OrderRoutingRule, type: :model doexpect(rule).not_to be_validexpect(rule.errors[:type]).to be_presentend++ it 'defaults position to the end of the channel list when omitted' do+ # Destroying the seeded rule compacts the list to positions 1-2+ # (acts_as_list), so the re-created rule lands at 3.+ channel.order_routing_rules.find_by(type: 'Spree::OrderRouting::Rules::PreferredLocation').destroy!++ rule = Spree::OrderRouting::Rules::PreferredLocation.create!(store: store, channel: channel)+ expect(rule.position).to eq(3)+ end++ it 'rejects a second rule of the same kind on a channel' do+ rule = Spree::OrderRouting::Rules::PreferredLocation.new(store: store, channel: channel)+ expect(rule).not_to be_valid+ expect(rule.errors[:type]).to be_present+ end+ end++ describe '.subclasses_with_preference_schema' do+ it 'enumerates registered kinds with localized labels and descriptions' do+ entry = described_class.subclasses_with_preference_schema.find { |e| e[:type] == 'default_location' }++ expect(entry[:label]).to eq('Default location')+ expect(entry[:description]).to be_present+ expect(entry[:preference_schema]).to eq([])+ endenddescribe 'Spree.order_routing.rules' do@@ -89,7 +117,7 @@ RSpec.describe Spree::OrderRoutingRule, type: :model dolet(:locations) { [create(:stock_location)] }it 'is implemented by subclasses' do- rule = Spree::OrderRouting::Rules::DefaultLocation.create!(store: store, channel: channel, position: 99)+ rule = channel.order_routing_rules.find_by(type: 'Spree::OrderRouting::Rules::DefaultLocation')rankings = rule.rank(order, locations)expect(rankings).to all(be_a(Spree::OrderRoutingRule::LocationRanking))end