Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

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.md
new file mode 100644
index 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.yaml
index 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_QQFwMZ8woJRNn4lx80
user:
id: admin_UkLWZg9DAJ
- first_name: Isaura
- last_name: Bradtke
- full_name: Isaura Bradtke
+ first_name: Magdalen
+ last_name: Botsford
+ full_name: Magdalen Botsford
selected_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_Bmt17NYsZQmcKyxPNm28
user:
id: admin_UkLWZg9DAJ
- first_name: Mickie
- last_name: Bahringer
- full_name: Mickie Bahringer
+ first_name: Marcella
+ last_name: Little
+ full_name: Marcella Little
selected_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
- first_name: Takako
- last_name: Schowalter
- full_name: Takako Schowalter
+ first_name: Bud
+ last_name: Pouros
+ full_name: Bud Pouros
selected_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
- first_name: Dwana
- last_name: Kiehn
- full_name: Dwana Kiehn
+ first_name: Anglea
+ last_name: Labadie
+ full_name: Anglea Labadie
selected_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_s0w09zRsBBiE
user:
id: admin_UkLWZg9DAJ
- first_name: Royce
- last_name: Funk
- full_name: Royce Funk
+ first_name: Dahlia
+ last_name: Nolan
+ full_name: Dahlia Nolan
selected_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_UkLWZg9DAJ
origin: 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: 1
limit: 25
@@ -837,8 +837,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: 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_UkLWZg9DAJ
origin: 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_UkLWZg9DAJ
origin: 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: publishable
token_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_NpVVr7KT3KR7aNQtYhRarkLB
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_PiEwdvTU6
+ token_prefix: sk_jvcayks8e
scopes:
- 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: aspernatur
key_type: secret
- token_prefix: sk_2NFKiP14w
+ token_prefix: sk_bEXJent5P
scopes:
- 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_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_YrTk9UUdj
+ token_prefix: sk_R4Mob1qJS
scopes:
- 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 error
content:
@@ -1300,12 +1300,12 @@ paths:
key_type: publishable
token_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_sLyTgpo6jEykowF7qMCRsbC4
created_by_email:
patch:
summary: Update an API key
@@ -1359,11 +1359,11 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration (renamed)
key_type: secret
- token_prefix: sk_iVncK9AGx
+ token_prefix: sk_Rqy49T6BQ
scopes:
- 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: ex
key_type: secret
- token_prefix: sk_f39FA4nWr
+ token_prefix: sk_hFAPcmw1E
scopes:
- 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_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_LnuKvFNz2
+ token_prefix: sk_hofZkVSLf
scopes:
- 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 categories
tags:
- - Channels
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the channels configured for the current store.
-
- **Required scope:** `read_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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-key
in: header
@@ -1570,57 +1555,67 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- name: page
in: query
required: false
+ description: Page number
schema:
type: integer
- name: limit
in: query
required: false
+ description: Number of records per page
schema:
type: integer
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (e.g., children, parent,
+ ancestors).
+ schema:
+ type: string
responses:
'200':
- description: channels found
+ description: categories found
content:
application/json:
example:
data:
- - id: ch_UkLWZg9DAJ
- name: Online Store
- code: online
- active: true
- default: true
- storefront_access: public
- guest_checkout: true
- preferred_order_routing_strategy:
- preferred_storefront_access:
- preferred_guest_checkout:
- created_at: '2026-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: 1
limit: 25
- count: 2
+ count: 1
pages: 1
from: 1
- to: 2
- in: 2
+ to: 1
+ in: 1
previous:
next:
schema:
@@ -1629,47 +1624,23 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/Channel"
+ "$ref": "#/components/schemas/Category"
meta:
"$ref": "#/components/schemas/PaginationMeta"
required:
- data
- meta
post:
- summary: Create a channel
+ summary: Create a category
tags:
- - Channels
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a new channel on the current store. `code` is normalized to a
- URL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's
- derived from `name`.
-
-
- **Required scope:** `write_settings` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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-key
in: header
@@ -1679,74 +1650,94 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: channel created
+ description: category created
content:
application/json:
example:
- id: ch_EfhxLZ9ck8
- name: Marketplace
- code: marketplace
- active: true
- default: false
- storefront_access: public
- guest_checkout: true
- preferred_order_routing_strategy:
- preferred_storefront_access:
- preferred_guest_checkout:
- created_at: '2026-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:
- - name
properties:
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 category
tags:
- - Channels
+ - Categories
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',
- })
+ 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-key
in: header
@@ -1756,52 +1747,75 @@ paths:
- 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: channel found
+ description: category found
content:
application/json:
example:
- id: ch_gbHJdmfrXB
- name: Wholesale
- code: wholesale
- active: true
- default: false
- storefront_access: public
- guest_checkout: true
- preferred_order_routing_strategy:
- preferred_storefront_access:
- preferred_guest_checkout:
- created_at: '2026-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-key
in: header
@@ -1811,26 +1825,47 @@ paths:
- 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: channel updated
+ description: category updated
content:
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: boolean
delete:
- summary: Delete a channel
+ summary: Delete a category
tags:
- - Channels
+ - 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: |-
+ 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-key
in: header
@@ -1875,53 +1910,30 @@ paths:
- 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: 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 category
tags:
- - Channels
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Publishes the listed products on this channel. Idempotent — re-publishing
- an already-published product updates its publication window. Products from
- sibling stores are silently dropped.
-
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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-key
in: header
@@ -1931,77 +1943,73 @@ paths:
- 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: products published
+ description: category repositioned
content:
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_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:
+ 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:
+ - Categories
security:
- api_key: []
bearer_auth: []
description: |-
- Unpublishes the listed products from this channel.
-
- **Required scope:** `write_products` (for API-key authentication).
- x-codeSamples:
- - lang: javascript
- label: Spree Admin SDK
- source: |-
- import { createAdminClient } from '@spree/admin-sdk'
-
- const client = createAdminClient({
- baseUrl: 'https://your-store.com',
- secretKey: 'sk_xxx',
- })
+ 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-key
in: header
@@ -2011,42 +2019,199 @@ paths:
- 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 unpublished
+ description: products found
content:
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: object
properties:
- 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_abc123
required:
- - 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: object
properties:
- 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 channels
tags:
- - Custom Fields
+ - Channels
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.
+ 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: bash
label: Spree CLI
- source: spree api get /custom_field_definitions -d '{"q":{"resource_type_eq":"Spree::Product"}}'
+ source: spree api get /channels
parameters:
- name: x-spree-api-key
in: header
@@ -2077,45 +2240,47 @@ paths:
required: true
schema:
type: string
- - name: expand
+ - name: page
in: query
required: false
- description: Comma-separated associations to expand. Use dot notation for
- nested expand (max 4 levels).
schema:
- type: string
- - name: fields
+ type: integer
+ - name: limit
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
+ type: integer
responses:
'200':
- description: definitions returned
+ description: channels found
content:
application/json:
example:
data:
- - id: cfdef_UkLWZg9DAJ
- namespace: specs
- key: fabric
- label: Title
- field_type: short_text
- resource_type: Spree::Product
- storefront_visible: true
- 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: 1
limit: 25
@@ -2126,14 +2291,32 @@ paths:
in: 2
previous:
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 channel
tags:
- - Custom Fields
+ - Channels
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api post /custom_field_definitions -d '{"namespace":"specs","key":"origin","label":"Country
- of Origin","field_type":"short_text","resource_type":"Spree::Product","storefront_visible":true}'
+ source: spree api post /channels -d '{"name":"Point of Sale","code":"pos","active":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -2170,53 +2351,51 @@ paths:
type: string
responses:
'201':
- description: definition created
+ description: channel created
content:
application/json:
example:
- id: cfdef_EfhxLZ9ck8
- namespace: specs
- key: origin
- label: Country of Origin
- field_type: short_text
- resource_type: Spree::Product
- storefront_visible: true
- 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: object
required:
- - key
- - field_type
- - resource_type
+ - name
properties:
- 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: string
get:
- summary: Show a custom field definition
+ summary: Get a channel
tags:
- - Custom Fields
+ - Channels
security:
- 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: bash
label: Spree CLI
- source: spree api get /custom_field_definitions/{id}
+ source: spree api get /channels/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -2247,44 +2426,28 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand. Use dot notation for
- nested expand (max 4 levels).
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., key,label,field_type).
- id is always included.
- schema:
- type: string
responses:
'200':
- description: definition found
+ description: channel 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-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 channel
tags:
- - Custom Fields
+ - Channels
security:
- 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: bash
label: 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-key
in: header
@@ -2319,47 +2481,44 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
responses:
'200':
- description: definition updated
+ description: channel updated
content:
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: object
properties:
- label:
+ name:
type: string
- storefront_visible:
+ code:
+ type: string
+ active:
type: boolean
delete:
- summary: Delete a custom field definition
+ summary: Delete a channel
tags:
- - Custom Fields
+ - Channels
security:
- api_key: []
bearer_auth: []
- description: |-
- Deletes the definition and cascades to all custom field values referencing it.
-
- **Required scope:** `write_settings` (for API-key authentication).
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -2371,10 +2530,10 @@ paths:
secretKey: 'sk_xxx',
})
- await client.customFieldDefinitions.delete('cfd_UkLWZg9DAJ')
+ await client.channels.delete('channel_xxx')
- lang: bash
label: Spree CLI
- source: spree api delete /custom_field_definitions/{id}
+ source: spree api delete /channels/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -2386,32 +2545,30 @@ paths:
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
+ 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:
- - Customer Groups
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the customer groups configured for the current store. Groups
- segment customers for targeted promotions (see the `customer_group`
- promotion rule) and reporting. The list endpoint never embeds the
- member list — fetch a single group with `?expand=customers` if you
- need them inline, or query `/admin/customers?customer_group_id_in=…`
- for paginated membership.
+ 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -2436,105 +2599,60 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: page
- in: query
- required: false
- description: Page number
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: Number of records per page
- schema:
- type: integer
- - name: q[name_cont]
- in: query
- required: false
- description: Filter by name (contains)
- schema:
- type: string
- - name: 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
+ description: products published
content:
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: 1
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"
+ 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: Create a customer group
+ summary: Unpublish products from a channel
tags:
- - Customer Groups
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Creates a customer group in the current store. `customer_ids` is
- optional; when present, customers are attached at create time.
- Pass prefixed IDs (e.g. `cus_…`) — the server decodes them
- automatically.
-
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api post /customer_groups -d '{"name":"VIP customers","description":"Top
- spenders, eligible for early access","customer_ids":["cus_UkLWZg9DAJ","cus_QrLWXg9CAJ"]}'
+ source: spree api post /channels/{id}/remove_products -d '{"product_ids":["prod_xxx","prod_yyy"]}'
parameters:
- name: x-spree-api-key
in: header
@@ -2567,75 +2682,47 @@ paths:
schema:
type: string
responses:
- '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 unpublished
content:
application/json:
example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
+ product_count: 1
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ type: object
+ properties:
+ product_count:
+ type: integer
requestBody:
content:
application/json:
schema:
type: object
required:
- - name
+ - product_ids
properties:
- name:
- type: string
- example: Wholesale
- description:
- type: string
- example: B2B accounts
- nullable: true
- customer_ids:
+ product_ids:
type: array
items:
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_id
in: path
required: true
- description: Customer group prefixed ID
schema:
type: string
get:
- summary: Get a customer group
+ summary: List order routing rules for a channel
tags:
- - Customer Groups
+ - Channels
security:
- api_key: []
bearer_auth: []
description: |-
- Returns a single customer group. Pass `?expand=customers` to embed
- the full member list inline (recommended only for single-record
- reads — embed cost scales with membership size).
-
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api get /customer_groups/{id} -d '{"expand":["customers"]}'
+ source: spree api get /channels/{channel_id}/order_routing_rules
parameters:
- name: x-spree-api-key
in: header
@@ -2664,87 +2749,69 @@ paths:
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:
- 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
- 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"
- 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 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
+ 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 channel
tags:
- - Customer Groups
+ - Channels
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.
-
+ 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -2777,62 +2841,71 @@ paths:
schema:
type: string
responses:
- '200':
- description: customer group updated
+ '201':
+ description: rule created
content:
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 type
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"
+ code: unknown_order_routing_rule_type
+ message: Unknown type
requestBody:
content:
application/json:
schema:
type: object
properties:
- 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 rule
tags:
- - Customer Groups
+ - Channels
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -2860,20 +2937,44 @@ paths:
schema:
type: string
responses:
- '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 rule
tags:
- - Customers
+ - Channels
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -2900,76 +3001,80 @@ paths:
required: true
schema:
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: header
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.
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: addresses found
+ description: types found
content:
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 definitions
tags:
- - Customers
+ - Custom Fields
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.
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api post /customers/{customer_id}/addresses -d '{"first_name":"Jane","last_name":"Doe","address1":"350
- Fifth Avenue","city":"New York","postal_code":"10118","country_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-key
in: header
@@ -3009,86 +3103,63 @@ paths:
required: true
schema:
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: string
responses:
- '201':
- description: address created
+ '200':
+ description: definitions returned
content:
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 definition
tags:
- - Customers
+ - Custom Fields
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -3119,68 +3194,59 @@ paths:
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
+ '201':
+ description: definition created
content:
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_type
properties:
- 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 definition
tags:
- - Customers
+ - Custom Fields
security:
- api_key: []
bearer_auth: []
- description: |-
- Deletes the address. If it was a default, the customer loses that default (no auto-promotion).
-
- **Required scope:** `write_customers` (for API-key authentication).
+ description: "**Required scope:** `read_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: 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: bash
label: Spree CLI
- source: spree api delete /customers/{customer_id}/addresses/{id}
+ source: spree api get /custom_field_definitions/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -3207,31 +3273,48 @@ paths:
required: true
schema:
type: string
- - name: customer_id
+ - name: id
in: path
required: true
schema:
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: string
responses:
- '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 definition
tags:
- - Customers
+ - Custom Fields
security:
- api_key: []
bearer_auth: []
- description: |-
- Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.
-
- **Required scope:** `read_customers` (for API-key authentication).
+ description: "**Required scope:** `write_settings` (for API-key authentication)."
x-codeSamples:
- lang: javascript
label: 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: bash
label: 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-key
in: header
@@ -3258,147 +3345,47 @@ paths:
required: true
schema:
type: string
- - name: customer_id
+ - 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 cards found
+ description: definition updated
content:
application/json:
example:
- data:
- - id: card_UkLWZg9DAJ
- brand: visa
- last4: '1111'
- month: 12
- year: 2027
- name: Spree Commerce
- default: false
- gateway_payment_profile_id:
- 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: boolean
delete:
- summary: Delete a customer credit card
+ summary: Delete a custom field definition
tags:
- - Customers
+ - Custom Fields
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -3425,11 +3412,6 @@ paths:
required: true
schema:
type: string
- - name: customer_id
- in: path
- required: true
- schema:
- type: string
- name: id
in: path
required: true
@@ -3437,19 +3419,25 @@ paths:
type: string
responses:
'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 groups
tags:
- - Customers
+ - Customer Groups
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -3474,71 +3462,105 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
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: sort
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).
+ description: Sort by field. Prefix with `-` for descending (e.g., `-created_at`).
schema:
type: string
- name: fields
in: query
required: false
- description: Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency).
- id is always included.
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
'200':
- description: store credits found
+ description: customer groups found
content:
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: 1
limit: 25
- count: 1
+ count: 2
pages: 1
from: 1
- to: 1
- in: 1
+ to: 2
+ in: 2
previous:
next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/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 group
tags:
- - Customers
+ - Customer Groups
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -3571,66 +3592,76 @@ paths:
required: true
schema:
type: string
- - name: customer_id
- in: path
- required: true
- schema:
- type: string
responses:
'201':
- description: store credit created
+ description: customer group created
content:
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: object
required:
- - amount
- - currency
- - category_id
+ - name
properties:
- 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 group
tags:
- - Customers
+ - Customer Groups
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -3662,62 +3690,175 @@ paths:
required: true
schema:
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
+ 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"
+ 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: header
required: true
schema:
type: string
- - name: id
- in: path
+ - name: Authorization
+ in: header
required: true
schema:
type: string
responses:
'200':
- description: store credit updated
+ description: customer group updated
content:
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: object
properties:
- 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_UkLWZg9DAJ
delete:
- summary: Delete a store credit
+ summary: Delete a customer group
tags:
- - Customers
+ - Customer Groups
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api delete /customers/{customer_id}/store_credits/{id}
+ source: spree api delete /customer_groups/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -3744,29 +3885,19 @@ paths:
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":
+ description: customer group deleted
+ "/api/v3/admin/customers/{customer_id}/addresses":
get:
- summary: List customers
+ summary: List customer addresses
tags:
- Customers
security:
- 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: bash
label: Spree CLI
- source: spree api get /customers -d '{"search":"jane","sort":"-created_at","limit":25}'
+ source: spree api get /customers/{customer_id}/addresses
parameters:
- name: x-spree-api-key
in: header
@@ -3797,74 +3924,57 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: page
- in: query
- required: false
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- schema:
- type: integer
- - name: q[search]
- in: query
- required: false
- description: Email + name full-text-ish search
+ - name: customer_id
+ in: path
+ required: true
schema:
type: string
- name: expand
in: query
required: 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: fields
in: query
required: 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: string
responses:
'200':
- description: customers found
+ description: addresses found
content:
application/json:
example:
data:
- - id: cus_UkLWZg9DAJ
- first_name: Jane
+ - id: addr_UkLWZg9DAJ
+ first_name: John
last_name: Doe
- phone:
- accepts_email_marketing: false
- full_name: Jane Doe
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
+ 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_UkLWZg9DAJ
meta:
page: 1
limit: 25
@@ -3876,14 +3986,14 @@ paths:
previous:
next:
post:
- summary: Create a customer
+ summary: Create a customer address
tags:
- Customers
security:
- 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: bash
label: Spree CLI
- source: spree api post /customers -d '{"email":"[email protected]","first_name":"Jane","last_name":"Doe","phone":"+1
- 212 555 1234","tags":["wholesale"],"accepts_email_marketing":true}'
+ 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-key
in: header
@@ -3920,79 +4035,86 @@ paths:
required: true
schema:
type: string
+ - name: customer_id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'201':
- description: customer created
+ description: address created
content:
application/json:
example:
- id: cus_gbHJdmfrXB
- first_name: New
- last_name: Customer
- phone:
- accepts_email_marketing: false
- full_name: New Customer
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- 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: Office
metadata: {}
- 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_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
- required:
- - email
properties:
- email:
- type: string
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
- 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 address
tags:
- Customers
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -4021,172 +4145,66 @@ paths:
required: true
schema:
type: string
- - name: id
+ - name: customer_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.
+ - name: id
+ in: path
+ required: true
schema:
type: string
responses:
'200':
- description: customer found
+ description: address updated
content:
application/json:
example:
- id: cus_UkLWZg9DAJ
- first_name: Jane
+ id: addr_UkLWZg9DAJ
+ first_name: John
last_name: Doe
- phone:
- accepts_email_marketing: false
- full_name: Jane Doe
- available_store_credit_total: '0'
- display_available_store_credit_total: "$0.00"
- 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
- 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"
+ 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_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
properties:
- 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: object
delete:
- summary: Delete a customer
+ summary: Delete a customer address
tags:
- Customers
security:
- 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: bash
label: Spree CLI
- source: spree api delete /customers/{id}
+ source: spree api delete /customers/{customer_id}/addresses/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -4215,6 +4233,11 @@ paths:
required: true
schema:
type: string
+ - name: customer_id
+ in: path
+ required: true
+ schema:
+ type: string
- name: id
in: path
required: true
@@ -4222,23 +4245,19 @@ paths:
type: string
responses:
'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 cards
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Attaches each customer in `ids` to every group in `customer_group_ids`.
- Idempotent — customers already in a group are skipped server-side.
- Groups from sibling stores are silently ignored. Returns counts of
- customers and groups that were processed (post store-scoping).
-
+ 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: javascript
label: 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: bash
label: 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_cards
parameters:
- name: x-spree-api-key
in: header
@@ -4268,57 +4284,67 @@ paths:
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: customers added to groups
+ description: credit cards found
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
- - 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 card
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Detaches each customer in `ids` from every group in `customer_group_ids`.
- No-op for non-members. Groups from sibling stores are silently ignored.
-
+ 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -4348,54 +4371,58 @@ paths:
required: true
schema:
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 card
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Adds each tag name in `tags` to every customer in `ids`. Tags are
- upserted by name; re-adding an existing tag is a no-op.
-
+ 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: bash
label: 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-key
in: header
@@ -4427,57 +4451,31 @@ paths:
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: 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 credits
tags:
- Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Removes each tag name in `tags` from every customer in `ids`. No-op
- for customers that don't carry the tag.
-
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api post /customers/bulk_remove_tags -d '{"ids":["cus_UkLWZg9DAJ"],"tags":["vip"]}'
+ source: spree api get /customers/{customer_id}/store_credits
parameters:
- name: x-spree-api-key
in: header
@@ -4507,54 +4502,69 @@ paths:
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: tags removed
+ description: store credits found
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
+ 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 customer
tags:
- - Exports
+ - Customers
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`).
+ `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: javascript
label: 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: bash
label: Spree CLI
- source: spree api get /exports
- parameters:
- - name: x-spree-api-key
- in: header
- required: true
- schema:
- type: string
- - name: Authorization
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: exports found
- 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-key
in: header
@@ -4656,75 +4597,66 @@ paths:
required: true
schema:
type: string
+ - name: customer_id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'201':
- description: export queued
+ description: store credit created
content:
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: Exchange
requestBody:
content:
application/json:
schema:
type: object
required:
- - type
+ - amount
+ - currency
+ - category_id
properties:
- 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 credit
tags:
- - Exports
+ - Customers
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -4751,6 +4688,11 @@ paths:
required: true
schema:
type: string
+ - name: customer_id
+ in: path
+ required: true
+ schema:
+ type: string
- name: id
in: path
required: true
@@ -4758,32 +4700,50 @@ paths:
type: string
responses:
'200':
- description: export found
+ description: store credit updated
content:
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: string
delete:
- summary: Delete an export
+ summary: Delete a store credit
tags:
- - Exports
+ - Customers
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api delete /exports/{id}
+ source: spree api delete /customers/{customer_id}/store_credits/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -4810,6 +4770,11 @@ paths:
required: true
schema:
type: string
+ - name: customer_id
+ in: path
+ required: true
+ schema:
+ type: string
- name: id
in: path
required: true
@@ -4817,19 +4782,19 @@ paths:
type: string
responses:
'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 customers
tags:
- - Exports
+ - Customers
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.
+ 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -4865,119 +4823,74 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: id
- in: path
- required: true
+ - name: page
+ in: query
+ required: false
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.
-
- **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: false
schema:
- 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 search
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).
+ 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., 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: string
responses:
'200':
- description: fulfillments found
+ description: customers found
content:
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
+ 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"
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: 1
limit: 25
@@ -4989,16 +4902,16 @@ paths:
previous:
next:
post:
- summary: Create a fulfillment
+ summary: Create a customer
tags:
- - Fulfillments
+ - Customers
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).
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/fulfillments -d '{"stock_location_id":"sloc_UkLWZg9DAJ","tracking":"INPOST-12345","delivery_method_id":"dm_UkLWZg9DAJ","status":"shipped","items":[{"item_id":"li_UkLWZg9DAJ","quantity":1}]}'
+ source: spree api post /customers -d '{"email":"[email protected]","first_name":"Jane","last_name":"Doe","phone":"+1
+ 212 555 1234","tags":["wholesale"],"accepts_email_marketing":true}'
parameters:
- name: x-spree-api-key
in: header
@@ -5029,127 +4944,81 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
schema:
type: string
responses:
'201':
- description: fulfillment created
+ description: customer created
content:
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
+ 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: object
required:
- - stock_location_id
+ - email
properties:
- stock_location_id:
+ email:
type: string
- description: Stock location the fulfillment ships from
- tracking:
+ 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: string
metadata:
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 customer
tags:
- - Fulfillments
+ - Customers
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -5174,83 +5045,73 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment ID
+ description: Customer 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).
+ 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., 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: string
responses:
'200':
- description: shipment found
+ description: customer found
content:
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
+ 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"
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 customer
tags:
- - Fulfillments
+ - Customers
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -5277,83 +5139,82 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment ID
schema:
type: string
responses:
'200':
- description: shipment updated
+ description: customer updated
content:
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
+ 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"
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: object
properties:
- 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 customer
tags:
- - Fulfillments
+ - Customers
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{
- ... }'
+ source: spree api delete /customers/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -5379,69 +5239,32 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
schema:
type: string
- name: id
in: path
required: true
- description: Fulfillment ID
schema:
type: string
responses:
- '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 groups
tags:
- - Fulfillments
+ - Customers
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -5467,69 +5292,59 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Fulfillment ID
schema:
type: string
responses:
'200':
- description: fulfillment canceled
+ description: customers added to groups
content:
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 groups
tags:
- - Fulfillments
+ - Customers
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -5555,69 +5372,58 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Fulfillment ID
schema:
type: string
responses:
'200':
- description: fulfillment resumed
+ description: customers removed from groups
content:
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 customers
tags:
- - Fulfillments
+ - Customers
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -5644,92 +5451,59 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Fulfillment ID
schema:
type: string
responses:
'200':
- description: fulfillment split
+ description: tags added
content:
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: integer
requestBody:
content:
application/json:
schema:
type: object
required:
- - variant_id
- - quantity
+ - ids
+ - tags
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 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 customers
tags:
- - Gift Cards
+ - Customers
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the gift card batches issued by the current store. Each batch
- groups the cards generated together for a campaign or bulk-issuance
- — the cards themselves live under `/admin/gift_cards` and reference
- the batch via `gift_card_batch_id`.
+ 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -5754,49 +5531,100 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: page
- in: query
- required: false
- description: Page number
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: 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: true
schema:
type: string
- - name: sort
- in: query
- required: false
- description: Sort by field. Prefix with `-` for descending.
+ - name: Authorization
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: gift card batches found
+ description: exports found
content:
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: 1
limit: 25
@@ -5807,34 +5635,24 @@ paths:
in: 1
previous:
next:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/GiftCardBatch"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
post:
- summary: Create a gift card batch
+ summary: Create an export
tags:
- - Gift Cards
+ - Exports
security:
- api_key: []
bearer_auth: []
description: |-
- Issues a batch of gift cards in a single call. The server generates
- `codes_count` cards inline for small batches (configurable via
- `Spree.config.gift_card_batch_web_limit`, default 500) or enqueues
- a background job for larger ones. Each card's code is the batch
- `prefix` followed by random hex.
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api post /gift_card_batches -d '{"prefix":"WELCOME","amount":"25.00","currency":"USD","codes_count":100,"expires_at":"2030-12-31"}'
+ source: spree api post /exports -d '{"type":"Spree::Exports::Products","search_params":{"name_cont":"shirt"}}'
parameters:
- name: x-spree-api-key
in: header
@@ -5869,83 +5684,73 @@ paths:
type: string
responses:
'201':
- description: gift card batch created
- content:
- application/json:
- example:
- id: gcb_gbHJdmfrXB
- codes_count: 5
- currency: USD
- prefix: NEWCAMP
- created_at: '2026-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 queued
content:
application/json:
example:
- error:
- code: validation_error
- message: Prefix can't be blank
- details:
- prefix:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ 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: object
required:
- - prefix
- - amount
- - codes_count
+ - type
properties:
- prefix:
- type: string
- example: WELCOME
- description: Lowercased and prepended to every generated code.
- amount:
- type: string
- example: '25.00'
- description: Decimal amount per card, greater than zero.
- currency:
+ type:
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 export
tags:
- - Gift Cards
+ - Exports
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api get /gift_card_batches/{id}
+ source: spree api get /exports/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -5972,48 +5777,39 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'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 found
content:
application/json:
example:
- error:
- code: record_not_found
- message: Gift card batch not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/admin/gift_cards":
- get:
- summary: List gift cards
+ 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 export
tags:
- - Gift Cards
+ - Exports
security:
- api_key: []
bearer_auth: []
description: |-
- Returns the gift cards issued by the current store. Filter by
- `q[code_cont]` for code search, `q[user_id_eq]` for cards issued
- to a specific customer, or `q[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: javascript
label: 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: bash
label: 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-key
in: header
@@ -6042,137 +5834,28 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: page
- in: query
- required: false
- description: Page number
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: Number of records per page
- schema:
- type: integer
- - name: q[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: true
schema:
type: string
responses:
- '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 export
tags:
- - Gift Cards
+ - Exports
security:
- api_key: []
bearer_auth: []
description: |-
- Issues a gift card scoped to the current store. The code is
- auto-generated when omitted. `currency` defaults to the store's
- configured currency. Pass `user_id` (prefixed ID) to attach the
- card to a specific customer.
-
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api post /gift_cards -d '{"amount":"25.00","currency":"USD","expires_at":"2030-12-31","user_id":"cus_UkLWZg9DAJ"}'
+ source: spree api get /exports/{id}/download
parameters:
- name: x-spree-api-key
in: header
@@ -6204,96 +5893,32 @@ paths:
required: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
- '201':
- description: gift card created
+ '200':
+ description: CSV file
content:
- 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 fulfillments
tags:
- - Gift Cards
+ - Fulfillments
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api get /gift_cards/{id} -d '{"expand":["customer","created_by","orders"]}'
+ source: spree api get /orders/{order_id}/fulfillments
parameters:
- name: x-spree-api-key
in: header
@@ -6320,64 +5943,88 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: expand
+ in: query
+ required: false
+ description: Comma-separated associations to expand (e.g., 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. id is always included.
+ description: Comma-separated list of fields to include (e.g., number,status,tracking,cost).
+ id is always included.
schema:
type: string
responses:
'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 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 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 fulfillment
tags:
- - Gift Cards
+ - Fulfillments
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -6404,65 +6055,127 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
schema:
type: string
responses:
- '200':
- description: gift card updated
+ '201':
+ description: fulfillment created
content:
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
+ orders
requestBody:
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 shipment
tags:
- - Gift Cards
+ - Fulfillments
security:
- api_key: []
bearer_auth: []
description: |-
- Deletes an unused gift card. Cards that have been redeemed or
- partially redeemed cannot be deleted and return 422.
-
+ 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api delete /gift_cards/{id}
+ source: spree api get /orders/{order_id}/fulfillments/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -6487,147 +6200,83 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
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: path
required: true
+ description: Order ID
schema:
type: string
- - name: Authorization
- in: header
+ - name: id
+ in: path
required: true
+ description: Fulfillment ID
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
+ - 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: expand
+ - name: fields
in: query
required: 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: string
responses:
'200':
- description: markets found
+ description: shipment 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-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 shipment
tags:
- - Markets
+ - Fulfillments
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.
-
+ 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: javascript
label: 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: 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"]}'
+ source: spree api patch /orders/{order_id}/fulfillments/{id} -d '{"tracking":"1Z999AA10123456784"}'
parameters:
- name: x-spree-api-key
in: header
@@ -6659,115 +6303,83 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Fulfillment ID
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-20T06:57:09.529Z'
- updated_at: '2026-07-20T06:57:09.529Z'
- schema:
- "$ref": "#/components/schemas/Market"
- '422':
- description: validation error
+ '200':
+ description: shipment updated
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"
+ 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_UkLWZg9DAJ
requestBody:
content:
application/json:
schema:
type: object
properties:
- 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 fulfillment
tags:
- - Markets
+ - Fulfillments
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api get /markets/{id}
+ source: spree api patch /orders/{order_id}/fulfillments/{id}/fulfill -d '{
+ ... }'
parameters:
- name: x-spree-api-key
in: header
@@ -6792,60 +6405,69 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
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 ID
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-20T06:57:09.861Z'
- updated_at: '2026-07-20T06:57:09.861Z'
- schema:
- "$ref": "#/components/schemas/Market"
- '404':
- description: market not found
+ description: fulfillment fulfilled
content:
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 fulfillment
tags:
- - Markets
+ - Fulfillments
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.
-
+ Cancels a fulfillment.
- **Required scope:** `write_settings` (for API-key authentication).
+ **Required scope:** `write_fulfillments` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: 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: bash
label: 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-key
in: header
@@ -6877,81 +6493,157 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Fulfillment ID
schema:
type: string
responses:
'200':
- description: market updated
+ description: fulfillment canceled
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-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 resumed
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
+ 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 fulfillment
tags:
- - Markets
+ - Fulfillments
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`.
-
+ 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -6978,31 +6670,92 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
+ schema:
+ type: string
+ - name: order_id
+ in: path
+ required: true
+ description: Order ID
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ description: Fulfillment ID
schema:
type: string
responses:
- '204':
- description: market deleted
- '422':
- description: cannot delete default or last market
+ '200':
+ description: fulfillment split
content:
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 batches
tags:
- - Option Types
+ - Gift Cards
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -7039,45 +6792,37 @@ paths:
- name: limit
in: query
required: false
- description: Number of records per page
+ description: Records per page
schema:
type: integer
- - name: q[name_cont]
+ - name: q[prefix_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).
+ description: Filter by prefix (contains)
schema:
type: string
- - name: fields
+ - name: sort
in: query
required: false
- description: Comma-separated list of fields to include (e.g., name,label,position).
- id is always included.
+ description: Sort by field. Prefix with `-` for descending.
schema:
type: string
responses:
'200':
- description: option types found
+ description: gift card batches 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-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: 1
limit: 25
@@ -7094,36 +6839,28 @@ paths:
data:
type: array
items:
- "$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 batch
tags:
- - Option Types
+ - Gift Cards
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.
+ Issues a batch of gift cards in a single call. The server generates
+ `codes_count` cards inline for small batches (configurable via
+ `Spree.config.gift_card_batch_web_limit`, default 500) or enqueues
+ a background job for larger ones. Each card's code is the batch
+ `prefix` followed by random hex.
- **Required scope:** `write_products` (for API-key authentication).
+ **Required scope:** `write_gift_cards` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -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: 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"}]}'
+ source: spree api post /gift_card_batches -d '{"prefix":"WELCOME","amount":"25.00","currency":"USD","codes_count":100,"expires_at":"2030-12-31"}'
parameters:
- name: x-spree-api-key
in: header
@@ -7155,26 +6891,25 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
responses:
'201':
- description: option type created
+ description: gift card batch created
content:
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_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/OptionType"
+ "$ref": "#/components/schemas/GiftCardBatch"
'422':
description: validation error
content:
@@ -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 blank
details:
- name:
- - can't be blank
- presentation:
+ prefix:
- can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
@@ -7195,47 +6928,50 @@ paths:
application/json:
schema:
type: object
+ required:
+ - prefix
+ - amount
+ - codes_count
properties:
- 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: string
get:
- summary: Get an option type
+ summary: Get a gift card batch
tags:
- - Option Types
+ - Gift Cards
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api get /option_types/{id}
+ source: spree api get /gift_card_batches/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -7260,67 +6996,50 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Option type ID
- schema:
- type: string
- - 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
+ description: gift card batch 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-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 found
content:
application/json:
example:
error:
code: record_not_found
- message: Option type not found
+ message: Gift card batch not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update an option type
+ "/api/v3/admin/gift_cards":
+ get:
+ summary: List gift cards
tags:
- - Option Types
+ - Gift Cards
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -7351,87 +7071,134 @@ paths:
description: Bearer token for admin authentication
schema:
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: unauthorized
content:
application/json:
example:
error:
- code: validation_error
- message: Presentation can't be blank
- details:
- presentation:
- - can't be blank
+ code: authentication_required
+ message: Authentication required
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
+ post:
+ summary: Create a gift card
tags:
- - Option Types
+ - Gift Cards
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -7456,30 +7228,98 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Option type ID
schema:
type: string
responses:
- '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 card
tags:
- - Orders
+ - Gift Cards
security:
- 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: javascript
label: 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: bash
label: 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-key
in: header
@@ -7506,62 +7346,62 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
+ - name: fields
+ in: query
+ required: false
+ description: Comma-separated list of fields to include. id is always included.
schema:
type: string
responses:
- '201':
- description: gift card applied
+ '200':
+ description: gift card found
content:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 849A0FE4531E1949
+ code: 061A199E7FEA86EA
status: active
currency: 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: false
active: 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 card
tags:
- - Orders
+ - Gift Cards
security:
- 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: bash
label: 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-key
in: header
@@ -7588,36 +7430,65 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Gift card ID
schema:
type: string
responses:
- '204':
- description: gift card removed
- "/api/v3/admin/orders/{order_id}/items":
- 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 card
tags:
- - Orders
+ - Gift Cards
security:
- 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: javascript
label: 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: bash
label: Spree CLI
- source: spree api get /orders/{order_id}/items
+ source: spree api delete /gift_cards/{id}
parameters:
- name: x-spree-api-key
in: header
@@ -7642,122 +7513,31 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., variant, variant.product).
- Use dot notation for nested expand (max 4 levels).
- schema:
- type: string
- - name: fields
- in: query
- required: false
- description: Comma-separated list of fields to include (e.g., quantity,price,total).
- id is always included.
schema:
type: string
responses:
- '200':
- description: items found
+ '204':
+ description: gift card deleted
+ '422':
+ description: redeemed gift card cannot be deleted
content:
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 imports
tags:
- - Orders
+ - Imports
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',
- })
+ 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-key
in: header
@@ -7767,109 +7547,177 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
schema:
type: string
responses:
- '201':
- description: 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 import
tags:
- - Orders
+ - Imports
security:
- 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-key
in: header
@@ -7879,11856 +7727,360 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
- schema:
- type: string
- - name: order_id
- in: path
- required: true
- description: Order ID
- schema:
- type: string
- - name: id
- in: path
- required: true
- description: Item ID
- schema:
- type: string
- - name: expand
- in: query
- required: false
- description: Comma-separated associations to expand (e.g., variant, variant.product).
- Use dot notation for nested expand (max 4 levels).
- 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 ID
schema:
type: string
responses:
'201':
- description: store credit applied
+ description: import created in mapping state
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- market_id:
- channel_id: ch_UkLWZg9DAJ
- number: R642369123
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- 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:
- - email
- - role_id
- properties:
- email:
- type: string
- role_id:
- type: string
- example: role_xxx
- "/api/v3/admin/invitations/{id}":
- delete:
- summary: Revoke an invitation
- tags:
- - Staff
- security:
- - api_key: []
- bearer_auth: []
- description: "**Required scope:** `write_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
- 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 blank
requestBody:
content:
application/json:
schema:
type: object
+ required:
+ - type
+ - attachment
properties:
- 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 template
tags:
- - Categories
+ - Imports
security:
- 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-key
in: header
@@ -19738,55 +8090,35 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: category_id
- in: path
+ - name: type
+ in: query
required: true
- description: Category ID
+ description: Registered import type, e.g. Spree::Imports::Products.
schema:
type: string
responses:
'200':
- description: products found
+ description: CSV template
content:
- 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 import
tags:
- - Categories
+ - Imports
security:
- 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-key
in: header
@@ -19796,89 +8128,162 @@ paths:
- name: Authorization
in: header
required: true
- description: Bearer token for admin authentication
schema:
type: string
- - name: category_id
+ - name: id
in: path
required: true
- description: Category ID
schema:
type: string
responses:
- '201':
- description: product added
+ '200':
+ description: import found
content:
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 import
tags:
- - Categories
+ - Imports
security:
- 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-key
in: header
@@ -19888,45 +8293,26 @@ paths:
- 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":
+ description: import deleted
+ "/api/v3/admin/imports/{id}/download":
get:
- summary: List imports
+ summary: Download the originally uploaded file
tags:
- Imports
security:
- 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: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
- description: imports found
+ description: CSV file
content:
- 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 processing
tags:
- Imports
security:
- api_key: []
bearer_auth: []
description: |-
- Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`
- and pass the returned `signed_id` as `attachment`. On success the import is in the
- `mapping` state and the response carries the mapping payload: `schema_fields`
- (the canonical columns for the type), `csv_headers`, a `sample_row`, and the
- auto-assigned `mappings`.
-
- Adjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`
- to start processing. Poll `GET /admin/imports/{id}` while `status` is
- `completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.
+ 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: true
schema:
type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
responses:
- '201':
- description: import created in mapping state
+ '200':
+ description: mapping completed, processing queued
content:
application/json:
example:
id: imp_gbHJdmfrXB
- number: IM319349748
+ number: IM358913381
type: Spree::Imports::Products
rows_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_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_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
@@ -20255,16 +8507,8 @@ paths:
- 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'
+ csv_headers: []
+ sample_row: {}
mappings:
- id: immap_UkLWZg9DAJ
schema_field: slug
@@ -20284,83 +8528,83 @@ paths:
required: true
- id: immap_uw2YK1rnl0
schema_field: status
- file_column:
+ file_column: status
required: false
- id: immap_OIJLhNcSbf
schema_field: description
- file_column:
+ file_column: description
required: false
- id: immap_AXs1igzRC6
schema_field: meta_title
- file_column:
+ file_column: meta_title
required: false
- id: immap_p6klVeMgbn
schema_field: meta_description
- file_column:
+ file_column: meta_description
required: false
- id: immap_nJqfPa3Cpe
schema_field: meta_keywords
- file_column:
+ file_column: meta_keywords
required: false
- id: immap_98FqgRua4h
schema_field: tags
- file_column:
+ file_column: tags
required: false
- id: immap_xhoCpeNMWu
schema_field: compare_at_price
- file_column:
+ file_column: compare_at_price
required: false
- id: immap_vEmzDoNU0H
schema_field: currency
- file_column:
+ file_column: currency
required: false
- id: immap_2KY5XM6frI
schema_field: width
- file_column:
+ file_column: width
required: false
- id: immap_HOVtlDrOmL
schema_field: height
- file_column:
+ file_column: height
required: false
- id: immap_ed6l8wVqSM
schema_field: depth
- file_column:
+ file_column: depth
required: false
- id: immap_s18jaGonyx
schema_field: dimensions_unit
- file_column:
+ file_column: dimensions_unit
required: false
- id: immap_GZUcnUYI5A
schema_field: weight
- file_column:
+ file_column: weight
required: false
- id: immap_ROeNhrwyV9
schema_field: weight_unit
- file_column:
+ file_column: weight_unit
required: false
- id: immap_L3pHOn63Vw
schema_field: available_on
- file_column:
+ file_column: available_on
required: false
- id: immap_PQNMcnNFWw
schema_field: discontinue_on
- file_column:
+ file_column: discontinue_on
required: false
- id: immap_C9SrJgpzQ4
schema_field: track_inventory
- file_column:
+ file_column: track_inventory
required: false
- id: immap_YHETxCGlb0
schema_field: inventory_count
- file_column:
+ file_column: inventory_count
required: false
- id: immap_5OQZnCRf8J
schema_field: inventory_backorderable
- file_column:
+ file_column: inventory_backorderable
required: false
- id: immap_F0GX8NaP3Y
schema_field: tax_category
- file_column:
+ file_column: tax_category
required: false
- id: immap_kOKT9MVfb0
schema_field: shipping_category
@@ -20368,110 +8612,7346 @@ paths:
required: false
- id: immap_3uWpPTcf5W
schema_field: image1_src
- file_column:
+ file_column: image1_src
required: false
- id: immap_D6Psx31WaT
schema_field: image2_src
- file_column:
+ file_column: image2_src
required: false
- id: immap_msx3nOJap6
schema_field: image3_src
- file_column:
+ file_column: image3_src
required: false
- id: immap_5CQZnCRf8J
schema_field: option1_name
- file_column:
+ file_column: option1_name
required: false
- id: immap_M2nyloHRUQ
schema_field: option1_value
- file_column:
+ file_column: option1_value
required: false
- id: immap_prklVeMgbn
schema_field: option2_name
- file_column:
+ file_column: option2_name
required: false
- id: immap_so8jaGonyx
schema_field: option2_value
- file_column:
+ file_column: option2_value
required: false
- id: immap_rsClYtECFI
schema_field: option3_name
- file_column:
+ file_column: option3_name
required: false
- id: immap_8DR0I7fEbw
schema_field: option3_value
- file_column:
+ file_column: option3_value
required: false
- id: immap_aAtNvLSUAr
schema_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 Value
required: false
- - id: immap_QiA48cIW7A
- schema_field: category2
- file_column:
+ - name: category1
+ label: Category 1
required: false
- - id: immap_QDA48cIW7A
- schema_field: category3
- file_column:
+ - name: category2
+ label: Category 2
+ required: false
+ - name: category3
+ label: Category 3
required: false
+ csv_headers: []
+ sample_row: {}
+ mappings: []
+ "/api/v3/admin/imports/{import_id}/rows":
+ get:
+ summary: List import rows
+ tags:
+ - 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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 channels
content:
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: integer
requestBody:
content:
application/json:
schema:
type: object
required:
- - type
- - attachment
+ - ids
+ - channel_ids
properties:
- 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 products
tags:
- - Imports
+ - Products
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.
+ 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-key
in: header
@@ -20483,33 +15963,63 @@ paths:
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
+ description: products deleted
content:
- application/json: {}
- text/csv:
+ application/json:
+ example:
+ product_count: 1
schema:
- 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: string
get:
- summary: Show an import
+ summary: List coupon codes for a promotion
tags:
- - Imports
+ - Promotions
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`.
+ 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_codes
parameters:
- name: x-spree-api-key
in: header
@@ -20521,160 +16031,67 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
responses:
'200':
- description: import found
+ description: coupon codes found
content:
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 promotion
tags:
- - Imports
+ - Promotions
security:
- 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_actions
parameters:
- name: x-spree-api-key
in: header
@@ -20686,26 +16103,61 @@ paths:
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
+ '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 promotion
tags:
- - Imports
+ - Promotions
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.
+ 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-key
in: header
@@ -20717,36 +16169,79 @@ paths:
required: true
schema:
type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
responses:
- '200':
- description: CSV file
+ '201':
+ description: action created
content:
- 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 promotion
tags:
- - Imports
+ - Promotions
security:
- api_key: []
bearer_auth: []
- description: |-
- Applies the submitted column mappings, then starts row processing. Omit `mappings`
- to accept the auto-assigned ones from the create response. Returns 422 when a
- required schema field is left unmapped (`details.missing_required_fields`) or a
- file column is assigned twice.
+ 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-key
in: header
@@ -20758,331 +16253,5169 @@ paths:
required: true
schema:
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: header
required: true
schema:
type: string
responses:
'200':
- description: mapping completed, processing queued
+ description: rules found
content:
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
+ 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
+ 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
+ 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
+ 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
+ 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:
+ - email
+ - role_id
+ properties:
+ email:
+ type: string
+ role_id:
+ type: string
+ example: role_xxx
+ "/api/v3/admin/invitations/{id}":
+ delete:
+ summary: Revoke an invitation
+ tags:
+ - Staff
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `write_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
+ 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: object
properties:
- 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 endpoint
tags:
- - Imports
+ - Webhooks
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.
+ 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-key
in: header
@@ -21092,163 +21425,126 @@ paths:
- name: Authorization
in: header
required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
+ description: Bearer token for admin authentication
schema:
type: string
responses:
- '200':
- description: 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 endpoint
tags:
- - Imports
+ - Webhooks
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`.
+ 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-key
in: header
@@ -21258,49 +21554,121 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
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: header
required: true
schema:
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 authentication
schema:
type: string
responses:
'200':
- description: rows found
+ description: webhook endpoint disabled
content:
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 rate
servers:
- url: http://{defaultHost}
variables:
@@ -21313,8 +21681,12 @@ tags:
description: CORS allowlist for storefront and admin client origins
- name: API Keys
description: 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 Fields
description: Custom field definitions for products, variants, customers, and other
resources
@@ -21329,6 +21701,9 @@ tags:
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
@@ -21362,47 +21737,6 @@ tags:
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:
@@ -23386,6 +23720,44 @@ components:
- 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:
@@ -24847,6 +25219,8 @@ components:
type: string
preferred_guest_checkout:
type: boolean
+ preferred_order_routing_strategy:
+ type: string
created_at:
type: string
updated_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: boolean
nullable: true
- payload:
- type: object
created_at:
type: string
updated_at:
@@ -25127,6 +25500,8 @@ components:
delivered_at:
type: string
nullable: true
+ payload:
+ type: object
webhook_endpoint_id:
type: string
webhook_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_url
x-typelizer: true
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 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: yc2xFoGugFWxKRnFoGaLmVwF
user:
id: cus_UkLWZg9DAJ
- first_name: Selina
- last_name: Kuvalis
+ first_name: Candi
+ last_name: Schumm
phone:
accepts_email_marketing: false
- full_name: Selina Kuvalis
+ full_name: Candi Schumm
available_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: eCPfFnyVYDYwYM6tqrHZz1Rd
user:
id: cus_UkLWZg9DAJ
- first_name: Lydia
- last_name: Gaylord
+ first_name: Stephanie
+ last_name: Reichel
phone:
accepts_email_marketing: false
- full_name: Lydia Gaylord
+ full_name: Stephanie Reichel
available_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: xgGeG4wdBFf9AhhoBbBYtMTi
user:
id: cus_UkLWZg9DAJ
- first_name: Teodora
- last_name: Zulauf
+ first_name: Chasidy
+ last_name: Block
phone:
accepts_email_marketing: false
- full_name: Teodora Zulauf
+ full_name: Chasidy Block
available_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-1525934
meta_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-153345
meta_title:
meta_description:
meta_keywords:
@@ -847,16 +847,19 @@ paths:
in_stock: false
backorderable: true
available: 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_EfhxLZ9ck8
thumbnail_url:
tags: []
@@ -958,8 +961,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 1803521
- slug: product-1803521
+ name: Product 180822
+ slug: product-180822
meta_title:
meta_description:
meta_keywords:
@@ -993,7 +996,7 @@ paths:
amount_in_cents: 999
currency: USD
display_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_gbHJdmfrXB
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R559934696
- token: SWyi6Xnc8s491q9yX38WHHqia95sWuvvTMV
+ number: R342007989
+ token: VS7APqPxHRMsNq5MGjzUnLDqWdnR3pkAWaJ
customer_note:
currency: USD
locale: en
@@ -1279,8 +1282,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 923654
- slug: product-923654
+ name: Product 921529
+ slug: product-921529
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1305,7 +1308,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H85053120087
+ number: H45075660320
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1334,7 +1337,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Blythe Beahan
+ name: Dewitt Cruickshank
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1405,9 +1408,9 @@ paths:
- id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R354829125
- token: oEx8WrpxutXH4sfy3QSWxKxLRR6LrkB9Ruu
+ number: R495129612
+ token: Z82RbRQLtzf85HGQSptDokZACx8yh99x8HG
customer_note:
currency: USD
locale: en
@@ -1451,8 +1454,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 91196
- slug: product-91196
+ name: Product 917362
+ slug: product-917362
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1477,7 +1480,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H73938182983
+ number: H07522527247
tracking: U10000
tracking_url:
cost: '100.0'
@@ -1506,7 +1509,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Blythe Beahan
+ name: Dewitt Cruickshank
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -1650,8 +1653,8 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R257765413
- token: SN8FwGqtYYFVTdEo3uNKead8s4i8N8muHz8
+ number: R257847599
+ token: g5bgjgci2Cd6pSfS7nJDQsV8SED1bvREHkz
email:
customer_note:
currency: USD
@@ -1807,16 +1810,16 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R978497785
- token: S2fezdM65stJqJLErtGrDocKgJiv7Jwngty
+ number: R756323828
+ token: xPgVauGASkDehw4w1KFe6diPx4RG4Su6c2f
customer_note:
currency: USD
locale: en
total_quantity: 0
warnings:
- code: line_item_removed
- message: Product 968179 was removed because it was sold out
+ message: Product 964208 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
item_total: '0.0'
@@ -1979,9 +1982,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R368041354
- token: maK9BFEWyBAf3uSiZrLf9b2jxM5Hzcczohc
+ number: R807663331
+ token: adDXkz1zdhq9t54a1RH9pju1nxteWguuP8p
customer_note: Leave at door
currency: USD
locale: en
@@ -2027,8 +2030,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 979703
- slug: product-979703
+ name: Product 973836
+ slug: product-973836
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2053,7 +2056,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H06113541600
+ number: H72063751672
tracking:
tracking_url:
cost: '10.0'
@@ -2082,7 +2085,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Gema Gerlach
+ name: Barabara Yost
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2327,9 +2330,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R465909685
- token: ccYwuB3UzU34SAPCQhaJSMmbtRgtjFcqYuC
+ number: R852645698
+ token: wpKwLJ9pbxKykmxMzCU29fEnj13umouWTxM
customer_note:
currency: USD
locale: en
@@ -2373,8 +2376,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 991797
- slug: product-991797
+ name: Product 992524
+ slug: product-992524
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2399,7 +2402,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H73360485066
+ number: H77553200603
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2428,7 +2431,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Mohammad Johns
+ name: Jeanelle Huels
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2573,15 +2576,15 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R074353110
+ number: R339098687
customer_note:
currency: USD
locale: en
total_quantity: 1
fulfillment_status: backorder
payment_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: 1
currency: USD
- name: Product 1027826
- slug: product-1027826
+ name: Product 1027544
+ slug: product-1027544
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -2639,7 +2642,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_gbHJdmfrXB
- number: H42129838682
+ number: H01647913406
tracking:
tracking_url:
cost: '10.0'
@@ -2668,7 +2671,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Alejandro Barton
+ name: Casie Stracke
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2697,8 +2700,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-ccbd8ddbf360
- number: PCJS29EY
+ response_code: BGS-d60cccf8ad16
+ number: PKV9QA41
amount: '29.99'
display_amount: "$29.99"
status: completed
@@ -2837,9 +2840,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R031332742
- token: 3v1rZK3QouCFRNCgGYTqW1xaeAkdya2rJRD
+ number: R729368018
+ token: gVnZL99E49c4G6Yyp9PzFng2n2ZXX48CCaX
customer_note:
currency: USD
locale: en
@@ -2890,8 +2893,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1212085
- slug: product-1212085
+ name: Product 1218988
+ slug: product-1218988
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2916,7 +2919,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H90931418984
+ number: H27197612367
tracking: U10000
tracking_url:
cost: '100.0'
@@ -2945,7 +2948,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Tijuana Kiehn
+ name: Alicia Kuvalis
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3100,9 +3103,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R709730286
- token: cz8CrtnVBwzW1uo4EDePsVzA2n163ZarZGA
+ number: R837055202
+ token: ynr1cN84XFaGhrBztZ7JdF44DFKsLuqBLtd
customer_note:
currency: USD
locale: en
@@ -3146,8 +3149,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1238006
- slug: product-1238006
+ name: Product 1233716
+ slug: product-1233716
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3172,7 +3175,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H39803900065
+ number: H18878420324
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3201,7 +3204,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Rhea Jerde
+ name: Jenifer Sanford
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3345,9 +3348,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R116842212
- token: Exign8V5gXztDApCkBSj9KDzkADbXh2Gd5n
+ number: R232244636
+ token: 8jj23MK5pmbL5SQkDhyzkTbbSyovPZctTHC
customer_note:
currency: USD
locale: en
@@ -3393,8 +3396,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1251469
- slug: product-1251469
+ name: Product 1254790
+ slug: product-1254790
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3419,7 +3422,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H28744187331
+ number: H92946793801
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3448,7 +3451,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Jerrell Swaniawski
+ name: Idalia Kertzmann
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3606,9 +3609,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R957270534
- token: yLxURFVzueKC6PBPYoFL4f9Tb728TVTF3hK
+ number: R680731425
+ token: jwMuqQRHS39he1xEFAfUJvvEytbMWDxvvV8
customer_note:
currency: USD
locale: en
@@ -3649,8 +3652,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1276735
- slug: product-1276735
+ name: Product 1279749
+ slug: product-1279749
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3675,7 +3678,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H77710785227
+ number: H54318322800
tracking: U10000
tracking_url:
cost: '100.0'
@@ -3704,7 +3707,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Colby Krajcik
+ name: Tyisha Swift
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3733,8 +3736,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260720065855116536
- number: PCMJ1P1X
+ response_code: 1-SC-20260721162039441482
+ number: PL7TNINM
amount: '50.0'
display_amount: "$50.00"
status: checkout
@@ -3914,9 +3917,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R610731091
- token: YEvQkswQotFpWsBfq5C73KcHQiZv4qzcyY7
+ number: R740288025
+ token: JUg9Upygd8RLUPBW4BvpVKYPBg8GCGGoaD6
customer_note:
currency: USD
locale: en
@@ -3960,8 +3963,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1312650
- slug: product-1312650
+ name: Product 1312118
+ slug: product-1312118
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3986,7 +3989,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H06498776597
+ number: H93043543546
tracking: U10000
tracking_url:
cost: '100.0'
@@ -4015,7 +4018,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Yaeko Okuneva
+ name: Kip Rath
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -4044,8 +4047,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260720065857619656
- number: POEO5L7L
+ response_code: 1-SC-20260721162042057199
+ number: P1O3NKS2
amount: '50.0'
display_amount: "$50.00"
status: invalid
@@ -4176,9 +4179,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R511205738
- token: aDLj3SX6a3XwA4Utmpk8pou4kMUunMssZwP
+ number: R004099846
+ token: Knp5XSnseniFgNT1ie7x4AsSyfH9k3wjkyv
customer_note:
currency: USD
locale: en
@@ -4228,8 +4231,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1342359
- slug: product-1342359
+ name: Product 1341957
+ slug: product-1341957
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4258,8 +4261,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1358747
- slug: product-1358747
+ name: Product 1356516
+ slug: product-1356516
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4403,9 +4406,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R895021433
- token: oaVJ4rhjfG8RMTHGBkQuQTvXhihzg1ZHVeb
+ number: R265564023
+ token: rLoUv1N9ih7v1HHnLHFNbMz74hy745LRj86
customer_note:
currency: USD
locale: en
@@ -4452,8 +4455,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1385004
- slug: product-1385004
+ name: Product 1385705
+ slug: product-1385705
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4577,9 +4580,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R697478225
- token: U7k3u92idxnrph2nmobsmmTKUkJ4Q3a5Yo7
+ number: R725463425
+ token: rUu1ard9oJ9uaXHwejmNfDTEkz4cmNsStD6
customer_note:
currency: USD
locale: en
@@ -4726,9 +4729,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_f5970bccd1d2e496f9e2df3a
+ external_id: bogus_081cef0f43a38dc9a23e37b2
external_data:
- client_secret: bogus_secret_2756b4bd68e99a4f
+ client_secret: bogus_secret_a9e3e4aa9cb10c44
customer_external_id:
expires_at:
amount: '110.0'
@@ -4826,7 +4829,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_8f47847cc40a8cbf7ac48adf
+ external_id: bogus_1c83f5b4634029b929befd45
external_data:
client_secret: secret_123
customer_external_id:
@@ -4888,7 +4891,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_d38dc12107c87f70b7184b2e
+ external_id: bogus_863405b319c7d4c7878ee868
external_data:
client_secret: secret_123
customer_external_id:
@@ -4990,7 +4993,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_abdd5b1bc7661044ec25e898
+ external_id: bogus_ab1f491c431fc7c14942b273
external_data:
client_secret: secret_123
customer_external_id:
@@ -5088,7 +5091,7 @@ paths:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
response_code:
- number: P04XI63Y
+ number: PQXDCJKR
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -5195,9 +5198,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R411337296
- token: 9as191w1KNzL89VEXYcbtxTKBsBQHs6jnKp
+ number: R748692900
+ token: ExTC9aN1JGUqdcW9bJjimNYK6bnNmtEydrh
customer_note:
currency: USD
locale: en
@@ -5238,8 +5241,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2002470
- slug: product-2002470
+ name: Product 2004532
+ slug: product-2004532
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5264,7 +5267,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H66674729045
+ number: H39641127215
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5293,7 +5296,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Rickie Torp
+ name: Tawny Boehm
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5322,8 +5325,8 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260720065928328833
- number: PYIMEG7R
+ response_code: 1-SC-20260721162248221498
+ number: P5RKE43T
amount: '10.0'
display_amount: "$10.00"
status: checkout
@@ -5467,9 +5470,9 @@ paths:
id: cart_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R791669896
- token: ChfMRyUkuSQjToc4YjhHUCLgXVZfsn8SLBf
+ number: R465837888
+ token: NfyNCVCWeFDYXiwKYwxy4wx9uXassVWCQAi
customer_note:
currency: USD
locale: en
@@ -5513,8 +5516,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2024256
- slug: product-2024256
+ name: Product 202786
+ slug: product-202786
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5539,7 +5542,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H81050159943
+ number: H67232884262
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5568,7 +5571,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Sidney Fisher
+ name: Shery Lesch
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -5710,7 +5713,7 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R815120791
+ number: R711852325
customer_note:
currency: USD
@@ -5718,7 +5721,7 @@ paths:
total_quantity: 1
fulfillment_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: 1
currency: USD
- name: Product 1425292
- slug: product-1425292
+ name: Product 1427596
+ slug: product-1427596
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5776,7 +5779,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H02137223133
+ number: H62333056142
tracking: U10000
tracking_url:
cost: '100.0'
@@ -5805,7 +5808,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Paulina Barrows
+ name: Ileen Brekke
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6742,15 +6745,15 @@ paths:
- id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R602488096
+ number: R398862344
customer_note:
currency: USD
locale: en
total_quantity: 1
fulfillment_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: 1
currency: USD
- name: Product 1119914
- slug: product-1119914
+ name: Product 1119809
+ slug: product-1119809
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6808,7 +6811,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H94775392862
+ number: H43385476115
tracking: U10000
tracking_url:
cost: '100.0'
@@ -6837,7 +6840,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Rosamond Pollich
+ name: Sophie Hermann
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7000,15 +7003,15 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R049918057
+ number: R755711983
customer_note:
currency: USD
locale: en
total_quantity: 1
fulfillment_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: 1
currency: USD
- name: Product 1133613
- slug: product-1133613
+ name: Product 1133496
+ slug: product-1133496
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -7066,7 +7069,7 @@ paths:
digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
- number: H49919599290
+ number: H59093298847
tracking: U10000
tracking_url:
cost: '100.0'
@@ -7095,7 +7098,7 @@ paths:
stock_location:
id: sloc_UkLWZg9DAJ
state_abbr: NY
- name: Ivonne Gleason
+ name: Malinda Williamson
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '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: wNUQgozZCPBq46sjCR6uYn99
user:
id: cus_UkLWZg9DAJ
@@ -7233,10 +7236,10 @@ paths:
newsletter_subscriber:
id: sub_UkLWZg9DAJ
- 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_UkLWZg9DAJ
customer_groups: []
schema:
@@ -7339,12 +7342,12 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
- first_name: Nola
- last_name: Toy
+ first_name: Kathrine
+ last_name: Yost
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Nola Toy
+ full_name: Kathrine Yost
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -7480,7 +7483,7 @@ paths:
application/json:
example:
id: cus_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -7671,7 +7674,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: CE747A2902E0F8E6
+ code: F5FF4BFD9C5C9A38
status: active
currency: USD
amount: '10.0'
@@ -7767,7 +7770,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: A85DF7530D5427D2
+ code: 2FA5A3CC7B0E77B3
status: active
currency: USD
amount: '10.0'
@@ -7839,8 +7842,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_5917b4c5313a6144a001f309
- external_client_secret: bogus_seti_secret_276edea39079a17f
+ external_id: bogus_seti_59a8f0cb4097daca5377ad0e
+ external_client_secret: bogus_seti_secret_d79d0cb5e151cbf1
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7939,8 +7942,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_db6f308c532481227c001535
- external_client_secret: seti_secret_f71e16082a1cfe98ed3d8094
+ external_id: seti_test_f9f0bd37a53046a006fe4795
+ external_client_secret: seti_secret_e47007878c2b2ca3ca3a686d
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8016,8 +8019,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_6277a5f68ea454abc328de35
- external_client_secret: seti_secret_3ab47824489c4e90391a2e52
+ external_id: seti_test_544613606c84fda77853c3dc
+ external_client_secret: seti_secret_fab5517e19d16c860e4d704b
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8958,7 +8961,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: EkGxSWB17nCseQYJoBp642fT
+ token: xtTAEirKdUyHVmeVjEvpWkCD
is_default: false
is_private: true
meta:
@@ -9034,7 +9037,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: YgLGByFdHn5x4npJg2qryZYp
+ token: ecn6DbXfgwBmXYxxi29izAKE
is_default: false
is_private: true
schema:
@@ -9130,7 +9133,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: T53yXsSRd1tCrW5ocQtYkcB5
+ token: m5StTE9sAQNmwr8sEJgXx4Kr
is_default: false
is_private: true
schema:
@@ -9192,7 +9195,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: NDYqPdkWYVCnXCMvRVtA3NQ2
+ token: vMrpCQxBoVg6pAhPnA7DJfCs
is_default: false
is_private: true
schema:
@@ -9473,11 +9476,11 @@ paths:
application/json:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-07-20T06:59:05.321Z'
- updated_at: '2026-07-20T06:59:05.324Z'
+ 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_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9556,10 +9559,10 @@ paths:
example:
id: sub_UkLWZg9DAJ
- 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_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-13c46914-2a75-4c79-8151-67de9795911e
+ slug: privacy-policy-8800ef1a-581d-4c89-9e7f-3e199290b6c2
body: 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: 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:
diff --git a/docs/docs.json b/docs/docs.json
index 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.md
index 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_class
end
```
-### 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:
-
-```
+```text
PATCH /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)" ab
2. **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.md
index 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 accounts
The gated wholesale portal's apply form collects a company name. Considered
diff --git a/packages/admin-sdk/examples/order-routing-rules/create.ts b/packages/admin-sdk/examples/order-routing-rules/create.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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:example
diff --git a/packages/admin-sdk/examples/order-routing-rules/list.ts b/packages/admin-sdk/examples/order-routing-rules/list.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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: string
diff --git a/packages/admin-sdk/src/types/generated/OrderRoutingRule.ts b/packages/admin-sdk/src/types/generated/OrderRoutingRule.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.json
index 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 file
diff --git a/packages/cli/src/generated/resource-paths.json b/packages/cli/src/generated/resource-paths.json
index 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 file
diff --git a/packages/dashboard-core/src/lib/permissions.ts b/packages/dashboard-core/src/lib/permissions.ts
index 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.ts
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.tsx
index 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>
<Button
diff --git a/packages/dashboard/src/schemas/channel.ts b/packages/dashboard/src/schemas/channel.ts
index 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 const
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb b/spree/api/app/controllers/concerns/spree/api/v3/scoped_authorization.rb
index 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 Spree
self.class._scoped_resource
end
- # 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 rather
diff --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.rb
new file mode 100644
index 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
+end
diff --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.rb
index 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 Spree
params.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.rb
index 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 Spree
params.permit(:type, preferences: {})
end
+ # `types`/`calculators` are read-only discovery — read scope + :show ability.
+ def read_actions
+ super + %w[types calculators]
+ end
+
def set_parent
return 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.rb
index 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 Spree
params.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_parent
return 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.rb
index 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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/store_serializer.rb
index 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 Spree
preferred_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: :iso8601
attribute :url, &:storefront_url
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index bd6d4ade1a..71ae6e96e5 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -345,8 +345,15 @@ Spree::Core::Engine.add_routes do
post :add_products
post :remove_products
end
+
+ 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_fieldable
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index ba1a3c6a33..9bf95b5f13 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -202,6 +202,7 @@ module Spree
admin_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.rb
new file mode 100644
index 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
+end
diff --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.rb
new file mode 100644
index 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
+end
diff --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.rb
new file mode 100644
index 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
+end
diff --git a/spree/api/spec/swagger_helper.rb b/spree/api/spec/swagger_helper.rb
index 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.rb
index 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 Spree
attribute :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 Spree
validate :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 Spree
raise 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.rb
index 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 Spree
can :manage, Spree::ReimbursementType
can :manage, Spree::ReturnReason
- # Channels
+ # Channels + per-channel order routing rules
can :manage, Spree::Channel
+ can :manage, Spree::OrderRoutingRule
# Restrictions on immutable types
cannot [:edit, :update], Spree::RefundReason, mutable: false
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 9ddc0f99c2..87af144a8e 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -1190,6 +1190,16 @@ en:
strategies:
legacy: Legacy
rules: 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 location
order_summary: Order Summary
order_total: Order Total
orders: Orders
diff --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.rb
new file mode 100644
index 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
+end
diff --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.rb
new file mode 100644
index 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
+end
diff --git a/spree/core/spec/models/spree/order_routing_rule_spec.rb b/spree/core/spec/models/spree/order_routing_rule_spec.rb
index 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 do
end
it '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_valid
end
@@ -38,6 +41,31 @@ RSpec.describe Spree::OrderRoutingRule, type: :model do
expect(rule).not_to be_valid
expect(rule.errors[:type]).to be_present
end
+
+ 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([])
+ end
end
describe 'Spree.order_routing.rules' do
@@ -89,7 +117,7 @@ RSpec.describe Spree::OrderRoutingRule, type: :model do
let(: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