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.

Store rich text as sanitized HTML instead of Action Text (#14417)

Damian Legawiec7e35951361a6
diff --git a/.changeset/rich-text-html-write-contract.md b/.changeset/rich-text-html-write-contract.md
new file mode 100644
index 0000000000..1602583e99
--- /dev/null
+++ b/.changeset/rich-text-html-write-contract.md
@@ -0,0 +1,15 @@
+---
+'@spree/admin-sdk': patch
+'@spree/cli': patch
+---
+
+Rich-text fields read as plain text plus HTML.
+
+Spree 6.0 stores rich text as sanitized HTML in plain text columns instead of Action Text. The write params are unchanged — `description` and `internal_note` still take the value, and that value is HTML.
+
+What changed is the read side:
+
+- `internal_note_html` is now readable on `Order`, and `internal_note` (plain text) on `Customer`. Previously the order serializer returned only plain text and the customer serializer only HTML; both now return the pair.
+- `description` returns tag-stripped plain text, with the markup under `description_html`. Hydrate an editor from `description_html`, not `description`.
+
+The field stores HTML, so send markup — a plain-text value with newlines in it renders as one run-on line.
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 02b2b48bcc..17211ed592 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -92,16 +92,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImI0YmQ3YjlhLTcwMjgtNDA2My1iZDU0LWVmZjY2Yzk4MDI1MSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2MTM2MDU0fQ.6lPz4TORaiwgXqxJC-52aXVz7ha6VOX5DjR5D9pNge8
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6Ijc0MDlmYTcxLTJmYTgtNGI4YS1iYzM3LTI3YzA1MDZhMzJkZCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2MzQ4ODg2fQ.LnAWObghW4rAznjIWDlhInuVV6ZMUxI1fNuz89E9Klc
user:
id: adm_UkLWZg9DAJ
- first_name: Shasta
- last_name: Dickens
- full_name: Shasta Dickens
+ first_name: Mira
+ last_name: Kreiger
+ full_name: Mira Kreiger
selected_locale:
- created_at: '2026-08-07T20:49:13.982Z'
- updated_at: '2026-08-07T20:49:13.982Z'
+ created_at: '2026-08-10T07:56:26.719Z'
+ updated_at: '2026-08-10T07:56:26.719Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -204,16 +204,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImE3MmYyMzM4LTdhZmYtNDAyYS1iNzg1LTI5M2EyZDM5MmU1ZSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2MTM2MDU0fQ.d_hnpYdCshcS2z5rVPZptmTcvHwDCAJK6DLB9i_9Jhg
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjhiZmYyMTFkLTdkYmYtNDNkNC04M2RiLTQzMzUxM2ZmZmJlOCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2MzQ4ODg2fQ.1fE3MsxrG4pmzLuwzFXJDkmiAxEnVpB08AvU8Q8A_wY
user:
id: adm_UkLWZg9DAJ
- first_name: Donovan
- last_name: Nikolaus
- full_name: Donovan Nikolaus
+ first_name: Luciano
+ last_name: Kuhic
+ full_name: Luciano Kuhic
selected_locale:
- created_at: '2026-08-07T20:49:14.041Z'
- updated_at: '2026-08-07T20:49:14.041Z'
+ created_at: '2026-08-10T07:56:26.777Z'
+ updated_at: '2026-08-10T07:56:26.777Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -315,13 +315,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Leoma
- last_name: Kertzmann
- full_name: Leoma Kertzmann
+ first_name: Lucilla
+ last_name: Jacobs
+ full_name: Lucilla Jacobs
selected_locale:
- created_at: '2026-08-07T20:49:18.129Z'
- updated_at: '2026-08-07T20:49:18.129Z'
+ created_at: '2026-08-10T07:56:32.013Z'
+ updated_at: '2026-08-10T07:56:32.013Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -430,13 +430,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Erica
- last_name: Williamson
- full_name: Erica Williamson
+ first_name: Rosena
+ last_name: Auer
+ full_name: Rosena Auer
selected_locale: de
- created_at: '2026-08-07T20:49:18.165Z'
- updated_at: '2026-08-07T20:49:18.176Z'
+ created_at: '2026-08-10T07:56:32.063Z'
+ updated_at: '2026-08-10T07:56:32.075Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -622,16 +622,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImVkYTU5Y2U4LWY4NTUtNDY5MC1iZDViLTU3NWU1ZjdlOGUxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2MTM5MzYzfQ.Q90fS3JVvOb5YUQlTWspNLkwybS-p6GnzksGkTQXIKU
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRkZDlkNjFkLWFmMzEtNDZmNi1iMzlhLTFlZTFiOGFkMTAyMiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2MzUyMTk3fQ.nfCVXQpi8m6VurSwUvaFewJNkT-UTIWR3lX2J6aJEmA
user:
id: adm_UkLWZg9DAJ
- first_name: Jeremy
- last_name: Fay
- full_name: Jeremy Fay
+ first_name: Ellen
+ last_name: Christiansen
+ full_name: Ellen Christiansen
selected_locale:
- created_at: '2026-08-07T20:49:23.246Z'
- updated_at: '2026-08-07T20:49:23.259Z'
+ created_at: '2026-08-10T07:56:37.792Z'
+ updated_at: '2026-08-10T07:56:37.805Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -750,8 +750,8 @@ paths:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-07T20:49:13.529Z'
- updated_at: '2026-08-07T20:49:13.529Z'
+ created_at: '2026-08-10T07:56:26.283Z'
+ updated_at: '2026-08-10T07:56:26.283Z'
meta:
page: 1
limit: 25
@@ -835,8 +835,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
- created_at: '2026-08-07T20:49:13.611Z'
- updated_at: '2026-08-07T20:49:13.611Z'
+ created_at: '2026-08-10T07:56:26.342Z'
+ updated_at: '2026-08-10T07:56:26.342Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -923,8 +923,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-07T20:49:13.690Z'
- updated_at: '2026-08-07T20:49:13.690Z'
+ created_at: '2026-08-10T07:56:26.373Z'
+ updated_at: '2026-08-10T07:56:26.373Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
@@ -985,8 +985,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
- created_at: '2026-08-07T20:49:13.739Z'
- updated_at: '2026-08-07T20:49:13.756Z'
+ created_at: '2026-08-10T07:56:26.433Z'
+ updated_at: '2026-08-10T07:56:26.469Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -1106,34 +1106,34 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-07T20:49:13.807Z'
- updated_at: '2026-08-07T20:49:13.807Z'
+ created_at: '2026-08-10T07:56:26.568Z'
+ updated_at: '2026-08-10T07:56:26.568Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_6BvYcjPTJwyQAXKdEyGSrVE7
+ plaintext_token: pk_CvQh2CR8QJeczDnWMeeoDsmU
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_fLgdntS6d
+ token_prefix: sk_rKS2a7miG
scopes:
- write_all
- created_at: '2026-08-07T20:49:13.808Z'
- updated_at: '2026-08-07T20:49:13.808Z'
+ created_at: '2026-08-10T07:56:26.569Z'
+ updated_at: '2026-08-10T07:56:26.569Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: ratione
+ name: aut
key_type: secret
- token_prefix: sk_NQfrhhbe9
+ token_prefix: sk_xkfQGTjyC
scopes:
- write_all
- created_at: '2026-08-07T20:49:13.809Z'
- updated_at: '2026-08-07T20:49:13.809Z'
+ created_at: '2026-08-10T07:56:26.570Z'
+ updated_at: '2026-08-10T07:56:26.570Z'
revoked_at:
last_used_at:
channel_id:
@@ -1200,16 +1200,16 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_N1LesvL3c
+ token_prefix: sk_6t49LLaWn
scopes:
- read_orders
- created_at: '2026-08-07T20:49:13.844Z'
- updated_at: '2026-08-07T20:49:13.844Z'
+ created_at: '2026-08-10T07:56:26.606Z'
+ updated_at: '2026-08-10T07:56:26.606Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: sk_N1LesvL3cAbyKnG9YXABk9eT
- created_by_email: [email protected]
+ plaintext_token: sk_6t49LLaWnuWFDyd5omMydEV5
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -1298,12 +1298,12 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-07T20:49:13.868Z'
- updated_at: '2026-08-07T20:49:13.868Z'
+ created_at: '2026-08-10T07:56:26.631Z'
+ updated_at: '2026-08-10T07:56:26.631Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_Lenc9AgL1KivRzku2RUYw7ku
+ plaintext_token: pk_usSFrW7JvLnimit2zEUanpzx
created_by_email:
patch:
summary: Update an API key
@@ -1357,11 +1357,11 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration (renamed)
key_type: secret
- token_prefix: sk_HhFudTbk8
+ token_prefix: sk_8eArFGMy8
scopes:
- write_all
- created_at: '2026-08-07T20:49:13.887Z'
- updated_at: '2026-08-07T20:49:13.903Z'
+ created_at: '2026-08-10T07:56:26.649Z'
+ updated_at: '2026-08-10T07:56:26.662Z'
revoked_at:
last_used_at:
channel_id:
@@ -1458,13 +1458,13 @@ paths:
application/json:
example:
id: key_EfhxLZ9ck8
- name: temporibus
+ name: itaque
key_type: secret
- token_prefix: sk_2J2UvtYWk
+ token_prefix: sk_Q3t8ozQvU
scopes:
- write_all
- created_at: '2026-08-07T20:49:13.927Z'
- updated_at: '2026-08-07T20:49:13.927Z'
+ created_at: '2026-08-10T07:56:26.688Z'
+ updated_at: '2026-08-10T07:56:26.688Z'
revoked_at:
last_used_at:
channel_id:
@@ -1522,12 +1522,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_4RF2FQkm5
+ token_prefix: sk_14PrTLo9d
scopes:
- write_all
- created_at: '2026-08-07T20:49:13.957Z'
- updated_at: '2026-08-07T20:49:13.973Z'
- revoked_at: '2026-08-07T20:49:13.973Z'
+ created_at: '2026-08-10T07:56:26.698Z'
+ updated_at: '2026-08-10T07:56:26.712Z'
+ revoked_at: '2026-08-10T07:56:26.712Z'
last_used_at:
channel_id:
plaintext_token:
@@ -1604,8 +1604,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-07T20:49:14.105Z'
- updated_at: '2026-08-07T20:49:14.105Z'
+ created_at: '2026-08-10T07:56:26.846Z'
+ updated_at: '2026-08-10T07:56:26.846Z'
meta:
page: 1
limit: 25
@@ -1679,8 +1679,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-07T20:49:14.154Z'
- updated_at: '2026-08-07T20:49:14.161Z'
+ created_at: '2026-08-10T07:56:26.923Z'
+ updated_at: '2026-08-10T07:56:26.931Z'
schema:
"$ref": "#/components/schemas/Category"
'422':
@@ -1786,8 +1786,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-07T20:49:14.224Z'
- updated_at: '2026-08-07T20:49:14.224Z'
+ created_at: '2026-08-10T07:56:26.975Z'
+ updated_at: '2026-08-10T07:56:26.975Z'
schema:
"$ref": "#/components/schemas/Category"
'404':
@@ -1857,8 +1857,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-07T20:49:14.275Z'
- updated_at: '2026-08-07T20:49:14.298Z'
+ created_at: '2026-08-10T07:56:27.030Z'
+ updated_at: '2026-08-10T07:56:27.055Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -1973,8 +1973,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-07T20:49:14.350Z'
- updated_at: '2026-08-07T20:49:14.374Z'
+ created_at: '2026-08-10T07:56:27.105Z'
+ updated_at: '2026-08-10T07:56:27.129Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -2086,8 +2086,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 18111
- slug: product-18111
+ name: Product 11174
+ slug: product-11174
meta_title:
meta_description:
meta_keywords:
@@ -2099,21 +2099,25 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Alias iste possimus sunt odio. Consequatur aperiam exercitationem
- consequuntur accusamus repellendus. Eligendi sunt dignissimos nihil
- quis ipsam eveniet deleniti. Iure incidunt id accusamus temporibus
- debitis ipsum occaecati. Quam debitis voluptatem magnam natus nobis
- perspiciatis. Nihil earum repudiandae consequuntur ratione ab perspiciatis.
- Eligendi exercitationem hic animi modi earum iste. Dignissimos nemo
- officiis repudiandae eveniet. Velit itaque unde quasi amet culpa
- illo ducimus sit. Enim porro dignissimos tenetur magnam deserunt
- fuga. Culpa dignissimos alias velit omnis vero. Expedita nulla velit
- natus deserunt. Qui fugit autem ducimus suscipit nisi omnis quibusdam
- itaque. Est tempora recusandae optio perferendis.
+ description: Repudiandae provident error deserunt dolor explicabo
+ esse assumenda voluptas. Quia suscipit quae explicabo ducimus autem
+ quis ut consectetur. Nemo autem nisi velit optio a perspiciatis
+ nostrum. A maiores rerum eligendi corporis aliquid magni odit. Vitae
+ at ea eveniet atque aspernatur accusamus dolores. Explicabo nostrum
+ nesciunt suscipit natus quod. Distinctio vero temporibus recusandae
+ aliquid molestiae veniam magni. Nulla modi sint minima autem error.
+ Vero reiciendis omnis animi error iure. Nobis quis illum ipsam distinctio
+ laborum doloribus et sapiente. Voluptas id ea quae sunt. Cumque
+ nihil veritatis asperiores vel ipsam. Nihil inventore ullam iure
+ omnis eius dicta. Maxime necessitatibus nisi vero laborum explicabo
+ quas totam. Totam perferendis et aliquid fugiat occaecati distinctio
+ quod. Unde totam voluptates distinctio quidem delectus. Cumque sunt
+ cum iusto aut. Sapiente quos laborum repellendus aspernatur.
description_html: |-
- Alias iste possimus sunt odio. Consequatur aperiam exercitationem consequuntur accusamus repellendus. Eligendi sunt dignissimos nihil quis ipsam eveniet deleniti. Iure incidunt id accusamus temporibus debitis ipsum occaecati.
- Quam debitis voluptatem magnam natus nobis perspiciatis. Nihil earum repudiandae consequuntur ratione ab perspiciatis. Eligendi exercitationem hic animi modi earum iste. Dignissimos nemo officiis repudiandae eveniet. Velit itaque unde quasi amet culpa illo ducimus sit.
- Enim porro dignissimos tenetur magnam deserunt fuga. Culpa dignissimos alias velit omnis vero. Expedita nulla velit natus deserunt. Qui fugit autem ducimus suscipit nisi omnis quibusdam itaque. Est tempora recusandae optio perferendis.
+ Repudiandae provident error deserunt dolor explicabo esse assumenda voluptas. Quia suscipit quae explicabo ducimus autem quis ut consectetur. Nemo autem nisi velit optio a perspiciatis nostrum. A maiores rerum eligendi corporis aliquid magni odit. Vitae at ea eveniet atque aspernatur accusamus dolores.
+ Explicabo nostrum nesciunt suscipit natus quod. Distinctio vero temporibus recusandae aliquid molestiae veniam magni. Nulla modi sint minima autem error.
+ Vero reiciendis omnis animi error iure. Nobis quis illum ipsam distinctio laborum doloribus et sapiente. Voluptas id ea quae sunt. Cumque nihil veritatis asperiores vel ipsam. Nihil inventore ullam iure omnis eius dicta.
+ Maxime necessitatibus nisi vero laborum explicabo quas totam. Totam perferendis et aliquid fugiat occaecati distinctio quod. Unde totam voluptates distinctio quidem delectus. Cumque sunt cum iusto aut. Sapiente quos laborum repellendus aspernatur.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -2128,14 +2132,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:14.484Z'
- updated_at: '2026-08-07T20:49:14.484Z'
+ created_at: '2026-08-10T07:56:27.273Z'
+ updated_at: '2026-08-10T07:56:27.273Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-07T20:49:14.464Z'
- updated_at: '2026-08-07T20:49:14.493Z'
+ created_at: '2026-08-10T07:56:27.247Z'
+ updated_at: '2026-08-10T07:56:27.283Z'
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
@@ -2305,8 +2309,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-07T20:49:13.292Z'
- updated_at: '2026-08-07T20:49:13.292Z'
+ created_at: '2026-08-10T07:56:26.007Z'
+ updated_at: '2026-08-10T07:56:26.007Z'
- id: ch_gbHJdmfrXB
name: Wholesale
code: wholesale
@@ -2317,8 +2321,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-07T20:49:14.666Z'
- updated_at: '2026-08-07T20:49:14.666Z'
+ created_at: '2026-08-10T07:56:27.472Z'
+ updated_at: '2026-08-10T07:56:27.472Z'
meta:
page: 1
limit: 25
@@ -2403,8 +2407,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-07T20:49:14.721Z'
- updated_at: '2026-08-07T20:49:14.721Z'
+ created_at: '2026-08-10T07:56:27.536Z'
+ updated_at: '2026-08-10T07:56:27.536Z'
requestBody:
content:
application/json:
@@ -2502,8 +2506,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-07T20:49:14.731Z'
- updated_at: '2026-08-07T20:49:14.731Z'
+ created_at: '2026-08-10T07:56:27.550Z'
+ updated_at: '2026-08-10T07:56:27.550Z'
patch:
summary: Update a channel
tags:
@@ -2557,8 +2561,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access: login_required
preferred_guest_checkout: false
- created_at: '2026-08-07T20:49:14.760Z'
- updated_at: '2026-08-07T20:49:14.781Z'
+ created_at: '2026-08-10T07:56:27.580Z'
+ updated_at: '2026-08-10T07:56:27.602Z'
requestBody:
content:
application/json:
@@ -2840,8 +2844,8 @@ paths:
- id: orule_UkLWZg9DAJ
position: 1
active: true
- created_at: '2026-08-07T20:49:13.297Z'
- updated_at: '2026-08-07T20:49:13.297Z'
+ created_at: '2026-08-10T07:56:26.012Z'
+ updated_at: '2026-08-10T07:56:26.012Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -2852,8 +2856,8 @@ paths:
- id: orule_gbHJdmfrXB
position: 2
active: true
- created_at: '2026-08-07T20:49:13.300Z'
- updated_at: '2026-08-07T20:49:13.300Z'
+ created_at: '2026-08-10T07:56:26.018Z'
+ updated_at: '2026-08-10T07:56:26.018Z'
type: minimize_splits
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -2864,8 +2868,8 @@ paths:
- id: orule_EfhxLZ9ck8
position: 3
active: true
- created_at: '2026-08-07T20:49:13.303Z'
- updated_at: '2026-08-07T20:49:13.303Z'
+ created_at: '2026-08-10T07:56:26.021Z'
+ updated_at: '2026-08-10T07:56:26.021Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -2930,8 +2934,8 @@ paths:
id: orule_VqXmZF31wY
position: 3
active: true
- created_at: '2026-08-07T20:49:19.032Z'
- updated_at: '2026-08-07T20:49:19.032Z'
+ created_at: '2026-08-10T07:56:33.057Z'
+ updated_at: '2026-08-10T07:56:33.057Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -3026,8 +3030,8 @@ paths:
id: orule_UkLWZg9DAJ
position: 2
active: false
- created_at: '2026-08-07T20:49:13.297Z'
- updated_at: '2026-08-07T20:49:19.074Z'
+ created_at: '2026-08-10T07:56:26.012Z'
+ updated_at: '2026-08-10T07:56:33.103Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -3215,8 +3219,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-07T20:49:15.485Z'
- updated_at: '2026-08-07T20:49:15.485Z'
+ created_at: '2026-08-10T07:56:28.382Z'
+ updated_at: '2026-08-10T07:56:28.382Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -3227,8 +3231,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_custom_order_notes
- created_at: '2026-08-07T20:49:15.486Z'
- updated_at: '2026-08-07T20:49:15.486Z'
+ created_at: '2026-08-10T07:56:28.384Z'
+ updated_at: '2026-08-10T07:56:28.384Z'
meta:
page: 1
limit: 25
@@ -3297,8 +3301,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_origin
- created_at: '2026-08-07T20:49:15.521Z'
- updated_at: '2026-08-07T20:49:15.521Z'
+ created_at: '2026-08-10T07:56:28.424Z'
+ updated_at: '2026-08-10T07:56:28.424Z'
requestBody:
content:
application/json:
@@ -3326,8 +3330,8 @@ paths:
description: Owner class, e.g. `Spree::Product`
storefront_visible:
type: boolean
- description: 'When false, definition is admin-only (was `display_on:
- back_end`)'
+ description: When false, the definition is admin-only and never
+ exposed in the Store API
searchable:
type: boolean
description: When true, values are included in storefront product
@@ -3406,8 +3410,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-07T20:49:15.525Z'
- updated_at: '2026-08-07T20:49:15.525Z'
+ created_at: '2026-08-10T07:56:28.429Z'
+ updated_at: '2026-08-10T07:56:28.429Z'
patch:
summary: Update a custom field definition
tags:
@@ -3467,8 +3471,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-07T20:49:15.545Z'
- updated_at: '2026-08-07T20:49:15.561Z'
+ created_at: '2026-08-10T07:56:28.450Z'
+ updated_at: '2026-08-10T07:56:28.467Z'
requestBody:
content:
application/json:
@@ -3614,14 +3618,14 @@ paths:
name: VIPs
description: Top spenders
customers_count: 0
- created_at: '2026-08-07T20:49:15.588Z'
- updated_at: '2026-08-07T20:49:15.588Z'
+ created_at: '2026-08-10T07:56:28.496Z'
+ updated_at: '2026-08-10T07:56:28.496Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
- created_at: '2026-08-07T20:49:15.597Z'
- updated_at: '2026-08-07T20:49:15.597Z'
+ created_at: '2026-08-10T07:56:28.497Z'
+ updated_at: '2026-08-10T07:56:28.497Z'
meta:
page: 1
limit: 25
@@ -3710,8 +3714,8 @@ paths:
name: Wholesale 2
description: B2B accounts
customers_count: 1
- created_at: '2026-08-07T20:49:15.670Z'
- updated_at: '2026-08-07T20:49:15.670Z'
+ created_at: '2026-08-10T07:56:28.573Z'
+ updated_at: '2026-08-10T07:56:28.573Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -3820,23 +3824,24 @@ paths:
name: VIPs
description: Top spenders
customers_count: 1
- created_at: '2026-08-07T20:49:15.724Z'
- updated_at: '2026-08-07T20:49:15.724Z'
+ created_at: '2026-08-10T07:56:28.641Z'
+ updated_at: '2026-08-10T07:56:28.641Z'
customers:
- id: cust_UkLWZg9DAJ
- first_name: Jere
- last_name: Okuneva
+ first_name: Dalene
+ last_name: Lindgren
phone:
accepts_email_marketing: false
- full_name: Jere Okuneva
+ full_name: Dalene Lindgren
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-07T20:49:15.728Z'
- updated_at: '2026-08-07T20:49:15.728Z'
+ created_at: '2026-08-10T07:56:28.644Z'
+ updated_at: '2026-08-10T07:56:28.644Z'
tags: []
+ internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
@@ -3914,8 +3919,8 @@ paths:
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
- created_at: '2026-08-07T20:49:15.781Z'
- updated_at: '2026-08-07T20:49:15.798Z'
+ created_at: '2026-08-10T07:56:28.710Z'
+ updated_at: '2026-08-10T07:56:28.727Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -4074,8 +4079,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-08-07T20:49:15.859Z'
- updated_at: '2026-08-07T20:49:15.859Z'
+ created_at: '2026-08-10T07:56:28.909Z'
+ updated_at: '2026-08-10T07:56:28.909Z'
customer_id: cust_UkLWZg9DAJ
meta:
page: 1
@@ -4168,8 +4173,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-08-07T20:49:15.905Z'
- updated_at: '2026-08-07T20:49:15.905Z'
+ created_at: '2026-08-10T07:56:29.099Z'
+ updated_at: '2026-08-10T07:56:29.099Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -4283,8 +4288,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-08-07T20:49:15.915Z'
- updated_at: '2026-08-07T20:49:15.932Z'
+ created_at: '2026-08-10T07:56:29.114Z'
+ updated_at: '2026-08-10T07:56:29.135Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -4423,8 +4428,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-07T20:49:15.983Z'
- updated_at: '2026-08-07T20:49:15.983Z'
+ created_at: '2026-08-10T07:56:29.201Z'
+ updated_at: '2026-08-10T07:56:29.201Z'
meta:
page: 1
limit: 25
@@ -4514,8 +4519,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-07T20:49:16.014Z'
- updated_at: '2026-08-07T20:49:16.014Z'
+ created_at: '2026-08-10T07:56:29.235Z'
+ updated_at: '2026-08-10T07:56:29.235Z'
delete:
summary: Delete a customer credit card
tags:
@@ -4640,8 +4645,8 @@ paths:
currency: USD
memo:
metadata: {}
- created_at: '2026-08-07T20:49:16.077Z'
- updated_at: '2026-08-07T20:49:16.077Z'
+ created_at: '2026-08-10T07:56:29.334Z'
+ updated_at: '2026-08-10T07:56:29.334Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -4720,8 +4725,8 @@ paths:
currency: USD
memo: Goodwill
metadata: {}
- created_at: '2026-08-07T20:49:16.148Z'
- updated_at: '2026-08-07T20:49:16.148Z'
+ created_at: '2026-08-10T07:56:29.398Z'
+ updated_at: '2026-08-10T07:56:29.398Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_gbHJdmfrXB
category_id: sccat_UkLWZg9DAJ
@@ -4816,8 +4821,8 @@ paths:
currency: USD
memo: Updated
metadata: {}
- created_at: '2026-08-07T20:49:16.169Z'
- updated_at: '2026-08-07T20:49:16.186Z'
+ created_at: '2026-08-10T07:56:29.418Z'
+ updated_at: '2026-08-10T07:56:29.438Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -4976,9 +4981,10 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-07T20:49:16.226Z'
- updated_at: '2026-08-07T20:49:16.226Z'
+ created_at: '2026-08-10T07:56:29.493Z'
+ updated_at: '2026-08-10T07:56:29.493Z'
tags: []
+ internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
@@ -5059,9 +5065,10 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-07T20:49:16.267Z'
- updated_at: '2026-08-07T20:49:16.267Z'
+ created_at: '2026-08-10T07:56:29.556Z'
+ updated_at: '2026-08-10T07:56:29.556Z'
tags: []
+ internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
@@ -5174,9 +5181,10 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-07T20:49:16.278Z'
- updated_at: '2026-08-07T20:49:16.278Z'
+ created_at: '2026-08-10T07:56:29.569Z'
+ updated_at: '2026-08-10T07:56:29.569Z'
tags: []
+ internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
@@ -5247,9 +5255,10 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-07T20:49:16.302Z'
- updated_at: '2026-08-07T20:49:16.320Z'
+ created_at: '2026-08-10T07:56:29.600Z'
+ updated_at: '2026-08-10T07:56:29.624Z'
tags: []
+ internal_note:
internal_note_html:
default_billing_address_id:
default_shipping_address_id:
@@ -5693,10 +5702,10 @@ paths:
example:
data:
- id: exp_UkLWZg9DAJ
- number: EF937116057
+ number: EF542828879
format: csv
- created_at: '2026-08-07T20:49:16.639Z'
- updated_at: '2026-08-07T20:49:16.639Z'
+ created_at: '2026-08-10T07:56:30.037Z'
+ updated_at: '2026-08-10T07:56:30.037Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -5767,10 +5776,10 @@ paths:
application/json:
example:
id: exp_gbHJdmfrXB
- number: EF208944152
+ number: EF974245200
format: csv
- created_at: '2026-08-07T20:49:16.675Z'
- updated_at: '2026-08-07T20:49:16.675Z'
+ created_at: '2026-08-10T07:56:30.074Z'
+ updated_at: '2026-08-10T07:56:30.074Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -5867,10 +5876,10 @@ paths:
application/json:
example:
id: exp_UkLWZg9DAJ
- number: EF472334057
+ number: EF321863413
format: csv
- created_at: '2026-08-07T20:49:16.689Z'
- updated_at: '2026-08-07T20:49:16.689Z'
+ created_at: '2026-08-10T07:56:30.087Z'
+ updated_at: '2026-08-10T07:56:30.087Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -6053,7 +6062,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: F65772843841
+ number: F40269189948
tracking: U10000
tracking_url:
pickup_point_data:
@@ -6080,8 +6089,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-07T20:49:19.158Z'
- updated_at: '2026-08-07T20:49:19.196Z'
+ created_at: '2026-08-10T07:56:33.218Z'
+ updated_at: '2026-08-10T07:56:33.261Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
meta:
@@ -6151,7 +6160,7 @@ paths:
application/json:
example:
id: ful_gbHJdmfrXB
- number: F90909367058
+ number: F66088666195
tracking: INPOST-12345
tracking_url:
pickup_point_data:
@@ -6170,7 +6179,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-07T20:49:19Z'
+ fulfilled_at: '2026-08-10T07:56:33Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -6178,8 +6187,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-07T20:49:19.335Z'
- updated_at: '2026-08-07T20:49:19.354Z'
+ created_at: '2026-08-10T07:56:33.408Z'
+ updated_at: '2026-08-10T07:56:33.436Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
'422':
@@ -6319,7 +6328,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: F21003498771
+ number: F50085939665
tracking: U10000
tracking_url:
pickup_point_data:
@@ -6346,8 +6355,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-07T20:49:19.572Z'
- updated_at: '2026-08-07T20:49:19.602Z'
+ created_at: '2026-08-10T07:56:33.856Z'
+ updated_at: '2026-08-10T07:56:33.892Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
@@ -6409,7 +6418,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: F30608755932
+ number: F12254935165
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
pickup_point_data:
@@ -6436,8 +6445,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-07T20:49:19.669Z'
- updated_at: '2026-08-07T20:49:19.721Z'
+ created_at: '2026-08-10T07:56:33.970Z'
+ updated_at: '2026-08-10T07:56:34.029Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
requestBody:
@@ -6513,7 +6522,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: F59358327738
+ number: F41579250437
tracking: U10000
tracking_url:
pickup_point_data:
@@ -6532,7 +6541,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-07T20:49:19Z'
+ fulfilled_at: '2026-08-10T07:56:34Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -6540,8 +6549,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-07T20:49:19.776Z'
- updated_at: '2026-08-07T20:49:19.839Z'
+ created_at: '2026-08-10T07:56:34.092Z'
+ updated_at: '2026-08-10T07:56:34.155Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
@@ -6603,7 +6612,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: F20773385444
+ number: F36187343880
tracking: U10000
tracking_url:
pickup_point_data:
@@ -6630,8 +6639,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-07T20:49:19.897Z'
- updated_at: '2026-08-07T20:49:19.952Z'
+ created_at: '2026-08-10T07:56:34.219Z'
+ updated_at: '2026-08-10T07:56:34.273Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
@@ -6693,7 +6702,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: F19986067143
+ number: F13105889609
tracking: U10000
tracking_url:
pickup_point_data:
@@ -6720,8 +6729,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-07T20:49:20.021Z'
- updated_at: '2026-08-07T20:49:20.084Z'
+ created_at: '2026-08-10T07:56:34.346Z'
+ updated_at: '2026-08-10T07:56:34.409Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
@@ -6785,7 +6794,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: F41838223758
+ number: F03427996518
tracking:
tracking_url:
pickup_point_data:
@@ -6812,8 +6821,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-07T20:49:20.204Z'
- updated_at: '2026-08-07T20:49:20.239Z'
+ created_at: '2026-08-10T07:56:34.548Z'
+ updated_at: '2026-08-10T07:56:34.579Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
requestBody:
@@ -6912,8 +6921,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-07T20:49:16.761Z'
- updated_at: '2026-08-07T20:49:16.761Z'
+ created_at: '2026-08-10T07:56:30.166Z'
+ updated_at: '2026-08-10T07:56:30.166Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -6997,8 +7006,8 @@ paths:
codes_count: 5
currency: USD
prefix: NEWCAMP
- created_at: '2026-08-07T20:49:16.799Z'
- updated_at: '2026-08-07T20:49:16.799Z'
+ created_at: '2026-08-10T07:56:30.206Z'
+ updated_at: '2026-08-10T07:56:30.206Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: adm_UkLWZg9DAJ
@@ -7102,8 +7111,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-07T20:49:16.829Z'
- updated_at: '2026-08-07T20:49:16.829Z'
+ created_at: '2026-08-10T07:56:30.237Z'
+ updated_at: '2026-08-10T07:56:30.237Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -7209,7 +7218,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 2C9DF903F0FB823D
+ code: D33462A49103EF4A
status: active
currency: USD
amount: '50.0'
@@ -7223,12 +7232,12 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-07T20:49:16.875Z'
- updated_at: '2026-08-07T20:49:16.875Z'
+ created_at: '2026-08-10T07:56:30.303Z'
+ updated_at: '2026-08-10T07:56:30.303Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
- code: 40DC58CE46FD3CDB
+ code: A634014BFDD38867
status: active
currency: USD
amount: '25.0'
@@ -7242,8 +7251,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-07T20:49:16.876Z'
- updated_at: '2026-08-07T20:49:16.876Z'
+ created_at: '2026-08-10T07:56:30.304Z'
+ updated_at: '2026-08-10T07:56:30.304Z'
customer_id:
created_by_id:
meta:
@@ -7331,7 +7340,7 @@ paths:
application/json:
example:
id: gc_EfhxLZ9ck8
- code: EB7B0331188FFEEE
+ code: C661077D8FB00135
status: active
currency: USD
amount: '25.0'
@@ -7345,8 +7354,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-07T20:49:16.923Z'
- updated_at: '2026-08-07T20:49:16.923Z'
+ created_at: '2026-08-10T07:56:30.367Z'
+ updated_at: '2026-08-10T07:56:30.367Z'
customer_id:
created_by_id: adm_UkLWZg9DAJ
schema:
@@ -7455,7 +7464,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 35BCFEE6CD8486D5
+ code: 2597BC6F25EC63BC
status: active
currency: USD
amount: '50.0'
@@ -7469,8 +7478,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-07T20:49:16.950Z'
- updated_at: '2026-08-07T20:49:16.950Z'
+ created_at: '2026-08-10T07:56:30.424Z'
+ updated_at: '2026-08-10T07:56:30.424Z'
customer_id:
created_by_id:
schema:
@@ -7533,7 +7542,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: C965C839F8E9166C
+ code: 87DB73023FDD4972
status: active
currency: USD
amount: '75.0'
@@ -7547,8 +7556,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-07T20:49:16.992Z'
- updated_at: '2026-08-07T20:49:17.018Z'
+ created_at: '2026-08-10T07:56:30.736Z'
+ updated_at: '2026-08-10T07:56:30.762Z'
customer_id:
created_by_id:
schema:
@@ -7651,10 +7660,10 @@ paths:
example:
data:
- id: imp_UkLWZg9DAJ
- number: IM852581680
+ number: IM543919064
rows_count: 0
- created_at: '2026-08-07T20:49:17.090Z'
- updated_at: '2026-08-07T20:49:17.096Z'
+ created_at: '2026-08-10T07:56:30.844Z'
+ updated_at: '2026-08-10T07:56:30.852Z'
type: products
status: pending
owner_type: store
@@ -7663,7 +7672,7 @@ paths:
processing_errors:
preferred_delimiter: ","
original_filename: products_import.csv
- original_byte_size: 3612
+ original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_UkLWZg9DAJ/download"
completed_rows_count: 0
failed_rows_count: 0
@@ -7830,10 +7839,10 @@ paths:
application/json:
example:
id: imp_gbHJdmfrXB
- number: IM005586301
+ number: IM261684030
rows_count: 0
- created_at: '2026-08-07T20:49:17.142Z'
- updated_at: '2026-08-07T20:49:17.178Z'
+ created_at: '2026-08-10T07:56:30.908Z'
+ updated_at: '2026-08-10T07:56:30.949Z'
type: products
status: mapping
owner_type: store
@@ -8268,10 +8277,10 @@ paths:
application/json:
example:
id: imp_UkLWZg9DAJ
- number: IM896009577
+ number: IM210672149
rows_count: 0
- created_at: '2026-08-07T20:49:17.303Z'
- updated_at: '2026-08-07T20:49:17.310Z'
+ created_at: '2026-08-10T07:56:31.077Z'
+ updated_at: '2026-08-10T07:56:31.084Z'
type: products
status: pending
owner_type: store
@@ -8280,7 +8289,7 @@ paths:
processing_errors:
preferred_delimiter: ","
original_filename: products_import.csv
- original_byte_size: 3612
+ original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_UkLWZg9DAJ/download"
completed_rows_count: 0
failed_rows_count: 0
@@ -8505,10 +8514,10 @@ paths:
application/json:
example:
id: imp_gbHJdmfrXB
- number: IM525523963
+ number: IM039651509
rows_count: 0
- created_at: '2026-08-07T20:49:17.401Z'
- updated_at: '2026-08-07T20:49:17.463Z'
+ created_at: '2026-08-10T07:56:31.192Z'
+ updated_at: '2026-08-10T07:56:31.261Z'
type: products
status: completed_mapping
owner_type: store
@@ -8517,7 +8526,7 @@ paths:
processing_errors:
preferred_delimiter: ","
original_filename: products_import.csv
- original_byte_size: 3612
+ original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
completed_rows_count: 0
failed_rows_count: 0
@@ -8841,10 +8850,10 @@ paths:
application/json:
example:
id: imp_gbHJdmfrXB
- number: IM136198422
+ number: IM466720395
rows_count: 1
- created_at: '2026-08-07T20:49:17.493Z'
- updated_at: '2026-08-07T20:49:17.540Z'
+ created_at: '2026-08-10T07:56:31.304Z'
+ updated_at: '2026-08-10T07:56:31.331Z'
type: products
status: processing
owner_type: store
@@ -8853,7 +8862,7 @@ paths:
processing_errors:
preferred_delimiter: ","
original_filename: products_import.csv
- original_byte_size: 3612
+ original_byte_size: 3627
original_file_url: "/api/v3/admin/imports/imp_gbHJdmfrXB/download"
completed_rows_count: 0
failed_rows_count: 1
@@ -9017,8 +9026,8 @@ paths:
row_number: 2
status: failed
validation_errors: boom
- created_at: '2026-08-07T20:49:17.572Z'
- updated_at: '2026-08-07T20:49:17.572Z'
+ created_at: '2026-08-10T07:56:31.355Z'
+ updated_at: '2026-08-10T07:56:31.355Z'
import_id: imp_UkLWZg9DAJ
item_type:
item_id:
@@ -9120,8 +9129,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
- id: mkt_gbHJdmfrXB
name: EU
currency: USD
@@ -9132,8 +9141,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-08-07T20:49:17.725Z'
- updated_at: '2026-08-07T20:49:17.725Z'
+ created_at: '2026-08-10T07:56:31.542Z'
+ updated_at: '2026-08-10T07:56:31.542Z'
meta:
page: 1
limit: 25
@@ -9226,8 +9235,8 @@ paths:
supported_locales:
- en
- fr
- created_at: '2026-08-07T20:49:17.776Z'
- updated_at: '2026-08-07T20:49:17.776Z'
+ created_at: '2026-08-10T07:56:31.706Z'
+ updated_at: '2026-08-10T07:56:31.706Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -9363,8 +9372,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-08-07T20:49:17.830Z'
- updated_at: '2026-08-07T20:49:17.830Z'
+ created_at: '2026-08-10T07:56:31.771Z'
+ updated_at: '2026-08-10T07:56:31.771Z'
schema:
"$ref": "#/components/schemas/Market"
'404':
@@ -9443,8 +9452,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-08-07T20:49:17.936Z'
- updated_at: '2026-08-07T20:49:17.967Z'
+ created_at: '2026-08-10T07:56:31.845Z'
+ updated_at: '2026-08-10T07:56:31.865Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -9624,8 +9633,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-07T20:49:18.192Z'
- updated_at: '2026-08-07T20:49:18.192Z'
+ created_at: '2026-08-10T07:56:32.098Z'
+ updated_at: '2026-08-10T07:56:32.098Z'
meta:
page: 1
limit: 25
@@ -9719,8 +9728,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-07T20:49:18.248Z'
- updated_at: '2026-08-07T20:49:18.248Z'
+ created_at: '2026-08-10T07:56:32.159Z'
+ updated_at: '2026-08-10T07:56:32.159Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -9844,8 +9853,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-07T20:49:18.274Z'
- updated_at: '2026-08-07T20:49:18.274Z'
+ created_at: '2026-08-10T07:56:32.193Z'
+ updated_at: '2026-08-10T07:56:32.193Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
@@ -9918,8 +9927,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-07T20:49:18.312Z'
- updated_at: '2026-08-07T20:49:18.328Z'
+ created_at: '2026-08-10T07:56:32.245Z'
+ updated_at: '2026-08-10T07:56:32.269Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -10079,8 +10088,8 @@ paths:
display_amount: "$1.50"
provider_id: internal
metadata: {}
- created_at: '2026-08-07T20:49:18.498Z'
- updated_at: '2026-08-07T20:49:18.498Z'
+ created_at: '2026-08-10T07:56:32.467Z'
+ updated_at: '2026-08-10T07:56:32.467Z'
meta:
page: 1
limit: 25
@@ -10154,8 +10163,8 @@ paths:
amount: "-2.0"
display_amount: "-$2.00"
metadata: {}
- created_at: '2026-08-07T20:49:18.586Z'
- updated_at: '2026-08-07T20:49:18.586Z'
+ created_at: '2026-08-10T07:56:32.584Z'
+ updated_at: '2026-08-10T07:56:32.584Z'
meta:
page: 1
limit: 25
@@ -10235,8 +10244,8 @@ paths:
amount: "-3.0"
display_amount: "-$3.00"
metadata: {}
- created_at: '2026-08-07T20:49:18.699Z'
- updated_at: '2026-08-07T20:49:18.699Z'
+ created_at: '2026-08-10T07:56:32.705Z'
+ updated_at: '2026-08-10T07:56:32.705Z'
'422':
description: invalid discount
content:
@@ -10333,8 +10342,8 @@ paths:
amount: '4.0'
display_amount: "$4.00"
metadata: {}
- created_at: '2026-08-07T20:49:18.880Z'
- updated_at: '2026-08-07T20:49:18.880Z'
+ created_at: '2026-08-10T07:56:32.906Z'
+ updated_at: '2026-08-10T07:56:32.906Z'
'422':
description: invalid fee
content:
@@ -10431,7 +10440,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: FBAF6CFDCDBD540F
+ code: 29C0C816318B53EF
status: active
currency: USD
amount: '10.0'
@@ -10445,8 +10454,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-07T20:49:20.312Z'
- updated_at: '2026-08-07T20:49:20.343Z'
+ created_at: '2026-08-10T07:56:34.658Z'
+ updated_at: '2026-08-10T07:56:34.692Z'
customer_id:
created_by_id:
requestBody:
@@ -10587,8 +10596,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 276778
- slug: product-276778
+ name: Product 275258
+ slug: product-275258
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -10620,12 +10629,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:20.492Z'
- updated_at: '2026-08-07T20:49:20.492Z'
+ created_at: '2026-08-10T07:56:34.869Z'
+ updated_at: '2026-08-10T07:56:34.869Z'
digital_links: []
metadata: {}
- created_at: '2026-08-07T20:49:20.513Z'
- updated_at: '2026-08-07T20:49:20.513Z'
+ created_at: '2026-08-10T07:56:34.895Z'
+ updated_at: '2026-08-10T07:56:34.895Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -10697,8 +10706,8 @@ paths:
preorder_ships_at:
quantity: 3
currency: USD
- name: Product 299400
- slug: product-299400
+ name: Product 29830
+ slug: product-29830
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -10730,12 +10739,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:20.628Z'
- updated_at: '2026-08-07T20:49:20.628Z'
+ created_at: '2026-08-10T07:56:35.035Z'
+ updated_at: '2026-08-10T07:56:35.035Z'
digital_links: []
metadata: {}
- created_at: '2026-08-07T20:49:20.649Z'
- updated_at: '2026-08-07T20:49:20.649Z'
+ created_at: '2026-08-10T07:56:35.060Z'
+ updated_at: '2026-08-10T07:56:35.060Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -10829,8 +10838,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 307878
- slug: product-307878
+ name: Product 303747
+ slug: product-303747
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -10862,12 +10871,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:20.718Z'
- updated_at: '2026-08-07T20:49:20.718Z'
+ created_at: '2026-08-10T07:56:35.151Z'
+ updated_at: '2026-08-10T07:56:35.151Z'
digital_links: []
metadata: {}
- created_at: '2026-08-07T20:49:20.738Z'
- updated_at: '2026-08-07T20:49:20.738Z'
+ created_at: '2026-08-10T07:56:35.177Z'
+ updated_at: '2026-08-10T07:56:35.177Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -10934,8 +10943,8 @@ paths:
preorder_ships_at:
quantity: 5
currency: USD
- name: Product 316614
- slug: product-316614
+ name: Product 315049
+ slug: product-315049
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -10967,12 +10976,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:20.796Z'
- updated_at: '2026-08-07T20:49:20.796Z'
+ created_at: '2026-08-10T07:56:35.244Z'
+ updated_at: '2026-08-10T07:56:35.244Z'
digital_links: []
metadata: {}
- created_at: '2026-08-07T20:49:20.828Z'
- updated_at: '2026-08-07T20:49:20.869Z'
+ created_at: '2026-08-10T07:56:35.265Z'
+ updated_at: '2026-08-10T07:56:35.299Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -11093,8 +11102,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R362870429
+ number: R484055636
customer_note:
currency: USD
locale: en
@@ -11138,8 +11147,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: draft
last_ip_address:
considered_risky: false
@@ -11150,11 +11159,12 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-07T20:49:22.001Z'
- updated_at: '2026-08-07T20:49:22.046Z'
+ created_at: '2026-08-10T07:56:36.590Z'
+ updated_at: '2026-08-10T07:56:36.638Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id:
created_by_id:
@@ -11329,8 +11339,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R976344360
+ number: R353709687
customer_note:
currency: USD
locale: en
@@ -11374,8 +11384,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: draft
last_ip_address:
considered_risky: false
@@ -11386,11 +11396,12 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-07T20:49:22.198Z'
- updated_at: '2026-08-07T20:49:22.198Z'
+ created_at: '2026-08-10T07:56:36.809Z'
+ updated_at: '2026-08-10T07:56:36.809Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id:
created_by_id:
@@ -11438,12 +11449,12 @@ paths:
// except `email` is optional.
const order = await client.orders.create({
- customer_id: 'cus_UkLWZg9DAJ', // Existing customer; omit for guest orders
- use_customer_default_address: false, // true to copy the customer's saved addresses
+ 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
+ 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
@@ -11453,7 +11464,9 @@ paths:
preferred_stock_location_id: 'sloc_UkLWZg9DAJ',
customer_note: 'Please leave at the front desk.',
- internal_note: 'VIP customer — handle with care.',
+ // Rich text: send HTML. Reads return this as plain text, plus
+ // `internal_note_html` with the markup.
+ internal_note: '<p>VIP customer — handle with care.</p>',
metadata: {
external_reference: 'subscription_invoice_2026_04',
source: 'recurring-engine',
@@ -11498,7 +11511,8 @@ paths:
- 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
+ leave at the front desk.","internal_note":"<p>VIP customer — handle with
+ care.</p>","metadata":{"external_reference":"subscription_invoice_2026_04","source":"recurring-engine"},"items":[{"variant_id":"variant_k5nR8xLq","quantity":2},{"variant_id":"variant_QXyZ12abCD","quantity":1,"metadata":{"gift":true}}],"shipping_address":{"first_name":"Jane","last_name":"Doe","address1":"350
Fifth Avenue","address2":"Floor 42","city":"New York","postal_code":"10118","country_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
@@ -11539,7 +11553,7 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R004934905
+ number: R734273258
customer_note:
currency: USD
@@ -11584,8 +11598,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: draft
last_ip_address:
considered_risky: false
@@ -11596,11 +11610,12 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-07T20:49:22.320Z'
- updated_at: '2026-08-07T20:49:22.323Z'
+ created_at: '2026-08-10T07:56:36.931Z'
+ updated_at: '2026-08-10T07:56:36.934Z'
preferred_stock_location_id: sloc_UkLWZg9DAJ
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id:
created_by_id:
@@ -11785,8 +11800,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R622308532
+ number: R784723985
customer_note:
currency: USD
locale: en
@@ -11830,8 +11845,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: draft
last_ip_address:
considered_risky: false
@@ -11842,11 +11857,12 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-07T20:49:22.340Z'
- updated_at: '2026-08-07T20:49:22.340Z'
+ created_at: '2026-08-10T07:56:36.950Z'
+ updated_at: '2026-08-10T07:56:36.950Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id:
created_by_id:
@@ -11885,12 +11901,12 @@ paths:
const order = await client.orders.update('or_UkLWZg9DAJ', {
- internal_note: 'VIP — gift wrap on next order',
+ internal_note: '<p>VIP — gift wrap on next order</p>',
})
- lang: bash
label: Spree CLI
- source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"VIP
- — gift wrap on next order"}'
+ source: spree api patch /orders/{id} -d '{"email":"[email protected]","internal_note":"<p>VIP
+ — gift wrap on next order</p>"}'
parameters:
- name: x-spree-api-key
in: header
@@ -11919,7 +11935,7 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R346786184
+ number: R702019483
customer_note:
currency: USD
@@ -11964,8 +11980,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: draft
last_ip_address:
considered_risky: false
@@ -11976,11 +11992,12 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-07T20:49:22.412Z'
- updated_at: '2026-08-07T20:49:22.436Z'
+ created_at: '2026-08-10T07:56:37.012Z'
+ updated_at: '2026-08-10T07:56:37.035Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id:
created_by_id:
@@ -12165,8 +12182,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R078021574
+ number: R389821628
customer_note:
currency: USD
locale: en
@@ -12174,7 +12191,7 @@ paths:
coupon_code:
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-08-07T20:49:22.548Z'
+ completed_at: '2026-08-10T07:56:37.148Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12210,8 +12227,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: placed
last_ip_address:
considered_risky: false
@@ -12222,11 +12239,12 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-07T20:49:22.501Z'
- updated_at: '2026-08-07T20:49:22.565Z'
+ created_at: '2026-08-10T07:56:37.102Z'
+ updated_at: '2026-08-10T07:56:37.163Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id:
created_by_id:
@@ -12308,8 +12326,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R152801422
+ number: R668620031
customer_note:
currency: USD
locale: en
@@ -12317,7 +12335,7 @@ paths:
coupon_code:
fulfillment_status: canceled
payment_status: none
- completed_at: '2026-08-07T20:49:22.761Z'
+ completed_at: '2026-08-10T07:56:37.358Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12353,8 +12371,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: canceled
last_ip_address:
considered_risky: false
@@ -12363,13 +12381,14 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-07T20:49:22.816Z'
+ canceled_at: '2026-08-10T07:56:37.387Z'
approved_at:
- created_at: '2026-08-07T20:49:22.691Z'
- updated_at: '2026-08-07T20:49:22.854Z'
+ created_at: '2026-08-10T07:56:37.303Z'
+ updated_at: '2026-08-10T07:56:37.405Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id: adm_UkLWZg9DAJ
created_by_id:
@@ -12429,8 +12448,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R202048662
+ number: R871465614
customer_note:
currency: USD
locale: en
@@ -12438,7 +12457,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-07T20:49:22.965Z'
+ completed_at: '2026-08-10T07:56:37.489Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12474,8 +12493,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: placed
last_ip_address:
considered_risky: false
@@ -12485,12 +12504,13 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-08-07T20:49:22.988Z'
- created_at: '2026-08-07T20:49:22.918Z'
- updated_at: '2026-08-07T20:49:22.965Z'
+ approved_at: '2026-08-10T07:56:37.515Z'
+ created_at: '2026-08-10T07:56:37.445Z'
+ updated_at: '2026-08-10T07:56:37.489Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id: adm_UkLWZg9DAJ
canceler_id:
created_by_id:
@@ -12550,8 +12570,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R543373514
+ number: R871204067
customer_note:
currency: USD
locale: en
@@ -12559,7 +12579,7 @@ paths:
coupon_code:
fulfillment_status: pending
payment_status: none
- completed_at: '2026-08-07T20:49:23.061Z'
+ completed_at: '2026-08-10T07:56:37.585Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12595,8 +12615,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: placed
last_ip_address:
considered_risky: false
@@ -12605,13 +12625,14 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-07T20:49:23.077Z'
+ canceled_at: '2026-08-10T07:56:37.600Z'
approved_at:
- created_at: '2026-08-07T20:49:23.013Z'
- updated_at: '2026-08-07T20:49:23.117Z'
+ created_at: '2026-08-10T07:56:37.541Z'
+ updated_at: '2026-08-10T07:56:37.646Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id: adm_UkLWZg9DAJ
created_by_id:
@@ -12671,8 +12692,8 @@ paths:
market_id: mkt_UkLWZg9DAJ
cart_id:
channel_id: ch_UkLWZg9DAJ
- number: R242916284
+ number: R879114101
customer_note:
currency: USD
locale: en
@@ -12680,7 +12701,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-07T20:49:23.190Z'
+ completed_at: '2026-08-10T07:56:37.736Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -12716,8 +12737,8 @@ paths:
- US
supported_locales:
- en
- created_at: '2026-08-07T20:49:13.286Z'
- updated_at: '2026-08-07T20:49:13.286Z'
+ created_at: '2026-08-10T07:56:25.958Z'
+ updated_at: '2026-08-10T07:56:25.958Z'
status: placed
last_ip_address:
considered_risky: false
@@ -12728,11 +12749,12 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-07T20:49:23.138Z'
- updated_at: '2026-08-07T20:49:23.190Z'
+ created_at: '2026-08-10T07:56:37.668Z'
+ updated_at: '2026-08-10T07:56:37.736Z'
preferred_stock_location_id:
tags: []
internal_note:
+ internal_note_html:
approver_id:
canceler_id:
created_by_id:
@@ -12807,8 +12829,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-08-07T20:49:23.295Z'
- updated_at: '2026-08-07T20:49:23.295Z'
+ created_at: '2026-08-10T07:56:37.839Z'
+ updated_at: '2026-08-10T07:56:37.839Z'
preferences: {}
preference_schema: []
meta:
@@ -12954,8 +12976,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-08-07T20:49:23.343Z'
- updated_at: '2026-08-07T20:49:23.343Z'
+ created_at: '2026-08-10T07:56:37.899Z'
+ updated_at: '2026-08-10T07:56:37.899Z'
preferences: {}
preference_schema: []
"/api/v3/admin/orders/{order_id}/payments":
@@ -13026,8 +13048,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-df069ea9d904
- number: PM4UZOOJ
+ response_code: BGS-eadb2f6843a4
+ number: P6RE9OWY
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -13045,14 +13067,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-07T20:49:21.056Z'
- updated_at: '2026-08-07T20:49:21.059Z'
+ created_at: '2026-08-10T07:56:35.494Z'
+ updated_at: '2026-08-10T07:56:35.497Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-07T20:49:21.058Z'
- updated_at: '2026-08-07T20:49:21.058Z'
+ created_at: '2026-08-10T07:56:35.496Z'
+ updated_at: '2026-08-10T07:56:35.496Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -13122,7 +13144,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: PUEXL4JP
+ number: P1I3FS70
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -13133,8 +13155,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-07T20:49:21.255Z'
- updated_at: '2026-08-07T20:49:21.255Z'
+ created_at: '2026-08-10T07:56:35.737Z'
+ updated_at: '2026-08-10T07:56:35.737Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -13227,8 +13249,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-419e930324ec
- number: PZBJFOIY
+ response_code: BGS-f2edbca76b4f
+ number: PYS0U17J
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -13246,14 +13268,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-07T20:49:21.333Z'
- updated_at: '2026-08-07T20:49:21.336Z'
+ created_at: '2026-08-10T07:56:35.839Z'
+ updated_at: '2026-08-10T07:56:35.842Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-07T20:49:21.335Z'
- updated_at: '2026-08-07T20:49:21.335Z'
+ created_at: '2026-08-10T07:56:35.841Z'
+ updated_at: '2026-08-10T07:56:35.841Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -13316,8 +13338,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-f315e522122f
- number: P09H0OCQ
+ response_code: BGS-c7c19a434413
+ number: P3P2NP7A
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -13335,14 +13357,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-07T20:49:21.444Z'
- updated_at: '2026-08-07T20:49:21.446Z'
+ created_at: '2026-08-10T07:56:35.955Z'
+ updated_at: '2026-08-10T07:56:35.957Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-07T20:49:21.445Z'
- updated_at: '2026-08-07T20:49:21.476Z'
+ created_at: '2026-08-10T07:56:35.956Z'
+ updated_at: '2026-08-10T07:56:35.993Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -13414,8 +13436,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-4f6420f2151d
- number: P6LWV5FI
+ response_code: void-BGS-418585900275
+ number: PPD23UJW
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -13433,14 +13455,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-07T20:49:21.722Z'
- updated_at: '2026-08-07T20:49:21.726Z'
+ created_at: '2026-08-10T07:56:36.217Z'
+ updated_at: '2026-08-10T07:56:36.220Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-07T20:49:21.725Z'
- updated_at: '2026-08-07T20:49:21.754Z'
+ created_at: '2026-08-10T07:56:36.219Z'
+ updated_at: '2026-08-10T07:56:36.243Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
@@ -13528,8 +13550,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-07T20:49:23.388Z'
- updated_at: '2026-08-07T20:49:23.388Z'
+ created_at: '2026-08-10T07:56:37.942Z'
+ updated_at: '2026-08-10T07:56:37.942Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -13543,8 +13565,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-07T20:49:23.390Z'
- updated_at: '2026-08-07T20:49:23.390Z'
+ created_at: '2026-08-10T07:56:37.943Z'
+ updated_at: '2026-08-10T07:56:37.943Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -13658,8 +13680,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-07T20:49:23.563Z'
- updated_at: '2026-08-07T20:49:23.565Z'
+ created_at: '2026-08-10T07:56:38.167Z'
+ updated_at: '2026-08-10T07:56:38.170Z'
currently_active: false
products_count: 1
prices_count: 2
@@ -13822,8 +13844,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-07T20:49:23.599Z'
- updated_at: '2026-08-07T20:49:23.599Z'
+ created_at: '2026-08-10T07:56:38.213Z'
+ updated_at: '2026-08-10T07:56:38.213Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -13898,8 +13920,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-07T20:49:23.844Z'
- updated_at: '2026-08-07T20:49:23.862Z'
+ created_at: '2026-08-10T07:56:38.485Z'
+ updated_at: '2026-08-10T07:56:38.503Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -14087,8 +14109,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-07T20:49:23.895Z'
- updated_at: '2026-08-07T20:49:23.912Z'
+ created_at: '2026-08-10T07:56:38.541Z'
+ updated_at: '2026-08-10T07:56:38.559Z'
currently_active: true
products_count: 0
prices_count: 0
@@ -14151,8 +14173,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-07T20:49:23.921Z'
- updated_at: '2026-08-07T20:49:23.939Z'
+ created_at: '2026-08-10T07:56:38.568Z'
+ updated_at: '2026-08-10T07:56:38.586Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -14266,8 +14288,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:23.973Z'
- updated_at: '2026-08-07T20:49:23.973Z'
+ created_at: '2026-08-10T07:56:38.617Z'
+ updated_at: '2026-08-10T07:56:38.617Z'
- id: price_gbHJdmfrXB
amount: '19.99'
amount_in_cents: 1999
@@ -14278,8 +14300,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-07T20:49:23.994Z'
- updated_at: '2026-08-07T20:49:23.994Z'
+ created_at: '2026-08-10T07:56:38.637Z'
+ updated_at: '2026-08-10T07:56:38.637Z'
- id: price_EfhxLZ9ck8
amount: '5.0'
amount_in_cents: 500
@@ -14290,8 +14312,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-07T20:49:23.998Z'
- updated_at: '2026-08-07T20:49:23.998Z'
+ created_at: '2026-08-10T07:56:38.643Z'
+ updated_at: '2026-08-10T07:56:38.643Z'
meta:
page: 1
limit: 25
@@ -14373,8 +14395,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_EfhxLZ9ck8
- created_at: '2026-08-07T20:49:24.122Z'
- updated_at: '2026-08-07T20:49:24.122Z'
+ created_at: '2026-08-10T07:56:38.784Z'
+ updated_at: '2026-08-10T07:56:38.784Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -14461,8 +14483,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-07T20:49:24.179Z'
- updated_at: '2026-08-07T20:49:24.179Z'
+ created_at: '2026-08-10T07:56:38.845Z'
+ updated_at: '2026-08-10T07:56:38.845Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
@@ -14527,8 +14549,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-07T20:49:24.311Z'
- updated_at: '2026-08-07T20:49:24.326Z'
+ created_at: '2026-08-10T07:56:38.989Z'
+ updated_at: '2026-08-10T07:56:39.006Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -14836,12 +14858,12 @@ paths:
data:
- id: cf_UkLWZg9DAJ
label: Title
- type: Spree::Metafields::ShortText
+ type: Spree::CustomFields::ShortText
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-07T20:49:24.912Z'
- updated_at: '2026-08-07T20:49:24.912Z'
+ created_at: '2026-08-10T07:56:39.596Z'
+ updated_at: '2026-08-10T07:56:39.596Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -14907,12 +14929,12 @@ paths:
example:
id: cf_gbHJdmfrXB
label: Description
- type: Spree::Metafields::LongText
+ type: Spree::CustomFields::LongText
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-08-07T20:49:25.052Z'
- updated_at: '2026-08-07T20:49:25.052Z'
+ created_at: '2026-08-10T07:56:39.663Z'
+ updated_at: '2026-08-10T07:56:39.663Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -14922,9 +14944,9 @@ paths:
example:
error:
code: validation_error
- message: Metafield definition has already been taken
+ message: Custom field definition has already been taken
details:
- metafield_definition_id:
+ custom_field_definition_id:
- has already been taken
requestBody:
content:
@@ -15007,12 +15029,12 @@ paths:
example:
id: cf_UkLWZg9DAJ
label: Title
- type: Spree::Metafields::ShortText
+ type: Spree::CustomFields::ShortText
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-07T20:49:25.139Z'
- updated_at: '2026-08-07T20:49:25.139Z'
+ created_at: '2026-08-10T07:56:39.745Z'
+ updated_at: '2026-08-10T07:56:39.745Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -15072,12 +15094,12 @@ paths:
example:
id: cf_UkLWZg9DAJ
label: Title
- type: Spree::Metafields::ShortText
+ type: Spree::CustomFields::ShortText
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-08-07T20:49:25.185Z'
- updated_at: '2026-08-07T20:49:25.202Z'
+ created_at: '2026-08-10T07:56:39.798Z'
+ updated_at: '2026-08-10T07:56:39.814Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -15195,10 +15217,9 @@ paths:
source: Espresso Machine
- key: description
type: html
- source: Nam voluptas ullam nobis alias exercitationem facere.
- Eligendi reiciendis eveniet velit ut aliquam tenetur. Accusamus
- dolor illo saepe ex. Laboriosam consequuntur recusandae eveniet
- laborum in. Rerum voluptatum consequuntur cumque fugiat.
+ source: |-
+ Magni accusantium optio facilis itaque quam possimus. Tenetur aperiam atque dolorum natus quam maxime. Debitis optio assumenda error ab nobis necessitatibus modi reprehenderit.
+ Aspernatur fuga quaerat facere beatae excepturi minus vel. Esse accusantium est beatae nam ullam qui cupiditate. Autem neque molestias rerum eligendi velit odio pariatur.
- key: slug
type: string
source: espresso-machine
@@ -15309,8 +15330,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 721911
- slug: product-721911
+ name: Product 729567
+ slug: product-729567
meta_title:
meta_description:
meta_keywords:
@@ -15322,14 +15343,16 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Impedit expedita tempore asperiores distinctio. Voluptatibus
- tenetur illo libero optio earum eos. Iste magnam magni ab mollitia
- deleniti. Error molestias illum repellendus tenetur ut ipsam beatae
- natus.
- description_html: Impedit expedita tempore asperiores distinctio.
- Voluptatibus tenetur illo libero optio earum eos. Iste magnam
- magni ab mollitia deleniti. Error molestias illum repellendus
- tenetur ut ipsam beatae natus.
+ description: Atque quos magni culpa dolore labore temporibus ipsam.
+ Odio ab officiis assumenda nemo illo. Veniam exercitationem impedit
+ architecto illum possimus minus. Consectetur laborum fuga et quibusdam
+ sit dolorem facere omnis. Nisi similique ducimus distinctio ullam
+ inventore quod pariatur esse. Unde dolor enim quis iste incidunt
+ sit. Ratione in placeat quibusdam sunt ipsa quam maiores inventore.
+ Sint possimus pariatur et ad illo.
+ description_html: |-
+ Atque quos magni culpa dolore labore temporibus ipsam. Odio ab officiis assumenda nemo illo. Veniam exercitationem impedit architecto illum possimus minus. Consectetur laborum fuga et quibusdam sit dolorem facere omnis.
+ Nisi similique ducimus distinctio ullam inventore quod pariatur esse. Unde dolor enim quis iste incidunt sit. Ratione in placeat quibusdam sunt ipsa quam maiores inventore. Sint possimus pariatur et ad illo.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -15344,14 +15367,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:25.329Z'
- updated_at: '2026-08-07T20:49:25.329Z'
+ created_at: '2026-08-10T07:56:39.964Z'
+ updated_at: '2026-08-10T07:56:39.964Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-07T20:49:25.320Z'
- updated_at: '2026-08-07T20:49:25.334Z'
+ created_at: '2026-08-10T07:56:39.946Z'
+ updated_at: '2026-08-10T07:56:39.970Z'
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -15414,7 +15437,9 @@ paths:
const product = await client.products.create({
name: 'Premium T-Shirt',
- description: 'Soft, organic cotton.',
+ // Rich text: send HTML. Reads return this as plain text, plus
+ // `description_html` with the markup.
+ description: '<p>Soft, organic cotton.</p>',
status: 'active',
variants: [
{
@@ -15442,8 +15467,8 @@ paths:
})
- 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}]}]}'
+ source: spree api post /products -d '{"name":"Premium T-Shirt","description":"<p>Soft,
+ organic cotton.</p>","status":"active","variants":[{"sku":"TSHIRT-S-NAVY","options":[{"name":"size","value":"Small"},{"name":"color","value":"navy"}],"prices":[{"currency":"USD","amount":"29.99"},{"currency":"EUR","amount":"27.99"}],"stock_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
@@ -15486,8 +15511,8 @@ paths:
status: draft
metadata: {}
deleted_at:
- created_at: '2026-08-07T20:49:25.463Z'
- updated_at: '2026-08-07T20:49:25.467Z'
+ created_at: '2026-08-10T07:56:40.101Z'
+ updated_at: '2026-08-10T07:56:40.106Z'
product_type_id:
tax_category_id:
schema:
@@ -15693,8 +15718,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 766188
- slug: product-766188
+ name: Product 768250
+ slug: product-768250
meta_title:
meta_description:
meta_keywords:
@@ -15706,30 +15731,26 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Dignissimos natus eum quis cum deserunt dolor corporis.
- Possimus voluptate voluptatum cum eum fugit dignissimos itaque aperiam.
- Repellat pariatur ipsam odit fugit delectus. Sunt cupiditate excepturi
- laborum quas quos illo rerum. Voluptates numquam magni itaque commodi
- blanditiis fugiat omnis. Odio voluptatibus placeat officia asperiores
- at. Alias facere eum blanditiis non distinctio rem deleniti nesciunt.
- Quo eveniet voluptate a officiis fugit mollitia corporis excepturi.
- Perspiciatis officia eveniet ab sed voluptate laudantium facilis.
- Deserunt odit sint debitis facilis officia voluptatibus dolorum
- amet. Ipsa nisi veritatis facere doloribus animi. Possimus amet
- mollitia soluta dolores nihil earum iure. Autem maxime ex sed modi
- id sunt. Esse nostrum maxime quos atque. Natus nemo pariatur aut
- alias nesciunt. Minima sequi vitae modi consectetur amet ipsam asperiores
- adipisci. Dignissimos odio excepturi reiciendis error dicta exercitationem
- laboriosam aperiam. Quaerat aut dolorem iste molestiae pariatur.
- Ut minima accusantium ea quam. Voluptatibus perferendis sapiente
- consequuntur sed libero facilis doloribus. Unde odit in quas voluptatem
- fuga ratione.
+ description: Itaque sequi quo blanditiis sint. Repellendus quam placeat
+ at velit pariatur quas qui. Dolore quas esse totam dicta a nulla
+ ratione. Corporis aliquam nemo optio reprehenderit excepturi inventore
+ fugiat. Distinctio optio officia impedit nulla. Vel ullam deleniti
+ numquam quasi adipisci natus praesentium. Quam consequatur in assumenda
+ beatae voluptatem. Qui tempore ducimus reprehenderit occaecati fugit
+ earum dolores excepturi. Incidunt at illo aliquam vitae adipisci
+ dolorem sapiente odit. Error debitis consequuntur necessitatibus
+ similique fugiat. Placeat voluptates quia vel quam. Placeat impedit
+ fugit eveniet deleniti earum facilis. Deleniti aperiam ipsam voluptatum
+ explicabo eius provident odio similique. Ab unde distinctio eum
+ esse. Magni sint numquam perferendis accusantium consectetur at.
+ Dolor repellat quidem dolorum quaerat quae illo qui. Necessitatibus
+ commodi totam possimus rem aperiam. Dolor earum eligendi quod accusamus
+ possimus commodi ipsum in. Unde sapiente non ullam voluptatum.
description_html: |-
- Dignissimos natus eum quis cum deserunt dolor corporis. Possimus voluptate voluptatum cum eum fugit dignissimos itaque aperiam. Repellat pariatur ipsam odit fugit delectus.
- Sunt cupiditate excepturi laborum quas quos illo rerum. Voluptates numquam magni itaque commodi blanditiis fugiat omnis. Odio voluptatibus placeat officia asperiores at. Alias facere eum blanditiis non distinctio rem deleniti nesciunt. Quo eveniet voluptate a officiis fugit mollitia corporis excepturi.
- Perspiciatis officia eveniet ab sed voluptate laudantium facilis. Deserunt odit sint debitis facilis officia voluptatibus dolorum amet. Ipsa nisi veritatis facere doloribus animi.
- Possimus amet mollitia soluta dolores nihil earum iure. Autem maxime ex sed modi id sunt. Esse nostrum maxime quos atque. Natus nemo pariatur aut alias nesciunt. Minima sequi vitae modi consectetur amet ipsam asperiores adipisci.
- Dignissimos odio excepturi reiciendis error dicta exercitationem laboriosam aperiam. Quaerat aut dolorem iste molestiae pariatur. Ut minima accusantium ea quam. Voluptatibus perferendis sapiente consequuntur sed libero facilis doloribus. Unde odit in quas voluptatem fuga ratione.
+ Itaque sequi quo blanditiis sint. Repellendus quam placeat at velit pariatur quas qui. Dolore quas esse totam dicta a nulla ratione. Corporis aliquam nemo optio reprehenderit excepturi inventore fugiat.
+ Distinctio optio officia impedit nulla. Vel ullam deleniti numquam quasi adipisci natus praesentium. Quam consequatur in assumenda beatae voluptatem. Qui tempore ducimus reprehenderit occaecati fugit earum dolores excepturi. Incidunt at illo aliquam vitae adipisci dolorem sapiente odit.
+ Error debitis consequuntur necessitatibus similique fugiat. Placeat voluptates quia vel quam. Placeat impedit fugit eveniet deleniti earum facilis. Deleniti aperiam ipsam voluptatum explicabo eius provident odio similique. Ab unde distinctio eum esse.
+ Magni sint numquam perferendis accusantium consectetur at. Dolor repellat quidem dolorum quaerat quae illo qui. Necessitatibus commodi totam possimus rem aperiam. Dolor earum eligendi quod accusamus possimus commodi ipsum in. Unde sapiente non ullam voluptatum.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -15744,14 +15765,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:25.583Z'
- updated_at: '2026-08-07T20:49:25.583Z'
+ created_at: '2026-08-10T07:56:40.233Z'
+ updated_at: '2026-08-10T07:56:40.233Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-07T20:49:25.573Z'
- updated_at: '2026-08-07T20:49:25.588Z'
+ created_at: '2026-08-10T07:56:40.219Z'
+ updated_at: '2026-08-10T07:56:40.240Z'
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
@@ -15822,7 +15843,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-785877
+ slug: product-788356
meta_title:
meta_description:
meta_keywords:
@@ -15834,12 +15855,21 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Unde adipisci magni ipsam perferendis. Neque voluptatibus
- ex repellendus quia consequuntur natus eveniet. Sapiente qui perspiciatis
- adipisci cum minima quaerat repudiandae.
- description_html: Unde adipisci magni ipsam perferendis. Neque voluptatibus
- ex repellendus quia consequuntur natus eveniet. Sapiente qui perspiciatis
- adipisci cum minima quaerat repudiandae.
+ description: Quo blanditiis accusantium et commodi cum molestias ea
+ nihil. Architecto sapiente asperiores laboriosam ratione. Cumque
+ doloribus fugit quia totam tempora natus nisi. Quidem reprehenderit
+ maxime quasi magni nesciunt porro fugit maiores. In illo quia itaque
+ corrupti quod placeat dolore. Magni ipsum necessitatibus autem neque
+ facilis ut doloribus. Cum nesciunt fugit maiores at animi suscipit
+ quos tempora. Est commodi odit delectus saepe officiis. Corrupti
+ iure rem eum nostrum qui cupiditate. Mollitia dolores illo laborum
+ quibusdam libero excepturi. In nobis cumque quos asperiores. Repudiandae
+ reprehenderit repellendus ad quos pariatur. Eos ad ipsa architecto
+ doloribus consequuntur enim tempore quae.
+ description_html: |-
+ Quo blanditiis accusantium et commodi cum molestias ea nihil. Architecto sapiente asperiores laboriosam ratione. Cumque doloribus fugit quia totam tempora natus nisi. Quidem reprehenderit maxime quasi magni nesciunt porro fugit maiores. In illo quia itaque corrupti quod placeat dolore.
+ Magni ipsum necessitatibus autem neque facilis ut doloribus. Cum nesciunt fugit maiores at animi suscipit quos tempora. Est commodi odit delectus saepe officiis. Corrupti iure rem eum nostrum qui cupiditate. Mollitia dolores illo laborum quibusdam libero excepturi.
+ In nobis cumque quos asperiores. Repudiandae reprehenderit repellendus ad quos pariatur. Eos ad ipsa architecto doloribus consequuntur enim tempore quae.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -15854,14 +15884,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:25.691Z'
- updated_at: '2026-08-07T20:49:25.691Z'
+ created_at: '2026-08-10T07:56:40.372Z'
+ updated_at: '2026-08-10T07:56:40.372Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-07T20:49:25.682Z'
- updated_at: '2026-08-07T20:49:25.717Z'
+ created_at: '2026-08-10T07:56:40.363Z'
+ updated_at: '2026-08-10T07:56:40.396Z'
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
@@ -16143,7 +16173,7 @@ paths:
- api_key: []
bearer_auth: []
description: |-
- Attaches each product in `ids` to every category (taxon) in `category_ids`.
+ Attaches each product in `ids` to every category (category) in `category_ids`.
Categories from sibling stores are silently ignored.
@@ -16792,15 +16822,15 @@ paths:
- id: coupon_UkLWZg9DAJ
code: AAA111
state: unused
- created_at: '2026-08-07T20:49:15.456Z'
- updated_at: '2026-08-07T20:49:15.456Z'
+ created_at: '2026-08-10T07:56:28.344Z'
+ updated_at: '2026-08-10T07:56:28.344Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
- id: coupon_gbHJdmfrXB
code: BBB222
state: unused
- created_at: '2026-08-07T20:49:15.457Z'
- updated_at: '2026-08-07T20:49:15.457Z'
+ created_at: '2026-08-10T07:56:28.345Z'
+ updated_at: '2026-08-10T07:56:28.345Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
meta:
@@ -16862,8 +16892,8 @@ paths:
example:
data:
- id: pact_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:26.655Z'
- updated_at: '2026-08-07T20:49:26.655Z'
+ created_at: '2026-08-10T07:56:41.324Z'
+ updated_at: '2026-08-10T07:56:41.324Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -16927,8 +16957,8 @@ paths:
application/json:
example:
id: pact_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:26.731Z'
- updated_at: '2026-08-07T20:49:26.731Z'
+ created_at: '2026-08-10T07:56:41.362Z'
+ updated_at: '2026-08-10T07:56:41.362Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -17056,8 +17086,8 @@ paths:
example:
data:
- id: prorule_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:26.797Z'
- updated_at: '2026-08-07T20:49:26.797Z'
+ created_at: '2026-08-10T07:56:41.412Z'
+ updated_at: '2026-08-10T07:56:41.412Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -17127,8 +17157,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:26.833Z'
- updated_at: '2026-08-07T20:49:26.833Z'
+ created_at: '2026-08-10T07:56:41.455Z'
+ updated_at: '2026-08-10T07:56:41.455Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -17219,8 +17249,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:26.858Z'
- updated_at: '2026-08-07T20:49:26.874Z'
+ created_at: '2026-08-10T07:56:41.480Z'
+ updated_at: '2026-08-10T07:56:41.496Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -17328,7 +17358,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-07T20:49:26.903Z'
+ starts_at: '2026-08-10T07:56:41.525Z'
expires_at:
usage_limit:
match_policy: all
@@ -17339,8 +17369,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-07T20:49:26.904Z'
- updated_at: '2026-08-07T20:49:26.904Z'
+ created_at: '2026-08-10T07:56:41.525Z'
+ updated_at: '2026-08-10T07:56:41.525Z'
action_ids: []
rule_ids: []
meta:
@@ -17447,7 +17477,7 @@ paths:
name: Black Friday
description:
code: blackfriday-os
- starts_at: '2026-08-07T20:49:27.011Z'
+ starts_at: '2026-08-10T07:56:41.623Z'
expires_at:
usage_limit:
match_policy: all
@@ -17458,8 +17488,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-07T20:49:27.011Z'
- updated_at: '2026-08-07T20:49:27.030Z'
+ created_at: '2026-08-10T07:56:41.623Z'
+ updated_at: '2026-08-10T07:56:41.641Z'
action_ids:
- pact_UkLWZg9DAJ
- pact_gbHJdmfrXB
@@ -17625,7 +17655,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-07T20:49:27.061Z'
+ starts_at: '2026-08-10T07:56:41.673Z'
expires_at:
usage_limit:
match_policy: all
@@ -17636,8 +17666,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-07T20:49:27.061Z'
- updated_at: '2026-08-07T20:49:27.061Z'
+ created_at: '2026-08-10T07:56:41.673Z'
+ updated_at: '2026-08-10T07:56:41.673Z'
action_ids: []
rule_ids: []
patch:
@@ -17734,7 +17764,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-07T20:49:27.149Z'
+ starts_at: '2026-08-10T07:56:41.783Z'
expires_at:
usage_limit:
match_policy: all
@@ -17745,8 +17775,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-07T20:49:27.149Z'
- updated_at: '2026-08-07T20:49:27.169Z'
+ created_at: '2026-08-10T07:56:41.784Z'
+ updated_at: '2026-08-10T07:56:41.802Z'
action_ids: []
rule_ids: []
requestBody:
@@ -18218,15 +18248,15 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-dc60b490dc3f
+ transaction_id: BGS-4b3da068f811
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
originator_id:
originator_type:
metadata: {}
- created_at: '2026-08-07T20:49:21.978Z'
- updated_at: '2026-08-07T20:49:21.978Z'
+ created_at: '2026-08-10T07:56:36.564Z'
+ updated_at: '2026-08-10T07:56:36.564Z'
requestBody:
content:
application/json:
@@ -18370,8 +18400,8 @@ paths:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-07T20:49:27.590Z'
- updated_at: '2026-08-07T20:49:27.590Z'
+ created_at: '2026-08-10T07:56:42.226Z'
+ updated_at: '2026-08-10T07:56:42.226Z'
non_expiring: false
meta:
page: 1
@@ -18465,8 +18495,8 @@ paths:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-07T20:49:27.623Z'
- updated_at: '2026-08-07T20:49:27.623Z'
+ created_at: '2026-08-10T07:56:42.268Z'
+ updated_at: '2026-08-10T07:56:42.268Z'
non_expiring: false
schema:
"$ref": "#/components/schemas/StoreCreditCategory"
@@ -18543,8 +18573,8 @@ paths:
preferred_storefront_access: public
preferred_guest_checkout: true
preferred_order_routing_strategy: Spree::OrderRouting::Strategy::Rules
- created_at: '2026-08-07T20:49:13.267Z'
- updated_at: '2026-08-07T20:49:27.672Z'
+ created_at: '2026-08-10T07:56:25.926Z'
+ updated_at: '2026-08-10T07:56:42.329Z'
url: http://www.example.com:3000
api_url: http://www.example.com:3000
setup_tasks:
@@ -18841,8 +18871,8 @@ paths:
preferred_storefront_access: public
preferred_guest_checkout: true
preferred_order_routing_strategy: Spree::OrderRouting::Strategy::Rules
- created_at: '2026-08-07T20:49:13.267Z'
- updated_at: '2026-08-07T20:49:27.749Z'
+ created_at: '2026-08-10T07:56:25.926Z'
+ updated_at: '2026-08-10T07:56:42.413Z'
url: http://www.example.com:3000
api_url: http://www.example.com:3000
setup_tasks:
@@ -19231,7 +19261,7 @@ paths:
- key: name
type: string
- key: description
- type: string
+ type: html
- key: permalink
type: string
readable: false
@@ -19246,11 +19276,6 @@ paths:
- key: permalink
type: string
readable: true
- - resource_type: taxonomy
- fields:
- - key: name
- type: string
- readable: false
- resource_type: store
fields:
- key: name
@@ -19420,13 +19445,13 @@ paths:
example:
data:
- id: adm_UkLWZg9DAJ
- first_name: Prudence
- last_name: Steuber
- full_name: Prudence Steuber
+ first_name: Rocco
+ last_name: Hilll
+ full_name: Rocco Hilll
selected_locale:
- created_at: '2026-08-07T20:49:13.381Z'
- updated_at: '2026-08-07T20:49:13.381Z'
+ created_at: '2026-08-10T07:56:26.076Z'
+ updated_at: '2026-08-10T07:56:26.076Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -19492,13 +19517,13 @@ paths:
application/json:
example:
id: adm_UkLWZg9DAJ
- first_name: Jerilyn
- last_name: Herman
- full_name: Jerilyn Herman
+ first_name: Denis
+ last_name: Kirlin
+ full_name: Denis Kirlin
selected_locale:
- created_at: '2026-08-07T20:49:13.460Z'
- updated_at: '2026-08-07T20:49:13.460Z'
+ created_at: '2026-08-10T07:56:26.203Z'
+ updated_at: '2026-08-10T07:56:26.203Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -19559,13 +19584,13 @@ paths:
application/json:
example:
id: adm_UkLWZg9DAJ
first_name: Renamed
- last_name: Hegmann
- full_name: Renamed Hegmann
+ last_name: Ryan
+ full_name: Renamed Ryan
selected_locale:
- created_at: '2026-08-07T20:49:13.482Z'
- updated_at: '2026-08-07T20:49:13.496Z'
+ created_at: '2026-08-10T07:56:26.234Z'
+ updated_at: '2026-08-10T07:56:26.248Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -19681,15 +19706,15 @@ paths:
example:
data:
- id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-08-07T20:49:17.601Z'
- updated_at: '2026-08-07T20:49:17.601Z'
- expires_at: '2026-08-21T20:49:17.599Z'
+ created_at: '2026-08-10T07:56:31.385Z'
+ updated_at: '2026-08-10T07:56:31.385Z'
+ expires_at: '2026-08-24T07:56:31.382Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=nvKgigEw4WuV7pvf4RgeYp6z"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=Gah5dom1BiSj4GbLwVZEx3Me"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -19753,13 +19778,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-08-07T20:49:17.638Z'
- updated_at: '2026-08-07T20:49:17.638Z'
- expires_at: '2026-08-21T20:49:17.636Z'
+ created_at: '2026-08-10T07:56:31.426Z'
+ updated_at: '2026-08-10T07:56:31.426Z'
+ expires_at: '2026-08-24T07:56:31.423Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=Wwf8ytmXfqBgbzaRN3k3cxrM"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=n7nPCM2PE1yicTjjNUshvS1W"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -19872,15 +19897,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-08-07T20:49:17.676Z'
- updated_at: '2026-08-07T20:49:17.676Z'
- expires_at: '2026-08-21T20:49:17.674Z'
+ created_at: '2026-08-10T07:56:31.463Z'
+ updated_at: '2026-08-10T07:56:31.463Z'
+ expires_at: '2026-08-24T07:56:31.461Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=cDqJm6Lf2xsySRuGF4u8Fanp"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=s7SEGQibhmQtvWYK7bS8cVUQ"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -20211,8 +20236,8 @@ paths:
- id: role_UkLWZg9DAJ
name: admin
description:
- created_at: '2026-08-07T20:49:27.259Z'
- updated_at: '2026-08-07T20:49:27.259Z'
+ created_at: '2026-08-10T07:56:41.895Z'
+ updated_at: '2026-08-10T07:56:41.895Z'
permissions:
- read_orders
- write_orders
@@ -20310,8 +20335,8 @@ paths:
id: role_gbHJdmfrXB
name: order_manager
description: Handles daily orders
- created_at: '2026-08-07T20:49:27.292Z'
- updated_at: '2026-08-07T20:49:27.292Z'
+ created_at: '2026-08-10T07:56:41.932Z'
+ updated_at: '2026-08-10T07:56:41.932Z'
permissions:
- write_orders
- read_customers
@@ -20405,8 +20430,8 @@ paths:
id: role_gbHJdmfrXB
name: support
description:
- created_at: '2026-08-07T20:49:27.315Z'
- updated_at: '2026-08-07T20:49:27.329Z'
+ created_at: '2026-08-10T07:56:41.955Z'
+ updated_at: '2026-08-10T07:56:41.968Z'
permissions:
- read_orders
- read_customers
@@ -20602,8 +20627,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-08-07T20:49:27.372Z'
- updated_at: '2026-08-07T20:49:27.372Z'
+ created_at: '2026-08-10T07:56:42.011Z'
+ updated_at: '2026-08-10T07:56:42.011Z'
meta:
page: 1
limit: 25
@@ -20717,8 +20742,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 30
pickup_instructions:
- created_at: '2026-08-07T20:49:27.429Z'
- updated_at: '2026-08-07T20:49:27.429Z'
+ created_at: '2026-08-10T07:56:42.065Z'
+ updated_at: '2026-08-10T07:56:42.065Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -20895,8 +20920,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-08-07T20:49:27.462Z'
- updated_at: '2026-08-07T20:49:27.462Z'
+ created_at: '2026-08-10T07:56:42.094Z'
+ updated_at: '2026-08-10T07:56:42.094Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'404':
@@ -20985,8 +21010,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 45
pickup_instructions:
- created_at: '2026-08-07T20:49:27.517Z'
- updated_at: '2026-08-07T20:49:27.534Z'
+ created_at: '2026-08-10T07:56:42.139Z'
+ updated_at: '2026-08-10T07:56:42.153Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -21229,14 +21254,14 @@ paths:
dimensions_unit:
backorder_limit:
deleted_at:
- created_at: '2026-08-07T20:49:27.953Z'
- updated_at: '2026-08-07T20:49:27.962Z'
+ created_at: '2026-08-10T07:56:42.606Z'
+ updated_at: '2026-08-10T07:56:42.614Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 96524
+ product_name: Product 968003
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
sku: SKU-116
@@ -21249,10 +21274,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 5.68
- height: 161.77
- width: 17.11
- depth: 89.6
+ weight: 48.11
+ height: 50.4
+ width: 76.97
+ depth: 43.33
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -21275,8 +21300,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:27.976Z'
- updated_at: '2026-08-07T20:49:27.976Z'
+ created_at: '2026-08-10T07:56:42.635Z'
+ updated_at: '2026-08-10T07:56:42.635Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -21286,14 +21311,14 @@ paths:
dimensions_unit:
backorder_limit:
deleted_at:
- created_at: '2026-08-07T20:49:27.973Z'
- updated_at: '2026-08-07T20:49:27.982Z'
+ created_at: '2026-08-10T07:56:42.632Z'
+ updated_at: '2026-08-10T07:56:42.643Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 96524
+ product_name: Product 968003
meta:
page: 1
limit: 25
@@ -21407,8 +21432,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:28.090Z'
- updated_at: '2026-08-07T20:49:28.090Z'
+ created_at: '2026-08-10T07:56:42.755Z'
+ updated_at: '2026-08-10T07:56:42.755Z'
metadata: {}
position: 3
cost_price:
@@ -21418,14 +21443,14 @@ paths:
dimensions_unit:
backorder_limit:
deleted_at:
- created_at: '2026-08-07T20:49:28.095Z'
- updated_at: '2026-08-07T20:49:28.097Z'
+ created_at: '2026-08-10T07:56:42.758Z'
+ updated_at: '2026-08-10T07:56:42.759Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 979718
+ product_name: Product 978
'422':
description: validation error
content:
@@ -21612,10 +21637,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 66.38
- height: 141.15
- width: 32.44
- depth: 11.61
+ weight: 185.74
+ height: 118.6
+ width: 48.68
+ depth: 80.6
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -21638,8 +21663,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:28.245Z'
- updated_at: '2026-08-07T20:49:28.245Z'
+ created_at: '2026-08-10T07:56:42.885Z'
+ updated_at: '2026-08-10T07:56:42.885Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -21649,14 +21674,14 @@ paths:
dimensions_unit:
backorder_limit:
deleted_at:
- created_at: '2026-08-07T20:49:28.243Z'
- updated_at: '2026-08-07T20:49:28.253Z'
+ created_at: '2026-08-10T07:56:42.883Z'
+ updated_at: '2026-08-10T07:56:42.892Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 994543
+ product_name: Product 992493
'404':
description: variant not found
content:
@@ -21740,10 +21765,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 44.48
- height: 178.9
- width: 79.4
- depth: 100.57
+ weight: 16.85
+ height: 167.48
+ width: 127.12
+ depth: 88.52
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -21766,8 +21791,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-07T20:49:28.473Z'
- updated_at: '2026-08-07T20:49:28.473Z'
+ created_at: '2026-08-10T07:56:43.022Z'
+ updated_at: '2026-08-10T07:56:43.022Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -21777,14 +21802,14 @@ paths:
dimensions_unit:
backorder_limit:
deleted_at:
- created_at: '2026-08-07T20:49:28.467Z'
- updated_at: '2026-08-07T20:49:28.526Z'
+ created_at: '2026-08-10T07:56:43.020Z'
+ updated_at: '2026-08-10T07:56:43.047Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1011525
+ product_name: Product 1019359
requestBody:
content:
application/json:
@@ -22029,9 +22054,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-07T20:49:28.656Z'
- updated_at: '2026-08-07T20:49:28.656Z'
- delivered_at: '2026-08-07T20:49:28.656Z'
+ created_at: '2026-08-10T07:56:43.204Z'
+ updated_at: '2026-08-10T07:56:43.204Z'
+ delivered_at: '2026-08-10T07:56:43.204Z'
payload:
event: order.created
data:
@@ -22047,9 +22072,9 @@ paths:
request_errors:
response_body:
success: true
- created_at: '2026-08-07T20:49:28.655Z'
- updated_at: '2026-08-07T20:49:28.655Z'
- delivered_at: '2026-08-07T20:49:28.655Z'
+ created_at: '2026-08-10T07:56:43.203Z'
+ updated_at: '2026-08-10T07:56:43.203Z'
+ delivered_at: '2026-08-10T07:56:43.202Z'
payload:
event: order.created
data:
@@ -22152,9 +22177,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-07T20:49:28.746Z'
- updated_at: '2026-08-07T20:49:28.746Z'
- delivered_at: '2026-08-07T20:49:28.746Z'
+ created_at: '2026-08-10T07:56:43.380Z'
+ updated_at: '2026-08-10T07:56:43.380Z'
+ delivered_at: '2026-08-10T07:56:43.380Z'
payload:
event: order.created
data:
@@ -22243,8 +22268,8 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-07T20:49:28.877Z'
- updated_at: '2026-08-07T20:49:28.877Z'
+ created_at: '2026-08-10T07:56:43.493Z'
+ updated_at: '2026-08-10T07:56:43.493Z'
delivered_at:
payload:
event: order.created
@@ -22347,8 +22372,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-07T20:49:28.909Z'
- updated_at: '2026-08-07T20:49:28.909Z'
+ created_at: '2026-08-10T07:56:43.518Z'
+ updated_at: '2026-08-10T07:56:43.518Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -22443,10 +22468,10 @@ paths:
subscriptions:
- order.placed
disabled_reason:
- created_at: '2026-08-07T20:49:29.019Z'
- updated_at: '2026-08-07T20:49:29.019Z'
+ created_at: '2026-08-10T07:56:43.643Z'
+ updated_at: '2026-08-10T07:56:43.643Z'
disabled_at:
- secret_key: 12f85dd0db4275f8652ca091c77f6f1de34e7dd884fb504dd63c5d3558d67f21
+ secret_key: 74241d12354d4c03818da756ffdd3d88535e93faada6c68cf152b9a6977596ad
last_delivery_at:
recent_delivery_count: 0
recent_failure_count: 0
@@ -22569,8 +22594,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-07T20:49:29.102Z'
- updated_at: '2026-08-07T20:49:29.102Z'
+ created_at: '2026-08-10T07:56:43.717Z'
+ updated_at: '2026-08-10T07:56:43.717Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -22649,8 +22674,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-07T20:49:29.180Z'
- updated_at: '2026-08-07T20:49:29.194Z'
+ created_at: '2026-08-10T07:56:43.876Z'
+ updated_at: '2026-08-10T07:56:43.892Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -22807,13 +22832,13 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-07T20:49:29.371Z'
- updated_at: '2026-08-07T20:49:29.371Z'
+ created_at: '2026-08-10T07:56:44.018Z'
+ updated_at: '2026-08-10T07:56:44.018Z'
delivered_at:
payload:
- id: 90f4189d-2e70-443e-a8e2-6c8dab47a027
+ id: 9e1fccd0-170e-4580-82de-b8179368e426
name: webhook.test
- created_at: '2026-08-07T20:49:29Z'
+ created_at: '2026-08-10T07:56:44Z'
data:
message: This is a test webhook from Spree.
metadata:
@@ -22882,8 +22907,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-07T20:49:29.422Z'
- updated_at: '2026-08-07T20:49:29.439Z'
+ created_at: '2026-08-10T07:56:44.050Z'
+ updated_at: '2026-08-10T07:56:44.068Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -22960,9 +22985,9 @@ paths:
- order.completed
- product.created
disabled_reason: Investigating
- created_at: '2026-08-07T20:49:29.481Z'
- updated_at: '2026-08-07T20:49:29.499Z'
- disabled_at: '2026-08-07T20:49:29.499Z'
+ created_at: '2026-08-10T07:56:44.092Z'
+ updated_at: '2026-08-10T07:56:44.108Z'
+ disabled_at: '2026-08-10T07:56:44.107Z'
secret_key:
last_delivery_at:
recent_delivery_count: 0
@@ -23045,8 +23070,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-07T20:49:14.959Z'
- updated_at: '2026-08-07T20:49:14.959Z'
+ created_at: '2026-08-10T07:56:27.851Z'
+ updated_at: '2026-08-10T07:56:27.851Z'
meta:
page: 1
limit: 25
@@ -23114,8 +23139,8 @@ paths:
automatic: true
rules_match_policy: any
metadata: {}
- created_at: '2026-08-07T20:49:15.089Z'
- updated_at: '2026-08-07T20:49:15.091Z'
+ created_at: '2026-08-10T07:56:27.929Z'
+ updated_at: '2026-08-10T07:56:27.930Z'
schema:
"$ref": "#/components/schemas/Collection"
'422':
@@ -23242,8 +23267,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-07T20:49:15.135Z'
- updated_at: '2026-08-07T20:49:15.135Z'
+ created_at: '2026-08-10T07:56:27.976Z'
+ updated_at: '2026-08-10T07:56:27.976Z'
schema:
"$ref": "#/components/schemas/Collection"
'404':
@@ -23307,8 +23332,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-07T20:49:15.181Z'
- updated_at: '2026-08-07T20:49:15.199Z'
+ created_at: '2026-08-10T07:56:28.030Z'
+ updated_at: '2026-08-10T07:56:28.048Z'
schema:
"$ref": "#/components/schemas/Collection"
requestBody:
@@ -23483,8 +23508,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 680
- slug: product-680
+ name: Product 68695
+ slug: product-68695
meta_title:
meta_description:
meta_keywords:
@@ -23496,14 +23521,14 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Ea tempore nostrum provident suscipit ab. Incidunt corrupti
- non possimus aliquam dolor repudiandae consequatur nulla. Voluptate
- necessitatibus explicabo ex illo veritatis aspernatur. Facilis fuga
- asperiores quasi impedit soluta vitae.
- description_html: Ea tempore nostrum provident suscipit ab. Incidunt
- corrupti non possimus aliquam dolor repudiandae consequatur nulla.
- Voluptate necessitatibus explicabo ex illo veritatis aspernatur.
- Facilis fuga asperiores quasi impedit soluta vitae.
+ description: Vel quibusdam mollitia suscipit reiciendis deserunt.
+ Perspiciatis minima omnis necessitatibus culpa corporis. Veniam
+ cupiditate corporis maiores eligendi. Id a earum doloremque officia
+ laborum.
+ description_html: Vel quibusdam mollitia suscipit reiciendis deserunt.
+ Perspiciatis minima omnis necessitatibus culpa corporis. Veniam
+ cupiditate corporis maiores eligendi. Id a earum doloremque officia
+ laborum.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -23518,14 +23543,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-07T20:49:15.281Z'
- updated_at: '2026-08-07T20:49:15.281Z'
+ created_at: '2026-08-10T07:56:28.142Z'
+ updated_at: '2026-08-10T07:56:28.142Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-07T20:49:15.272Z'
- updated_at: '2026-08-07T20:49:15.285Z'
+ created_at: '2026-08-10T07:56:28.130Z'
+ updated_at: '2026-08-10T07:56:28.148Z'
product_type_id:
tax_category_id: taxcat_UkLWZg9DAJ
schema:
@@ -23729,8 +23754,8 @@ paths:
pickup_point_provider:
storefront_visible: true
tracking_url:
- created_at: '2026-08-07T20:49:16.508Z'
- updated_at: '2026-08-07T20:49:16.509Z'
+ created_at: '2026-08-10T07:56:29.863Z'
+ updated_at: '2026-08-10T07:56:29.864Z'
deleted_at:
tax_category_id:
delivery_zone_ids: []
@@ -23809,8 +23834,8 @@ paths:
pickup_point_provider:
storefront_visible: true
tracking_url:
- created_at: '2026-08-07T20:49:16.552Z'
- updated_at: '2026-08-07T20:49:16.553Z'
+ created_at: '2026-08-10T07:56:29.936Z'
+ updated_at: '2026-08-10T07:56:29.937Z'
deleted_at:
tax_category_id:
delivery_zone_ids: []
@@ -23957,12 +23982,12 @@ paths:
- type: Spree::Calculator::Shipping::PriceSack
name: Price sack
preference_schema:
- - key: currency
- type: string
- default: USD
- key: discount_amount
type: decimal
default: 0
+ - key: currency
+ type: string
+ default: USD
- key: minimal_amount
type: decimal
default: 0
@@ -24046,8 +24071,8 @@ paths:
country_iso: US
state_abbr:
state_name:
- created_at: '2026-08-07T20:49:16.611Z'
- updated_at: '2026-08-07T20:49:16.611Z'
+ created_at: '2026-08-10T07:56:30.019Z'
+ updated_at: '2026-08-10T07:56:30.019Z'
- id: dzm_gbHJdmfrXB
member_type: postal_code
postal_code_prefix: '10'
@@ -24056,10 +24081,10 @@ paths:
country_iso: US
state_abbr:
state_name:
- created_at: '2026-08-07T20:49:16.611Z'
- updated_at: '2026-08-07T20:49:16.611Z'
- created_at: '2026-08-07T20:49:16.610Z'
- updated_at: '2026-08-07T20:49:16.610Z'
+ created_at: '2026-08-10T07:56:30.020Z'
+ updated_at: '2026-08-10T07:56:30.020Z'
+ created_at: '2026-08-10T07:56:30.019Z'
+ updated_at: '2026-08-10T07:56:30.019Z'
delivery_method_ids: []
requestBody:
content:
@@ -24157,8 +24182,8 @@ paths:
fulfillment_types:
- shipping
products_count: 0
- created_at: '2026-08-07T20:49:24.637Z'
- updated_at: '2026-08-07T20:49:24.637Z'
+ created_at: '2026-08-10T07:56:39.339Z'
+ updated_at: '2026-08-10T07:56:39.339Z'
option_type_ids: []
category_ids: []
custom_field_definitions: []
@@ -24234,8 +24259,8 @@ paths:
fulfillment_types:
- shipping
products_count: 0
- created_at: '2026-08-07T20:49:24.687Z'
- updated_at: '2026-08-07T20:49:24.687Z'
+ created_at: '2026-08-10T07:56:39.413Z'
+ updated_at: '2026-08-10T07:56:39.413Z'
option_type_ids: []
category_ids: []
custom_field_definitions: []
@@ -24337,8 +24362,8 @@ paths:
fulfillment_types:
- shipping
products_count: 0
- created_at: '2026-08-07T20:49:24.729Z'
- updated_at: '2026-08-07T20:49:24.729Z'
+ created_at: '2026-08-10T07:56:39.447Z'
+ updated_at: '2026-08-10T07:56:39.447Z'
option_type_ids: []
category_ids: []
custom_field_definitions: []
@@ -24392,8 +24417,8 @@ paths:
fulfillment_types:
- shipping
products_count: 0
- created_at: '2026-08-07T20:49:24.774Z'
- updated_at: '2026-08-07T20:49:24.789Z'
+ created_at: '2026-08-10T07:56:39.497Z'
+ updated_at: '2026-08-10T07:56:39.513Z'
option_type_ids: []
category_ids: []
custom_field_definitions: []
@@ -25997,6 +26022,9 @@ components:
type: array
items:
type: string
+ internal_note:
+ type: string
+ nullable: true
internal_note_html:
type: string
nullable: true
@@ -26042,6 +26070,7 @@ components:
- created_at
- updated_at
- tags
+ - internal_note
- internal_note_html
- default_billing_address_id
- default_shipping_address_id
@@ -27582,6 +27611,9 @@ components:
internal_note:
type: string
nullable: true
+ internal_note_html:
+ type: string
+ nullable: true
approver_id:
type: string
nullable: true
@@ -27683,6 +27715,7 @@ components:
- preferred_stock_location_id
- tags
- internal_note
+ - internal_note_html
- approver_id
- canceler_id
- created_by_id
diff --git a/docs/developer/upgrades/5.6-to-6.0.mdx b/docs/developer/upgrades/5.6-to-6.0.mdx
index ecded983e7..eaf8366253 100644
--- a/docs/developer/upgrades/5.6-to-6.0.mdx
+++ b/docs/developer/upgrades/5.6-to-6.0.mdx
@@ -89,6 +89,35 @@ bundle exec rake spree:migrate_taxons_to_categories_and_collections
Taxons become `Spree::Category` (hierarchy) and automatic taxons become `Spree::Collection` (flat, rule-based). `Spree::Taxon` remains as an alias for one release.
+### Move rich text out of Action Text
+
+```bash
+bundle exec rake spree:migrate_rich_text_to_columns
+```
+
+Category and collection descriptions, policy bodies, and order and customer internal notes move from `action_text_rich_texts` into text columns on their own tables. Per-locale rows land in the model's translation table.
+
+Run this **after** two earlier steps, both load-bearing: the categories step re-points the rows from `Spree::Taxon` to `Spree::Category` so this one can still find them, and the customers step populates `spree_customers` — a note is copied onto the customer row it belongs to, so running before those rows exist would treat every legacy customer note as orphaned and skip it for good. Following the manifest order handles this for you.
+
+Content is sanitized on the way in, and **the 6.0 allowlist is much narrower than 5.6's**: it permits only what the dashboard's editor emits — paragraphs, headings, `strong`/`em`/`s`/`u`/`code`, `pre`, `blockquote`, lists, `hr`, `br` and links. Tables, images, `div`/`span`, inline `style` and arbitrary `class` attributes are no longer permitted. Text inside a stripped tag survives; its formatting does not. The exceptions are `script` and `style`, which are removed along with their contents — a script body would otherwise reappear as visible text.
+
+If your descriptions rely on richer markup, permit it in an initializer **before** running the task and before saving anything under 6.0:
+
+```ruby
+# config/initializers/spree.rb
+Spree::RichTextSanitizer.allowed_tags += %w[table thead tbody tr th td img]
+Spree::RichTextSanitizer.allowed_attributes += %w[src alt colspan rowspan]
+```
+
+The Action Text rows are left in place as a rollback path and are dropped with the tables in 6.1.
+
+Once this has run, **Spree no longer loads Action Text.** `spree_core` dropped `require 'action_text/engine'` — along with `action_cable/engine`, which nothing in Spree used — and a fresh install no longer creates the tables. The rake task requires Action Text itself, so the upgrade works either way. If your own code uses `has_rich_text`, Action Text view helpers, or Action Cable, require what you need in `config/application.rb` (apps generated from the Spree starter already do):
+
+```ruby
+require 'action_text/engine'
+require 'action_cable/engine'
+```
+
### Backfill order coupon codes
```bash
@@ -440,6 +469,26 @@ Two enforcement changes on the Admin API:
- **JWT staff pass the same per-controller key gate as secret keys.** A request whose principal lacks `<read|write>_<resource>` gets a 403 with `details.required_permission` naming the missing key.
- **Staff endpoints moved out of the `settings` scope.** `/admin_users`, `/invitations`, and `/roles` now require the new `read_staff` / `write_staff` scopes; secret keys minted with `settings` before 6.0 lose those endpoints. `/countries` and `/locales` became scope-exempt reference data.
+### Rich-text fields read as plain text plus HTML
+
+**Writes are unchanged.** `description` and `internal_note` still take the value, and that value is still HTML — the same as 5.6, so no integration needs updating.
+
+Reads are where 6.0 differs. Every rich-text field now returns both shapes:
+
+| Resource | Plain text | HTML |
+| --- | --- | --- |
+| Product, Category, Collection | `description` | `description_html` |
+| Order, Customer | `internal_note` | `internal_note_html` |
+
+Two consequences worth checking in your own code:
+
+- **Hydrate editors from `*_html`.** The plain field is tag-stripped, so binding an editor to `description` and saving it back would flatten the markup on every save.
+- **The field holds HTML.** That is true of every writer — the Admin API, CSV import, the console — so send markup, not plain text with newlines in it.
+
+Both internal-note serializers now return the pair. Previously orders exposed only plain text and customers only HTML.
+
+Stored markup is also held to a narrower allowlist than 5.6 — see [the rich-text migration](#move-rich-text-out-of-action-text) for what is permitted and how to widen it.
+
## For extension authors
- **Don't reach for model business methods from services** — 6.0 code style writes behavior inline in service/workflow steps; models keep data, validations, predicates and persistence primitives. Extensions patching removed model methods (`finalize!` internals, updater hooks) should move to workflow hooks (`Spree.hooks.register('carts.complete.before_finalize') { |flow| ... }` — handlers receive the workflow instance) or event subscribers.
diff --git a/docs/plans/6.0-rich-text-descriptions.md b/docs/plans/6.0-rich-text-descriptions.md
index 7c1e54a946..80fbd5003e 100644
--- a/docs/plans/6.0-rich-text-descriptions.md
+++ b/docs/plans/6.0-rich-text-descriptions.md
@@ -1,14 +1,14 @@
# Rich Text Descriptions
-**Status:** Phases 1–2 partially shipped in 5.4 (`RichTextHelper` + Product serializer split ✓ — PR #13811); **sanitizer retargeted to 5.6** (never shipped, live XSS surface — decisions.md 2026-07-27); ActionText removal pending in 6.0
-**Target:** Spree 5.4 (serializer split ✓) + **5.6 (sanitization — permissive allowlist)** + 6.0 (allowlist tightened to Tiptap set; ActionText removal — **entirely**, dependency included)
-**Depends on:** `6.0-admin-spa.md` (Tiptap is the only editor at 6.0 — no legacy admin), `6.0-replace-taxons-with-categories.md` (sequencing: Phase 3 runs **before** the `spree_taxons` table rename; that plan owns the translation-table renames), `5.4-6.0-custom-fields-rename.md` (`CustomFields::RichText` value storage migrates here), `5.4-metafield-translations.md`, `5.5-6.0-resource-translations-api.md` (translated HTML flows through the same sanitizer)
+**Status:** **COMPLETE (2026-08-09)** — all five phases shipped, including the 6.0 allowlist tightening. ActionText is gone from every model, the `mobility-actiontext` dependency is dropped, `field` + `field_html` reads are live across Product, Category, Collection, Policy, Order and Customer (writes stay on the plain attribute), the allowlist is scoped to the Tiptap-emitted set, and `spree:migrate_rich_text_to_columns` is in the 5.6→6.0 upgrade manifest. The `action_text_rich_texts` tables deliberately survive to 6.1 as the data migration's source and rollback path.
+**Target:** Spree 5.4 (serializer split ✓) + 5.6 (sanitization — permissive allowlist ✓) + 6.0 (ActionText removal ✓ — **entirely**, dependency included)
+**Depends on:** `6.0-admin-spa.md` (Tiptap is the only editor at 6.0 — no legacy admin), `6.0-replace-taxons-with-categories.md` (sequencing: Phase 3 shipped **after** the `spree_taxons` table rename, so `spree:migrate_rich_text_to_columns` runs after `migrate_taxons_to_categories_and_collections` in the manifest — that step retypes the Action Text rows so the copy can still find them; that plan owns the translation-table renames), `5.4-6.0-custom-fields-rename.md` (`CustomFields::RichText` value storage migrates here), `5.4-metafield-translations.md`, `5.5-6.0-resource-translations-api.md` (translated HTML flows through the same sanitizer)
**Author:** Damian + Claude
-**Last updated:** 2026-07-27
+**Last updated:** 2026-08-10
## Summary
-Standardize how rich text (product descriptions, category descriptions, policy bodies, custom-field rich text, internal notes) is stored and served. Move off ActionText as a storage backend in favor of sanitized plain HTML text columns, since the 6.0 admin uses Tiptap (not Trix). Unify the API shape: every rich text field reads as `field` (plain text) + `field_html` (HTML), and **writes as `field_html`** (read/write symmetry).
+Standardize how rich text (product descriptions, category descriptions, policy bodies, custom-field rich text, internal notes) is stored and served. Move off ActionText as a storage backend in favor of sanitized plain HTML text columns, since the 6.0 admin uses Tiptap (not Trix). Unify the API shape: every rich text field reads as `field` (plain text) + `field_html` (HTML). **Writes stay on the plain attribute** — the value is HTML either way, so a second setter would only be a second spelling of the same write.
**Scope expansion vs the original draft (2026-07-27 review):** ActionText is removed *entirely* at 6.0 — including `CustomFields::RichText` values and Order/User internal notes, which the original draft deferred. Both deferrals collapsed under scrutiny: the dashboard already writes Tiptap HTML into rich-text custom fields **today** (through ActionText's Trix allowlist — the exact bug this plan exists to fix), and at 6.0 the SPA's internal-note editor is the *only* editor, so "stays on ActionText for the Rails admin" describes a UI that no longer exists. With those two migrated, nothing in core uses ActionText and the dependency is dropped.
@@ -33,10 +33,10 @@ Rich text storage is inconsistent across models (state at HEAD, 2026-07-27):
- **Store HTML in text columns.** Tiptap produces HTML via `editor.getHTML()`. No ActionText, no Tiptap JSON — HTML is universally consumable (storefronts, emails, search, feeds, mobile); the admin is the only writer.
- **ActionText is dropped entirely at 6.0 — code in 6.0, tables in 6.1.** All five users migrate in 6.0 (Taxon, Policy, CustomFields::RichText, Order#internal_note, User internal_note), and 6.0 removes the runtime surface: the `mobility-actiontext` gemspec dependency, the `has_rich_text`/`backend: :action_text` declarations, and the model-generator template line. The `action_text_rich_texts` **tables** are dropped in 6.1 with the other legacy-table drops (data is copied out in 6.0; the tables linger one release as the rollback path — the same convention `spree_adjustments` follows). Nokogiri (already used by the shipped helper, but only a transitive dependency) is declared in `spree_core.gemspec`.
-- **Read/write symmetry (the v3 non-negotiable):** reads are `field` (plain) + `field_html` (HTML); **writes accept `field_html`**, never HTML-in-the-plain-field — the original draft's "accept HTML in the `description` param" meant a client PATCHing `description: "<p>x</p>"` read back `description: "x"`. The **model owns the bridge** (the OptionType#label pattern): `description_html=` sanitizes and writes the underlying column, paired with the existing reader. Writes to the plain field on rich-text models are rejected (422), not silently stripped.
-- **Sanitize on write, allowlist scoped to what the editor emits.** The dashboard's Tiptap is StarterKit + Link (bold/italic/strike, lists, blockquote, code/pre, headings, links). The allowlist matches that — **no `style`, no `class`** (resolving the original draft's own open question flagging them as attack vectors), no tables/img/figure/span/div until the editor gains them (each future extension widens the allowlist deliberately). Server-side via `Rails::HTML5::SafeListSanitizer` (rails-html-sanitizer ≥ 1.6, present).
+- **One write path, two read shapes (revised on implementation, 2026-08-10).** The draft called for `field_html` write params and treated read/write symmetry as non-negotiable. That was dropped: the value is HTML whichever name it arrives under, so a `field_html=` setter was a second spelling of `field=` — it broke every existing client to match a read field that *deliberately* returns something else (plain text, for meta tags, search and feeds). Writes are therefore unchanged from 5.6 (`description`, `internal_note`, `body`), sanitized by a `before_save`; `field_html` is a **reader only**, and no `field_html=` exists on any model. Pinned by `sanitizable_rich_text_spec.rb` and `categories_controller_spec.rb`.
+- **Sanitize on write, allowlist scoped to what the editor emits.** The dashboard's Tiptap is StarterKit + Link (bold/italic/strike, lists, blockquote, code/pre, headings, links). The allowlist matches that — **no `style`; `class` only as a code block's `language-*` hint**, which is the one class Tiptap emits (resolving the original draft's open question flagging both as attack vectors), no tables/img/figure/span/div until the editor gains them (each future extension widens the allowlist deliberately). Server-side via Loofah scrubbers — a `PermitScrubber` for tags/attributes, preceded by one that prunes `script`/`style` subtrees and narrows `class` — both applied to a single parsed fragment.
- **Plain text extraction via the shipped `Spree::RichTextHelper`** (`app/helpers/spree/rich_text_helper.rb`) — it deliberately maps block boundaries and `<br>` to newlines; the original draft's `.text.squish` would glue Tiptap's whitespace-free blocks together. Serializers standardize on it.
-- **Internal notes standardize on the same shape**: both Admin serializers expose `internal_note` (plain) + `internal_note_html`; controllers permit `internal_note_html`. Text columns on `spree_orders`/`spree_users`, no translations.
+- **Internal notes standardize on the same shape**: both Admin serializers expose `internal_note` (plain) + `internal_note_html`; controllers permit the plain `internal_note`. Text columns on `spree_orders`/`spree_customers`, no translations.
- **Rake tasks never hardcode table names** (`Spree::Taxon.table_name` etc.) — Phase 3 must survive shipping before *or* after the `spree_taxons → spree_categories` rename, though the intended order is before.
- **Models with plain-text-only descriptions keep simple text columns** (Promotion, PaymentMethod, Store, PriceList, CustomerGroup) — no `_html` variant.
@@ -74,7 +74,7 @@ module Spree
end
module Spree
- module SanitizableRichText # concern: sanitizes_rich_text :description — before_save allowlist pass
+ module SanitizableRichText # concern: has_spree_rich_text :description — before_save allowlist pass + field_html reader
end
end
```
@@ -86,7 +86,7 @@ Applied to every rich-text writer path — which includes CSV import (`import_sc
```ruby
class Spree::Product < Spree.base_class
include Spree::SanitizableRichText
- sanitizes_rich_text :description
+ has_spree_rich_text :description
def description_html = description.to_s
def description_html=(value) = self.description = value # sanitized by the concern on save
@@ -133,36 +133,52 @@ Contents: `RichTextSanitizer` + `SanitizableRichText` applied to Product (covers
### Phase 2: Product serializer ✓ shipped (5.4, PR #13811)
-### Phase 3: Taxon off ActionText (before the `spree_categories` rename)
+### Phase 3: Category (and Collection) off ActionText ✓ shipped (2026-08-09)
-Both target columns **already exist** (`spree_taxons.description`, `spree_taxon_translations.description` — verified), and may hold stale pre-ActionText data: the rake task copies **only where an ActionText row exists**, never blindly overwriting; per-locale `action_text_rich_texts` rows (mobility-actiontext `locale` column) land in the translation table. Remove `backend: :action_text`, apply `sanitizes_rich_text`, update `CategorySerializer` to the helper. Table names via `Spree::Taxon.table_name`.
+Landed **after** the `spree_categories` rename rather than before — the rename shipped first (PR #14302), which is why `spree:migrate_rich_text_to_columns` runs immediately after `migrate_taxons_to_categories_and_collections` in the manifest: that step retypes the Action Text rows from `Spree::Taxon` to `Spree::Category`, so the copy can still find them. Both target columns already existed.
-### Phase 4: Policy off ActionText — **needs migrations the original draft lacked**
+**`Spree::Collection` was missing from this plan's model list** — it was added after the plan was written (its own comment pointed back here) and carried `backend: :action_text` too, so the real count was five models, not four. Its `description` columns did not exist and were added; it also gained the `RICH_TEXT_TRANSLATABLE_FIELDS` constant it was missing, so the SPA translation matrix renders a rich-text editor for it.
-`spree_policies` has **no `body` column** and `spree_policy_translations` has **no `body` column** — add both first, then the copy task (same only-where-ActionText-exists rule). Rewrite the ActionText-coupled scopes (`with_body` joins `:rich_text_body`, `without_body` uses `where.missing` — `policy.rb:42-43, 66`) as column-presence checks. **There is no Admin API v3 policies controller at all today** (Store API read-only) — Policy CRUD is built as part of this phase, coordinated with `6.0-admin-api.md`.
+### Phase 4: Policy off ActionText ✓ shipped (2026-08-09)
-### Phase 5: CustomFields::RichText + internal notes + consumer sweep + drop ActionText
+`spree_policies.body` and `spree_policy_translations.body` added as predicted. The ActionText-coupled scopes are now column-presence checks (`with_body` → `where.not(body: [nil, ''])`). **Admin API Policy CRUD was NOT built here** — it stays deferred to `6.0-admin-api.md`; this phase only changed how the existing Store API read path stores and serves the body.
-- `CustomFields::RichText`: **shipped** with the custom-fields rename (spree/spree#14415). `has_rich_text :value` is gone; the model stores sanitized HTML in the existing `value` text column via `sanitizes_rich_text`. The copy runs inside the rename migration rather than a rake task — the STI class name changes in the same migration, so the Action Text rows (filed under the pre-rename base class `Spree::Metafield`) are unreachable afterwards. Source rows are left in place as the rollback path and are dropped with the tables in 6.1.
-- `Order#internal_note` + `User` internal_note → text columns + `sanitizes_rich_text`; serializers/params standardized (`internal_note` + `internal_note_html` on both).
-- Consumer sweep: Meilisearch serialize, Google feed, CSV export (above); model generator template's ActionText line (`generators/spree/model/templates/model.rb.tt:22`).
-- Then: remove `mobility-actiontext` from `spree_core.gemspec`, drop migrated `action_text_rich_texts` rows, drop the ActionText tables in 6.1 alongside the other legacy drops.
-- Type pipeline (typelizer → Zod → OpenAPI → SDK tests) after each serializer change.
+### Phase 5: internal notes + consumer sweep + drop ActionText ✓ shipped (2026-08-09)
+
+- `CustomFields::RichText`: shipped earlier with the custom-fields rename (spree/spree#14415).
+- `Order#internal_note` + Customer internal_note → text columns + `has_spree_rich_text`; both Admin serializers now expose `internal_note` + `internal_note_html` (Order previously shipped plain-only, Customer html-only).
+- Consumer sweep done: Meilisearch presenter and Google feed now index/emit `RichTextHelper.to_plain_text`, CSV export dropped its spurious `html_safe`, and the model generator template emits `has_spree_rich_text` instead of `has_rich_text`.
+- `mobility-actiontext` removed from `spree_core.gemspec`, along with the `require 'mobility/action_text'` in `config/initializers/mobility.rb` that pulled it in (nothing declares that backend now). `action_text/engine` **stays required** — `ActionText::RichText` must keep loading for the data migration and the 6.1 rollback path.
+- Type pipeline run (typelizer → Zod → OpenAPI → SDK tests). Dashboard write sites and the hand-written `packages/admin-sdk/src/params.ts` were updated to the `*_html` write contract.
+
+**Two implementation notes worth keeping:**
+
+- **The copy reads the raw `body` column, never `body.to_s`.** ActionText's renderer wraps output in `<div class="trix-content">`; copying through it would have migrated that wrapper into every column, and since the allowlist drops `class`, it would have left a bare `<div>` behind.
+- **Customer notes are copied after `migrate_users_to_customers`, not before.** That step now retypes `action_text_rich_texts` too (it previously left them behind, so legacy notes stayed filed under the pre-6.0 user class), and the copy still matches `SOURCE_USER_TYPE` for installs that ran an older build of it. The manifest order is nevertheless load-bearing: a note is copied onto the customer row it belongs to, and `spree_customers` is empty until that step runs, so going first would count every legacy note as orphaned and skip it for good.
+
+**Body-pruning shipped with the 6.0 allowlist:** `script`/`style` elements are removed subtree-and-all, so a script body can no longer survive as visible text. Implemented as a `Loofah::Scrubber` chained ahead of `Rails::HTML::PermitScrubber` on **one** parsed fragment — going through `SafeListSanitizer` twice would parse and re-serialize the whole document on every save. `loofah` is declared in `spree_core.gemspec` rather than leaned on transitively, though it was already a hard runtime requirement: `Rails::HTML5::SafeListSanitizer` *is* Loofah under the hood.
+
+Deliberately **not** `SafeListSanitizer.new(prune: true)`, which prunes the contents of *every* disallowed tag: `<iframe>keepme</iframe>` would become `""` instead of `"keepme"`, silently destroying text out of the legacy TinyMCE content this allowlist exists to preserve. `pruned_tags` keeps the destructive behavior scoped to the two tags whose bodies are never prose — everywhere else a stripped tag leaves its text behind, which is what limits the damage the tightened allowlist does to legacy TinyMCE markup.
## Constraints on Current Work
-- **No new `has_rich_text` or `backend: :action_text` declarations.** New rich text = text column + `SanitizableRichText`.
-- **New rich-text serializers return `field` + `field_html`; writes accept `field_html`.** Never HTML under a plain field name.
+- **No new `has_rich_text` or `backend: :action_text` declarations.** New rich text = text column + `has_spree_rich_text` (from `SanitizableRichText`), which sanitizes on save and defines the `field_html` reader. A translated field needs a bare `sanitizes_rich_text` on the `Translation` class too — Mobility writes bypass the base record's callbacks, and the reader belongs on the parent. **Writes use the plain attribute; there is no `field_html=`.**
+- **New rich-text serializers return `field` + `field_html`; writes take the plain attribute.** `field_html` is a reader — don't add a `field_html=` alongside it.
- **Do not store Tiptap JSON.**
- **Don't widen the sanitizer allowlist ahead of the editor.** Editor gains a node type → allowlist widens in the same PR.
- **Rake tasks use `Model.table_name`** — never literal table names (CLAUDE.md rule; the categories rename may land on either side).
+- **Don't drop the `action_text_rich_texts` tables or the `action_text/engine` require before 6.1.** `spree:migrate_rich_text_to_columns` reads them, and they are the rollback path.
## Resolved Questions
-1. **`style`/`class` stripped entirely** (2026-07-27, closing the original open question): the shipped Tiptap editor (StarterKit + Link) emits neither; the original allowlist admitted attack surface (CSS overlays, class collisions) for markup no writer produces. Text-align classes get allowlisted if/when the editor gains the extension.
-2. **Write contract is `field_html`** (2026-07-27): read/write symmetry per the v3 rule; model-owned bridge; plain-field HTML writes rejected.
+1. **`style` stripped entirely; `class` narrowed to the code-block hint** (2026-07-27, revised on implementation 2026-08-09): the original allowlist admitted attack surface (CSS overlays, class collisions) for markup no writer produces. `style` is gone outright. `class` turned out not to be strippable outright — Tiptap's code block emits `language-*` from its `languageClassPrefix`, so dropping `class` wholesale would corrupt every code block; it is permitted and pattern-narrowed instead. Text-align classes get allowlisted if/when the editor gains the extension.
+
+ **Shipped 2026-08-09.** `style` is gone entirely. `class` is permitted **only** as a code block's `language-*` hint (Tiptap's `languageClassPrefix`, the one class the editor does emit), narrowed by `allowed_class_pattern` in the same scrubber pass that prunes `script`/`style` — so it is not an open attribute. The tag list was derived by reading each StarterKit extension's `renderHTML` rather than inferring from the toolbar, and every editor construct round-trips byte-identical (asserted per node type in the spec).
+
+ Legacy TinyMCE markup outside the set (tables, images, `div`/`span`) is unwrapped on next save: **text survives, formatting does not.** That is the deliberate trade — the alternative was permitting markup no writer produces. The 5.6→6.0 upgrade guide documents the narrowing and shows the initializer to widen it, which merchants with richer legacy content should apply *before* running the migration.
+2. **Write contract is `field_html`** (2026-07-27) — **reversed on implementation (2026-08-10).** It shipped that way briefly and was reverted: the value is HTML under either name, so `field_html=` was a second spelling of `field=` that broke every existing client to chase symmetry with a read field which intentionally differs. Writes stay on the plain attribute, sanitized on save; `field_html` is a reader only. See the Key Decisions entry above.
3. **ActionText is fully dropped, not reduced** (2026-07-27): custom-field rich text and internal notes migrate too — the dashboard already Tiptaps both surfaces (custom fields today, internal notes at 6.0 when the SPA is the only admin), and keeping ActionText for them preserves the exact Trix-corruption bug this plan exists to fix.
-4. **Sequencing with the categories rename** (2026-07-27): Phase 3 before the table rename by intent, table-name-agnostic by construction. The categories plan drops its `backend: :action_text` line (fixed) and owns the translation-table renames.
+4. **Sequencing with the categories rename** (2026-07-27; **outcome reversed 2026-08-09**): the intent was Phase 3 first, but the rename shipped first (PR #14302). Being table-name-agnostic by construction is what made that harmless — the copy task simply runs *after* `migrate_taxons_to_categories_and_collections` in the manifest, which retypes the Action Text rows from `Spree::Taxon` to `Spree::Category` so they remain findable. The categories plan drops its `backend: :action_text` line (fixed) and owns the translation-table renames.
## Open Questions
@@ -170,9 +186,9 @@ Both target columns **already exist** (`spree_taxons.description`, `spree_taxon_
## References
-- Shipped: `spree/core/app/helpers/spree/rich_text_helper.rb`, `spree/api/app/serializers/spree/api/v3/product_serializer.rb:48-56` (PR #13811)
-- ActionText users (the complete set, verified): `taxon.rb:164`, `policy.rb:30`, `order.rb:49`, `user_methods.rb:109`, `metafields/rich_text.rb:7`
-- Inconsistent internal-note serializers: `admin/order_serializer.rb:51-52` (plain only) vs `admin/customer_serializer.rb:48-49` (html only)
-- Raw-HTML consumers: `search_provider/product_presenter.rb:52`, `data_feeds/google_presenter.rb:68`, `csv/product_variant_presenter.rb:88`, `import_schemas/products.rb:10`
+- Primitives: `spree/core/app/helpers/spree/rich_text_helper.rb` (plain-text extraction), `app/models/spree/rich_text_sanitizer.rb` (allowlist + body-pruning), `app/models/concerns/spree/sanitizable_rich_text.rb` (`has_spree_rich_text`, plus `sanitizes_rich_text` alone for Translation classes)
+- Data migration: `lib/tasks/migrate_rich_text_to_columns.rake` + `spec/lib/tasks/migrate_rich_text_to_columns_spec.rb`; manifest step `migrate_rich_text_to_columns` in `lib/spree/upgrades/5_6_to_6_0/manifest.yml`
+- Migrated models (was `taxon.rb`, `collection.rb`, `policy.rb`, `order.rb`, `customer_methods.rb`, `custom_fields/rich_text.rb`): all now text column + `sanitizes_rich_text`, with the sanitize pass repeated on each `Translation` class
+- Columns added: `20260809200001_add_rich_text_columns_for_action_text_removal.rb` (collection + policy descriptions/bodies and their translations, customer internal_note)
- Related plans: `6.0-admin-spa.md` (Tiptap; `<InternalNoteCard>`, `<CustomFieldsDrawer>`), `6.0-replace-taxons-with-categories.md`, `5.4-6.0-custom-fields-rename.md`, `5.4-metafield-translations.md`, `5.5-6.0-resource-translations-api.md`, `6.0-admin-api.md` (Policy CRUD; write-contract mirror)
- Tiptap HTML output docs: https://tiptap.dev/docs/editor/guide/output#html
diff --git a/packages/admin-sdk/examples/orders/create.ts b/packages/admin-sdk/examples/orders/create.ts
index b730a0cfe5..1deee84bc7 100644
--- a/packages/admin-sdk/examples/orders/create.ts
+++ b/packages/admin-sdk/examples/orders/create.ts
@@ -11,12 +11,12 @@ const client = createAdminClient({
// except `email` is optional.
const order = await client.orders.create({
- customer_id: 'cus_UkLWZg9DAJ', // Existing customer; omit for guest orders
- use_customer_default_address: false, // true to copy the customer's saved addresses
+ 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
+ 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
@@ -26,7 +26,9 @@ const order = await client.orders.create({
preferred_stock_location_id: 'sloc_UkLWZg9DAJ',
customer_note: 'Please leave at the front desk.',
- internal_note: 'VIP customer — handle with care.',
+ // Rich text: send HTML. Reads return this as plain text, plus
+ // `internal_note_html` with the markup.
+ internal_note: '<p>VIP customer — handle with care.</p>',
metadata: {
external_reference: 'subscription_invoice_2026_04',
source: 'recurring-engine',
@@ -68,6 +70,7 @@ const order = await client.orders.create({
// Optional. Invalid codes are non-fatal — the order is created either way.
coupon_code: 'WELCOME10',
})
+
// endregion:example
export { order }
diff --git a/packages/admin-sdk/examples/orders/update.ts b/packages/admin-sdk/examples/orders/update.ts
index e40c9a7c62..3f3da69093 100644
--- a/packages/admin-sdk/examples/orders/update.ts
+++ b/packages/admin-sdk/examples/orders/update.ts
@@ -8,8 +8,9 @@ const client = createAdminClient({
// region:example
const order = await client.orders.update('or_UkLWZg9DAJ', {
- internal_note: 'VIP — gift wrap on next order',
+ internal_note: '<p>VIP — gift wrap on next order</p>',
})
+
// endregion:example
export { order }
diff --git a/packages/admin-sdk/examples/products/create.ts b/packages/admin-sdk/examples/products/create.ts
index a8ae7e88b6..7c0ae12f15 100644
--- a/packages/admin-sdk/examples/products/create.ts
+++ b/packages/admin-sdk/examples/products/create.ts
@@ -8,7 +8,9 @@ const client = createAdminClient({
// region:example
const product = await client.products.create({
name: 'Premium T-Shirt',
- description: 'Soft, organic cotton.',
+ // Rich text: send HTML. Reads return this as plain text, plus
+ // `description_html` with the markup.
+ description: '<p>Soft, organic cotton.</p>',
status: 'active',
variants: [
{
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 5b705b2088..86f8f765b6 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -269,6 +269,7 @@ export interface OrderCreateParams {
preferred_stock_location_id?: string
locale?: string
customer_note?: string
+ /** Rich text HTML. Reads come back as this plus `internal_note_html`. */
internal_note?: string
metadata?: Record<string, unknown>
shipping_address?: AddressInputParams
@@ -288,6 +289,7 @@ export interface OrderUpdateParams {
email?: string
customer_id?: string
customer_note?: string
+ /** Rich text HTML. Reads come back as this plus `internal_note_html`. */
internal_note?: string
ship_address?: AddressInputParams
bill_address?: AddressInputParams
@@ -365,6 +367,7 @@ export interface CustomerCreateParams {
last_name?: string
phone?: string
accepts_email_marketing?: boolean
+ /** Rich text HTML. Reads come back as this plus `internal_note_html`. */
internal_note?: string
metadata?: Record<string, unknown>
tags?: string[]
@@ -378,6 +381,7 @@ export interface CustomerUpdateParams {
last_name?: string
phone?: string
accepts_email_marketing?: boolean
+ /** Rich text HTML. Reads come back as this plus `internal_note_html`. */
internal_note?: string
metadata?: Record<string, unknown>
tags?: string[]
@@ -457,6 +461,7 @@ export interface ProductPublicationInput {
export interface ProductCreateParams {
name: string
+ /** Rich text HTML. Reads come back as this (plain text) plus `description_html`. */
description?: string
slug?: string
status?: 'draft' | 'active' | 'archived'
@@ -482,6 +487,7 @@ export interface ProductCreateParams {
export interface ProductUpdateParams {
name?: string
+ /** Rich text HTML. Reads come back as this (plain text) plus `description_html`. */
description?: string
slug?: string
status?: 'draft' | 'active' | 'archived'
@@ -540,6 +546,7 @@ export interface CategoryCreateParams {
name: string
/** Prefixed ID of the parent category. Omit or null for a top-level category. */
parent_id?: string | null
+ /** Rich text HTML. Reads come back as this (plain text) plus `description_html`. */
description?: string
permalink?: string
meta_title?: string
@@ -555,6 +562,7 @@ export interface CategoryUpdateParams {
name?: string
/** Prefixed ID of the parent category, or null to move it to the top level. */
parent_id?: string | null
+ /** Rich text HTML. Reads come back as this (plain text) plus `description_html`. */
description?: string
permalink?: string
meta_title?: string
@@ -619,6 +627,7 @@ export interface CollectionRuleParam {
export interface CollectionCreateParams {
name: string
+ /** Rich text HTML. Reads come back as this (plain text) plus `description_html`. */
description?: string
permalink?: string
meta_title?: string
@@ -639,6 +648,7 @@ export interface CollectionCreateParams {
export interface CollectionUpdateParams {
name?: string
+ /** Rich text HTML. Reads come back as this (plain text) plus `description_html`. */
description?: string
permalink?: string
/**
diff --git a/packages/admin-sdk/src/types/generated/Customer.ts b/packages/admin-sdk/src/types/generated/Customer.ts
index c376d27d60..4ec44d9d47 100644
--- a/packages/admin-sdk/src/types/generated/Customer.ts
+++ b/packages/admin-sdk/src/types/generated/Customer.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 6fba848fcffc083056d92227119da72f
+// Typelizer digest a77ca3f28e457cb10400cee7d9c2cdc1
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Address, NewsletterSubscriber, CustomerGroup, Order, StoreCredit} from '@/types'
@@ -23,6 +23,7 @@ interface Customer {
created_at: string;
updated_at: string;
tags: Array<string>;
+ internal_note: string | null;
internal_note_html: string | null;
default_billing_address_id: string | null;
default_shipping_address_id: string | null;
diff --git a/packages/admin-sdk/src/types/generated/Order.ts b/packages/admin-sdk/src/types/generated/Order.ts
index 99b2103f13..510fbfb1f2 100644
--- a/packages/admin-sdk/src/types/generated/Order.ts
+++ b/packages/admin-sdk/src/types/generated/Order.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 2367359de0e1fef1d82e130df6c964a9
+// Typelizer digest 9aa6d70adeda31f8c3a08e690176a893
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {LineItem, Fulfillment, Payment, Address, GiftCard, Market, AppliedPromotion, Cart, Channel, StockLocation, PaymentMethod, Customer, Return, Exchange, Claim} from '@/types'
@@ -63,6 +63,7 @@ interface Order {
preferred_stock_location_id: string | null;
tags: Array<string>;
internal_note: string | null;
+ internal_note_html: string | null;
approver_id: string | null;
canceler_id: string | null;
created_by_id: string | null;
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index 810b0b21c7..cab8b8f96f 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/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add 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}":{"delete":{"summary":"Remove a product from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the category's manual classification.\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 removed"}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, definition is admin-only (was `display_on: back_end`)"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_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":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/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":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_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}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_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"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"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_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/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_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_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 default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_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","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_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/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates a product into the collection (appended to the end).\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"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/collections/{collection_id}/products/{id}":{"delete":{"summary":"Remove a product from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the collection's manual curation.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method. fulfillment_type is one of shipping, digital, pickup, pickup_point.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_ids":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"fulfillment_types":{"type":"array","items":{"type":"string"},"description":"How products of this type can be delivered."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"fulfillment_types":{"type":"array","items":{"type":"string"}},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}}},"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"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"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},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","number","token","email","customer_note","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"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},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"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"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note_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","failed_attempts","metadata","created_at","updated_at","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},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"fulfillment_type":{"type":"string"},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"tax_category_id":{"type":"string","nullable":true},"delivery_zone_ids":{"type":"array","items":{"type":"string"}},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","fulfillment_type","estimated_transit_business_days_min","estimated_transit_business_days_max","admin_name","fulfillment_provider","pickup_point_provider","storefront_visible","tracking_url","created_at","updated_at","deleted_at","tax_category_id","delivery_zone_ids","stock_location_ids","calculator_type","calculator_preferences"],"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},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","postal_code_prefix","postal_code_from","postal_code_to","country_iso","state_abbr","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_method_ids"],"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"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"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},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","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},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"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","rows_count","created_at","updated_at","type","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"}},"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},"cart_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"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"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},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","number","email","customer_note","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","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},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"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"},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","product_type_id","tax_category_id"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"fulfillment_types":{"type":"array","items":{"type":"string"}},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","fulfillment_types","products_count","created_at","updated_at","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"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},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"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},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","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
+{"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"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add 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}":{"delete":{"summary":"Remove a product from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the category's manual classification.\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 removed"}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_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":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/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":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_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}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_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"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"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 (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/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_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_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 default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_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","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_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/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates a product into the collection (appended to the end).\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"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/collections/{collection_id}/products/{id}":{"delete":{"summary":"Remove a product from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the collection's manual curation.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method. fulfillment_type is one of shipping, digital, pickup, pickup_point.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_ids":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"fulfillment_types":{"type":"array","items":{"type":"string"},"description":"How products of this type can be delivered."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"fulfillment_types":{"type":"array","items":{"type":"string"}},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}}},"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"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"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},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","number","token","email","customer_note","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"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},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"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"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"fulfillment_type":{"type":"string"},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"tax_category_id":{"type":"string","nullable":true},"delivery_zone_ids":{"type":"array","items":{"type":"string"}},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","fulfillment_type","estimated_transit_business_days_min","estimated_transit_business_days_max","admin_name","fulfillment_provider","pickup_point_provider","storefront_visible","tracking_url","created_at","updated_at","deleted_at","tax_category_id","delivery_zone_ids","stock_location_ids","calculator_type","calculator_preferences"],"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},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","postal_code_prefix","postal_code_from","postal_code_to","country_iso","state_abbr","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_method_ids"],"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"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"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},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","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},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"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","rows_count","created_at","updated_at","type","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"}},"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},"cart_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"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"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},"internal_note_html":{"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},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","number","email","customer_note","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","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","internal_note_html","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},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"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"},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","product_type_id","tax_category_id"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"fulfillment_types":{"type":"array","items":{"type":"string"}},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","fulfillment_types","products_count","created_at","updated_at","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"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},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"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},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","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/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsx
index 8b4f2017e4..c32b4af753 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/customers/$customerId.tsx
@@ -42,6 +42,7 @@ import {
MetadataCard,
RelativeTime,
ResourceLayout,
+ RichTextEditor,
Select,
SelectContent,
SelectItem,
@@ -214,9 +215,7 @@ function CustomerBody({ customer }: { customer: Customer }) {
<ProfileCard customer={customer} />
<CustomerGroupsCard customer={customer} />
<AddressesCard customer={customer} />
- {/* Key on `updated_at` so the textarea's local state resets after a
- refetch (e.g. another mutation invalidates the customer). */}
- <InternalNoteCard key={customer.updated_at} customer={customer} />
+ <InternalNoteCard customer={customer} />
<Slot name="customer.form_sidebar" context={{ customer }} />
</>
}
@@ -787,6 +786,13 @@ function InternalNoteCard({ customer }: { customer: Customer }) {
const { t } = useTranslation()
const [editing, setEditing] = useState(false)
const [note, setNote] = useState(customer.internal_note_html ?? '')
+ const serverNote = customer.internal_note_html ?? ''
+
+ // Track the server value only while the editor is closed, so a refetch from
+ // an unrelated mutation can't discard a note the user is part-way through.
+ useEffect(() => {
+ if (!editing) setNote(serverNote)
+ }, [editing, serverNote])
const mutation = useUpdateCustomer(customer.id)
@@ -806,10 +812,10 @@ function InternalNoteCard({ customer }: { customer: Customer }) {
<CardContent>
{editing ? (
<div className="flex flex-col gap-3">
- <Textarea
- rows={4}
+ <RichTextEditor
+ ariaLabel={t('admin.pages.customers.detail.section_internal_note')}
value={note}
- onChange={(e) => setNote(e.target.value)}
+ onChange={setNote}
placeholder={t('admin.fields.customer.internal_note.placeholder')}
/>
<div className="flex gap-2 justify-end">
@@ -819,7 +825,7 @@ function InternalNoteCard({ customer }: { customer: Customer }) {
size="sm"
onClick={() => {
setEditing(false)
- setNote(customer.internal_note_html ?? '')
+ setNote(serverNote)
}}
>
{t('admin.actions.cancel')}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/customers/index.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/customers/index.tsx
index ea7bc284dc..4769a2e96f 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/customers/index.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/customers/index.tsx
@@ -23,6 +23,7 @@ import {
FieldGroup,
FieldLabel,
Input,
+ RichTextEditor,
RowActions,
Sheet,
SheetContent,
@@ -30,7 +31,6 @@ import {
SheetFooter,
SheetHeader,
SheetTitle,
- Textarea,
useConfirm,
} from '@spree/dashboard-ui'
import { useMutation } from '@tanstack/react-query'
@@ -405,7 +405,10 @@ function NewCustomerSheet({
if (values.first_name.trim()) payload.first_name = values.first_name.trim()
if (values.last_name.trim()) payload.last_name = values.last_name.trim()
if (values.phone.trim()) payload.phone = values.phone.trim()
- if (values.internal_note.trim()) payload.internal_note = values.internal_note.trim()
+ // The editor emits an empty paragraph once it has been focused and cleared,
+ // which is not a note.
+ const internalNote = values.internal_note.trim()
+ if (internalNote && internalNote !== '<p></p>') payload.internal_note = internalNote
if (values.tags.length) payload.tags = values.tags
try {
@@ -506,12 +509,18 @@ function NewCustomerSheet({
<FieldLabel htmlFor="internal_note">
{t('admin.fields.customer.internal_note.label')}
</FieldLabel>
- <Textarea
- id="internal_note"
- rows={4}
- placeholder={t('admin.fields.customer.internal_note.placeholder')}
- aria-invalid={!!form.formState.errors.internal_note || undefined}
- {...form.register('internal_note')}
+ <Controller
+ control={form.control}
+ name="internal_note"
+ render={({ field }) => (
+ <RichTextEditor
+ id="internal_note"
+ ariaLabel={t('admin.fields.customer.internal_note.label')}
+ placeholder={t('admin.fields.customer.internal_note.placeholder')}
+ value={field.value}
+ onChange={field.onChange}
+ />
+ )}
/>
<FieldError errors={[form.formState.errors.internal_note]} />
</Field>
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsx
index a5765bf455..f930901cdc 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/orders/$orderId.tsx
@@ -44,6 +44,7 @@ import {
MetadataCard,
RelativeTime,
ResourceLayout,
+ RichTextEditor,
Select,
SelectContent,
SelectItem,
@@ -2634,17 +2635,26 @@ function InternalNoteCard({ order }: { order: Order }) {
const { orderId } = Route.useParams()
const [editing, setEditing] = useState(false)
+ // Edit the HTML, not the plain-text projection: `internal_note` has its
+ // markup stripped, so round-tripping it through the `internal_note_html`
+ // write would flatten an existing note on a save that changed nothing.
+ const [note, setNote] = useState(order.internal_note_html ?? '')
+ const serverNote = order.internal_note_html ?? ''
+
+ // Track the server value only while the editor is closed. Any order mutation
+ // refetches this record, and adopting the incoming value mid-edit would throw
+ // away whatever the user is part-way through typing.
+ useEffect(() => {
+ if (!editing) setNote(serverNote)
+ }, [editing, serverNote])
+
const mutation = useOrderMutation(orderId, (params: { internal_note: string }) =>
adminClient.orders.update(orderId, params),
)
function handleSubmit(e: FormEvent<HTMLFormElement>) {
e.preventDefault()
- const fd = new FormData(e.currentTarget)
- mutation.mutate(
- { internal_note: fd.get('internal_note') as string },
- { onSuccess: () => setEditing(false) },
- )
+ mutation.mutate({ internal_note: note }, { onSuccess: () => setEditing(false) })
}
return (
@@ -2660,9 +2670,21 @@ function InternalNoteCard({ order }: { order: Order }) {
<CardContent>
{editing ? (
<form onSubmit={handleSubmit} className="flex flex-col gap-3">
- <Textarea name="internal_note" defaultValue={order.internal_note ?? ''} />
+ <RichTextEditor
+ ariaLabel={t('admin.orders.detail.section_internal_note')}
+ value={note}
+ onChange={setNote}
+ />
<div className="flex justify-end gap-2">
- <Button type="button" variant="outline" size="sm" onClick={() => setEditing(false)}>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => {
+ setNote(serverNote)
+ setEditing(false)
+ }}
+ >
{t('admin.actions.cancel')}
</Button>
<Button type="submit" size="sm" disabled={mutation.isPending}>
@@ -2670,8 +2692,12 @@ function InternalNoteCard({ order }: { order: Order }) {
</Button>
</div>
</form>
- ) : order.internal_note ? (
- <p className="text-sm text-muted-foreground whitespace-pre-wrap">{order.internal_note}</p>
+ ) : order.internal_note_html ? (
+ <div
+ className="prose prose-sm max-w-none text-muted-foreground dark:prose-invert"
+ // biome-ignore lint/security/noDangerouslySetInnerHtml: HTML is sanitized server-side via the rich-text pipeline
+ dangerouslySetInnerHTML={{ __html: order.internal_note_html }}
+ />
) : (
<p className="text-sm text-muted-foreground">{t('admin.common.none')}</p>
)}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
index 34243e37bd..6002019645 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
@@ -132,8 +132,8 @@ function productToFormValues(
name: product.name,
// Hydrate the Tiptap editor from the HTML field, not `description` — the
// serializer squishes that one to tag-stripped plain text, which would
- // collapse paragraphs/line breaks on every reload. Write still goes back
- // through the `description` param (the API accepts HTML there).
+ // collapse paragraphs/line breaks on every reload. Writes send the editor's
+ // HTML back under the plain `description` param.
description: product.description_html ?? '',
status: (product.status as ProductFormValues['status']) ?? 'draft',
category_ids: product.categories?.map((t) => t.id) ?? [],
@@ -337,6 +337,8 @@ function ProductForm({ product }: { product: Product }) {
// Extension fields come from live form state: the Zod parse behind
// `data` strips keys the first-party schema doesn't know.
const extensionValues = extensionSubmitValues('product', form)
+ // `description` rides through as HTML — the editor's output is what the
+ // column stores; the API reads it back as plain text plus `description_html`.
const payload: Record<string, unknown> = { ...rest, ...extensionValues }
if (variants && variants.length > 0) {
diff --git a/packages/dashboard/src/schemas/category.ts b/packages/dashboard/src/schemas/category.ts
index 15f4e55069..cab70f25c8 100644
--- a/packages/dashboard/src/schemas/category.ts
+++ b/packages/dashboard/src/schemas/category.ts
@@ -80,6 +80,8 @@ export function categoryToParams(values: CategoryFormValues) {
// null keeps an existing child category at the top level on update; create
// treats null/undefined the same (no parent).
parent_id: values.parent_id,
+ // HTML in, HTML stored. The API reads it back as plain `description`
+ // plus `description_html`.
description: values.description,
permalink: values.permalink,
meta_title: values.meta_title,
diff --git a/packages/dashboard/src/schemas/collection.ts b/packages/dashboard/src/schemas/collection.ts
index d7624e9b39..55e4e38c83 100644
--- a/packages/dashboard/src/schemas/collection.ts
+++ b/packages/dashboard/src/schemas/collection.ts
@@ -172,6 +172,8 @@ export function collectionToForm(collection: Collection): CollectionFormValues {
export function collectionToParams(values: CollectionFormValues) {
return {
name: values.name,
+ // HTML in, HTML stored. The API reads it back as plain `description`
+ // plus `description_html`.
description: values.description,
permalink: values.permalink,
meta_title: values.meta_title,
diff --git a/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rb
index 0a568a26aa..ae3d9a7f6e 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/customers_controller.rb
@@ -73,7 +73,7 @@ module Spree
# `customer_groups` is preloaded because the serializer's always-on
# `customer_group_ids` attribute reads it for every row.
def collection_includes
- [:rich_text_internal_note, :customer_groups, taggings: :tag]
+ [:customer_groups, taggings: :tag]
end
private
diff --git a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb
index 1739aac628..a1565af3ec 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/orders_controller.rb
@@ -129,7 +129,7 @@ module Spree
end
def collection_includes
- [:line_items, :customer, :channel, :rich_text_internal_note]
+ [:line_items, :customer, :channel]
end
private
diff --git a/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
index 2c1177da4b..3bcea553a7 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/customer_serializer.rb
@@ -7,7 +7,7 @@ module Spree
class CustomerSerializer < V3::CustomerSerializer
typelize failed_attempts: :number,
tags: [:string, multi: true],
- internal_note_html: [:string, nullable: true],
+ internal_note: [:string, nullable: true], internal_note_html: [:string, nullable: true],
metadata: 'Record<string, unknown>',
orders_count: :number,
total_spent: :string,
@@ -25,8 +25,12 @@ module Spree
user.tags.map(&:name) # not pluck as we preload tags
end
+ attribute :internal_note do |user|
+ user.respond_to?(:internal_note) ? Spree::RichTextHelper.to_plain_text(user.internal_note).presence : nil
+ end
+
attribute :internal_note_html do |user|
- user.respond_to?(:internal_note) ? user.internal_note&.body&.to_s.presence : nil
+ user.respond_to?(:internal_note) ? user.internal_note.presence : nil
end
attribute :default_billing_address_id do |user|
diff --git a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
index 0435ff6548..1a22849256 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/order_serializer.rb
@@ -24,7 +24,8 @@ module Spree
last_ip_address: [:string, nullable: true],
considered_risky: :boolean, confirmation_delivered: :boolean,
store_owner_notification_delivered: :boolean,
- internal_note: [:string, nullable: true], approver_id: [:string, nullable: true],
+ internal_note: [:string, nullable: true], internal_note_html: [:string, nullable: true],
+ approver_id: [:string, nullable: true],
canceler_id: [:string, nullable: true], created_by_id: [:string, nullable: true],
customer_id: [:string, nullable: true],
preferred_stock_location_id: [:string, nullable: true],
@@ -49,7 +50,11 @@ module Spree
end
attribute :internal_note do |order|
- order.internal_note&.to_plain_text.presence
+ Spree::RichTextHelper.to_plain_text(order.internal_note).presence
+ end
+
+ attribute :internal_note_html do |order|
+ order.internal_note.presence
end
attribute :approver_id do |order|
diff --git a/spree/api/app/serializers/spree/api/v3/category_serializer.rb b/spree/api/app/serializers/spree/api/v3/category_serializer.rb
index 2be163a511..4fe23d8b66 100644
--- a/spree/api/app/serializers/spree/api/v3/category_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/category_serializer.rb
@@ -18,11 +18,11 @@ module Spree
end
attribute :description do |category|
- category.description&.to_plain_text.to_s
+ Spree::RichTextHelper.to_plain_text(category.description)
end
attribute :description_html do |category|
- category.description&.body&.to_s.to_s
+ category.description_html
end
attribute :image_url do |category|
diff --git a/spree/api/app/serializers/spree/api/v3/collection_serializer.rb b/spree/api/app/serializers/spree/api/v3/collection_serializer.rb
index 2311d32911..bff6c49c2f 100644
--- a/spree/api/app/serializers/spree/api/v3/collection_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/collection_serializer.rb
@@ -16,11 +16,11 @@ module Spree
:meta_title, :meta_description, :meta_keywords, :products_count
attribute :description do |collection|
- collection.description&.to_plain_text.to_s
+ Spree::RichTextHelper.to_plain_text(collection.description)
end
attribute :description_html do |collection|
- collection.description&.body&.to_s.to_s
+ collection.description_html
end
attribute :image_url do |collection|
diff --git a/spree/api/app/serializers/spree/api/v3/policy_serializer.rb b/spree/api/app/serializers/spree/api/v3/policy_serializer.rb
index 77cfa252f6..3a1e19fcf9 100644
--- a/spree/api/app/serializers/spree/api/v3/policy_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/policy_serializer.rb
@@ -8,11 +8,11 @@ module Spree
attributes :name, :slug
attribute :body do |policy|
- policy.body&.to_plain_text
+ Spree::RichTextHelper.to_plain_text(policy.body)
end
attribute :body_html do |policy|
- policy.body&.body&.to_s.to_s
+ policy.body_html
end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rb
index 925e5bf597..ae095446d5 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/categories_controller_spec.rb
@@ -82,6 +82,23 @@ RSpec.describe Spree::Api::V3::Admin::CategoriesController, type: :controller do
expect(category.reload.name).to eq('Apparel')
end
+ # `description` carries HTML in and reads back as both shapes: the plain
+ # field tag-stripped, the markup under description_html.
+ it 'stores the description as HTML and reads back both shapes' do
+ patch :update, params: { id: category.prefixed_id, description: '<p>Soft <strong>cotton</strong></p>' }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['description_html']).to eq('<p>Soft <strong>cotton</strong></p>')
+ expect(json_response['description']).to eq('Soft cotton')
+ end
+
+ it 'sanitizes the description on write' do
+ patch :update, params: { id: category.prefixed_id, description: '<p>ok</p><script>alert(1)</script>' }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['description_html']).to eq('<p>ok</p>')
+ end
+
it 'purges the image when image is set to null' do
# Attach reliably persists on a factory-built category; the controller treats
# it the same as a store-owned Category (both resolve through `scope`).
diff --git a/spree/core/app/models/concerns/spree/customer_methods.rb b/spree/core/app/models/concerns/spree/customer_methods.rb
index fa90d60c57..13bf51db87 100644
--- a/spree/core/app/models/concerns/spree/customer_methods.rb
+++ b/spree/core/app/models/concerns/spree/customer_methods.rb
@@ -11,6 +11,7 @@ module Spree
include Spree::RansackableAttributes
include Spree::Searchable
include Spree::Publishable
+ include Spree::SanitizableRichText
included do
has_prefix_id :cust # Stripe: cus_
@@ -85,7 +86,8 @@ module Spree
# Attachments
#
has_one_attached :avatar, service: Spree.public_storage_service_name
- has_rich_text :internal_note
+
+ has_spree_rich_text :internal_note
#
# Attributes
diff --git a/spree/core/app/models/concerns/spree/sanitizable_rich_text.rb b/spree/core/app/models/concerns/spree/sanitizable_rich_text.rb
index a98d2b6394..8caf40f5cf 100644
--- a/spree/core/app/models/concerns/spree/sanitizable_rich_text.rb
+++ b/spree/core/app/models/concerns/spree/sanitizable_rich_text.rb
@@ -12,10 +12,35 @@ module Spree
extend ActiveSupport::Concern
class_methods do
+ # Declares a rich text attribute: sanitized on save, and readable as
+ # +field_html+ for the raw markup. This is what a model wants.
+ #
+ # has_spree_rich_text :description
+ #
+ # A translated attribute needs the same declaration on the +Translation+
+ # class, because Mobility writes bypass the parent's callbacks — but only
+ # to sanitize, since the reader belongs on the parent:
+ #
+ # self::Translation.class_eval do
+ # include Spree::SanitizableRichText
+ # sanitizes_rich_text :description
+ # end
+ #
+ # @param attributes [Array<Symbol>] rich text attribute names
+ # @return [void]
+ def has_spree_rich_text(*attributes)
+ sanitizes_rich_text(*attributes)
+ rich_text_html_reader(*attributes)
+ end
+
# Installs a +before_save+ pass sanitizing each named attribute. Only
# attributes that actually changed are rewritten, so unrelated saves
# never touch stored content.
#
+ # Prefer {#has_spree_rich_text} — reach for this alone only where the
+ # +field_html+ reader doesn't belong, i.e. on a Mobility +Translation+
+ # class or a model that serializes the value some other way.
+ #
# @param attributes [Array<Symbol>] rich text attribute names
# @return [void]
def sanitizes_rich_text(*attributes)
@@ -32,6 +57,22 @@ module Spree
end
end
end
+
+ # Defines +field_html+, the raw stored markup. The API exposes it beside
+ # the plain +field+, which serializers render as text — writes use the
+ # plain name, since the value is HTML either way.
+ #
+ # Reads through the attribute's own reader rather than +self[]+, so a
+ # translated field still goes through Mobility and resolves against the
+ # active locale.
+ #
+ # @param attributes [Array<Symbol>] rich text attribute names
+ # @return [void]
+ def rich_text_html_reader(*attributes)
+ attributes.each do |attribute|
+ define_method(:"#{attribute}_html") { public_send(attribute).to_s }
+ end
+ end
end
end
end
diff --git a/spree/core/app/models/spree/category.rb b/spree/core/app/models/spree/category.rb
index 11c3c73197..03a8abd1f2 100644
--- a/spree/core/app/models/spree/category.rb
+++ b/spree/core/app/models/spree/category.rb
@@ -17,6 +17,7 @@ module Spree
include Spree::HasCustomFields
include Spree::Metadata
include Spree::MemoizedData
+ include Spree::SanitizableRichText
MEMOIZED_METHODS = %w[cached_self_and_descendants_ids].freeze
@@ -138,9 +139,9 @@ module Spree
translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
#
- # Action Text
+ # Rich text
#
- translates :description, backend: :action_text
+ has_spree_rich_text :description
# Categories are manual only in 6.0 — rule-based (automatic) membership lives on
# Spree::Collection. The automatic/rules_match_policy/sort_order columns and the
@@ -194,6 +195,10 @@ module Spree
end
self::Translation.class_eval do
+ include Spree::SanitizableRichText
+
+ sanitizes_rich_text :description
+
before_save :set_permalink
before_save :set_pretty_name
after_save :regenerate_pretty_name_and_permalink, if: :should_regenerate_pretty_name_and_permalink?
diff --git a/spree/core/app/models/spree/collection.rb b/spree/core/app/models/spree/collection.rb
index 3d9453f10c..6b2848f1a7 100644
--- a/spree/core/app/models/spree/collection.rb
+++ b/spree/core/app/models/spree/collection.rb
@@ -26,6 +26,7 @@ module Spree
include Spree::TranslatableResourceSlug
include Spree::HasCustomFields
include Spree::Metadata
+ include Spree::SanitizableRichText
#
# Slug / permalink — FriendlyId with history (mirrors Spree::Category; flat, no hierarchy).
@@ -38,14 +39,19 @@ module Spree
friendly_id :permalink, slug_column: :permalink, use: :history
TRANSLATABLE_FIELDS = %i[name description permalink].freeze
+ RICH_TEXT_TRANSLATABLE_FIELDS = %i[description].freeze
translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
#
- # Action Text
+ # Rich text
#
- # Interim: description via ActionText (mirrors Spree::Category). 6.0-rich-text-descriptions.md
- # migrates both Category and Collection off ActionText later.
- translates :description, backend: :action_text
+ has_spree_rich_text :description
+
+ self::Translation.class_eval do
+ include Spree::SanitizableRichText
+
+ sanitizes_rich_text :description
+ end
#
# Associations
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 0a0ccb698e..ae00a54cfb 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -19,6 +19,7 @@ module Spree
extend Spree::DisplayMoney
include Spree::SingleStoreResource
+ include Spree::SanitizableRichText
include Spree::Purchase::Channel
include Spree::Purchase::Market
include Spree::Purchase::Currency
@@ -50,7 +51,8 @@ module Spree
end
has_secure_token :token, length: 35
- has_rich_text :internal_note
+
+ has_spree_rich_text :internal_note
MEMOIZED_METHODS = %w(tax_zone)
diff --git a/spree/core/app/models/spree/policy.rb b/spree/core/app/models/spree/policy.rb
index 0b44550b1a..bd5b1dfd1a 100644
--- a/spree/core/app/models/spree/policy.rb
+++ b/spree/core/app/models/spree/policy.rb
@@ -4,6 +4,7 @@ module Spree
extend FriendlyId
include Spree::TranslatableResource
+ include Spree::SanitizableRichText
UNIQUENESS_SCOPE = %i[owner_id owner_type].freeze
@@ -25,9 +26,15 @@ module Spree
translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
#
- # ActionText
+ # Rich text
#
- translates :body, backend: :action_text
+ has_spree_rich_text :body
+
+ self::Translation.class_eval do
+ include Spree::SanitizableRichText
+
+ sanitizes_rich_text :body
+ end
#
# Validations
@@ -39,8 +46,8 @@ module Spree
#
# Scopes
#
- scope :with_body, -> { joins(:rich_text_body).distinct }
- scope :without_body, -> { where.missing(:rich_text_body) }
+ scope :with_body, -> { where.not(body: [nil, '']) }
+ scope :without_body, -> { where(body: [nil, '']) }
scope :with_matching_name, ->(name_to_match) do
value = name_to_match.to_s.strip.downcase
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index 00a1bebb8c..fa8ec92f72 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -55,7 +55,7 @@ module Spree
RICH_TEXT_TRANSLATABLE_FIELDS = %i[description].freeze
translates(*TRANSLATABLE_FIELDS, column_fallback: Spree.mobility_column_fallback)
- sanitizes_rich_text :description
+ has_spree_rich_text :description
# Translated descriptions live on the Mobility translation table, so writes
# through locale accessors or +upsert_translations+ never touch the base
diff --git a/spree/core/app/models/spree/rich_text_sanitizer.rb b/spree/core/app/models/spree/rich_text_sanitizer.rb
index f018cb5a05..bd838b59da 100644
--- a/spree/core/app/models/spree/rich_text_sanitizer.rb
+++ b/spree/core/app/models/spree/rich_text_sanitizer.rb
@@ -4,35 +4,90 @@ module Spree
# Allowlist sanitizer for rich text HTML stored in plain text columns
# (e.g. +Spree::Product#description+).
#
- # The default allowlist is deliberately permissive: legacy descriptions were
- # written with TinyMCE (spans, divs, inline styles, tables, images) and must
- # survive a re-save. It still removes the dangerous surface — +script+,
- # +iframe+, event-handler attributes and +javascript:+ URLs — and Loofah
- # scrubs the contents of +style+ against its own CSS property allowlist.
+ # The allowlist is scoped to what the dashboard's editor actually emits —
+ # Tiptap StarterKit plus Link. Anything outside that set is markup no writer
+ # in Spree produces, so permitting it would only widen the attack surface
+ # (inline styles for CSS overlays, +class+ for collisions with storefront
+ # styles, +iframe+/+object+ for framed third-party content).
#
- # Merchants who embed videos can re-permit +iframe+ from an initializer:
+ # Widening it is a deliberate act, not a default: an editor gaining a node
+ # type widens the allowlist in the same change. Merchants whose legacy
+ # descriptions embed richer markup — tables, images or video +iframe+s from
+ # the pre-6.0 TinyMCE admin — can re-permit it from an initializer, and
+ # should, because content is re-sanitized on its next save:
#
- # Spree::RichTextSanitizer.allowed_tags += %w[iframe]
- # Spree::RichTextSanitizer.allowed_attributes += %w[allowfullscreen frameborder]
+ # Spree::RichTextSanitizer.allowed_tags += %w[table thead tbody tr th td img]
+ # Spree::RichTextSanitizer.allowed_attributes += %w[src alt colspan rowspan]
class RichTextSanitizer
+ # Tiptap StarterKit (paragraph, headings, hard break, horizontal rule,
+ # bold, italic, strike, underline, code, code block, blockquote, lists)
+ # plus Link. Verified against each extension's +renderHTML+.
class_attribute :allowed_tags,
- default: (Rails::HTML5::SafeListSanitizer.allowed_tags.to_a +
- %w[table thead tbody tfoot tr th td]).uniq.freeze
+ default: %w[
+ p br hr
+ h1 h2 h3 h4 h5 h6
+ strong em s u code pre
+ blockquote ul ol li a
+ ].freeze
- class_attribute :allowed_attributes,
- default: (Rails::HTML5::SafeListSanitizer.allowed_attributes.to_a +
- %w[style target rel colspan rowspan]).uniq.freeze
+ # +href+/+target+/+rel+/+title+ come from Link. +class+ is permitted only
+ # because a code block carries +language-*+ on its inner +code+ element;
+ # the class scrubber below is what keeps that from being a free-for-all.
+ class_attribute :allowed_attributes, default: %w[href target rel title class].freeze
+
+ # Classes surviving on +code+ elements. Tiptap writes +language-<name>+
+ # from its +languageClassPrefix+; nothing else in the editor emits a class,
+ # so every other value is stripped rather than trusted.
+ class_attribute :allowed_class_pattern, default: /\Alanguage-[a-z0-9+#-]+\z/i
+
+ # Elements allowed to carry a class at all. Only the code block needs one,
+ # and keeping the list tight stops +language-*+ from becoming a way to put a
+ # class on arbitrary markup.
+ class_attribute :classable_tags, default: %w[code].freeze
+
+ # Tags whose *contents* are dropped along with the tag. Stripping only the
+ # tag would leave the script body or stylesheet behind as visible text.
+ class_attribute :pruned_tags, default: %w[script style].freeze
# @param html [String, nil] rich text HTML
# @return [String, nil] HTML with disallowed tags and attributes removed, or the input unchanged when blank
def self.sanitize(html)
return html if html.blank?
- Rails::HTML5::SafeListSanitizer.new.sanitize(
- html,
- tags: allowed_tags,
- attributes: allowed_attributes
- )
+ # Both scrubbers run against a single parsed fragment. Going through
+ # SafeListSanitizer twice (once to prune, once to allowlist) would parse
+ # and re-serialize the whole document on every save.
+ fragment = Loofah.html5_fragment(html)
+ fragment.scrub!(prune_scrubber)
+ fragment.scrub!(permit_scrubber)
+ fragment.to_html
+ end
+
+ # Drops pruned elements subtree-and-all — allowlisting alone would strip the
+ # tag but leave the script body or stylesheet behind as visible text — and
+ # narrows +class+ to the code-block language hint in the same pass.
+ def self.prune_scrubber
+ tags = pruned_tags
+ classable = classable_tags
+ pattern = allowed_class_pattern
+
+ Loofah::Scrubber.new(direction: :top_down) do |node|
+ next node.remove if tags.include?(node.name)
+ next unless node.element? && node.key?('class')
+ next node.delete('class') unless classable.include?(node.name)
+
+ kept = node['class'].split.select { |name| pattern.match?(name) }
+ kept.empty? ? node.delete('class') : node['class'] = kept.join(' ')
+ end
+ end
+ private_class_method :prune_scrubber
+
+ def self.permit_scrubber
+ Rails::HTML::PermitScrubber.new.tap do |scrubber|
+ scrubber.tags = allowed_tags
+ scrubber.attributes = allowed_attributes
+ end
end
+ private_class_method :permit_scrubber
end
end
diff --git a/spree/core/app/presenters/spree/csv/product_variant_presenter.rb b/spree/core/app/presenters/spree/csv/product_variant_presenter.rb
index 25ba8d42f1..136c353400 100644
--- a/spree/core/app/presenters/spree/csv/product_variant_presenter.rb
+++ b/spree/core/app/presenters/spree/csv/product_variant_presenter.rb
@@ -83,7 +83,7 @@ module Spree
product.slug,
index.zero? ? product.status : nil,
index.zero? ? product.try(:vendor_name) : nil,
- index.zero? ? product.description&.html_safe : nil,
+ index.zero? ? product.description : nil,
index.zero? ? product.meta_title : nil,
index.zero? ? product.meta_description : nil,
index.zero? ? product.meta_keywords : nil,
diff --git a/spree/core/app/presenters/spree/data_feeds/google_presenter.rb b/spree/core/app/presenters/spree/data_feeds/google_presenter.rb
index ead6052ddd..459fee0cf2 100644
--- a/spree/core/app/presenters/spree/data_feeds/google_presenter.rb
+++ b/spree/core/app/presenters/spree/data_feeds/google_presenter.rb
@@ -71,7 +71,7 @@ module Spree
xml['g'].id variant.id
xml['g'].item_group_id product.id
xml['g'].title format_title(product, variant)
- xml['g'].description product.description || format_title(product, variant)
+ xml['g'].description plain_description(product).presence || format_title(product, variant)
xml['g'].link "#{store.storefront_url}/products/#{product.slug}"
xml['g'].image_link image_url
xml['g'].price "#{variant.amount_in(feed_currency)} #{feed_currency}"
@@ -96,6 +96,14 @@ module Spree
parent << node
end
+ # Google expects plain text in g:description, not markup. Memoized per
+ # product: this is called once per variant, and stripping the markup
+ # parses the whole description each time.
+ def plain_description(product)
+ @plain_descriptions ||= {}
+ @plain_descriptions[product.id] ||= Spree::RichTextHelper.to_plain_text(product.description)
+ end
+
def format_title(product, variant)
parts = [product.name]
variant.option_values.each do |option_value|
diff --git a/spree/core/app/presenters/spree/search_provider/product_presenter.rb b/spree/core/app/presenters/spree/search_provider/product_presenter.rb
index 847602af8c..ae05dd5dcd 100644
--- a/spree/core/app/presenters/spree/search_provider/product_presenter.rb
+++ b/spree/core/app/presenters/spree/search_provider/product_presenter.rb
@@ -57,7 +57,9 @@ module Spree
currency: currency,
# Translated fields — with fallback to default locale
name: translated(product, :name, fallback_locale),
- description: translated(product, :description, fallback_locale),
+ # Indexed as plain text — HTML tag names would otherwise become
+ # searchable tokens.
+ description: Spree::RichTextHelper.to_plain_text(translated(product, :description, fallback_locale)),
slug: translated(product, :slug, fallback_locale),
# Price in this currency
price: lowest_price(currency)&.to_f,
diff --git a/spree/core/config/initializers/mobility.rb b/spree/core/config/initializers/mobility.rb
index 5a46eae1db..4e4265af1f 100644
--- a/spree/core/config/initializers/mobility.rb
+++ b/spree/core/config/initializers/mobility.rb
@@ -1,7 +1,3 @@
-Rails.application.config.after_initialize do
- require 'mobility/action_text'
-end
-
Mobility.configure do |config|
config.plugins do
ransack
diff --git a/spree/core/db/migrate/20250120152208_add_default_locale_to_action_text_rich_texts.rb b/spree/core/db/migrate/20250120152208_add_default_locale_to_action_text_rich_texts.rb
deleted file mode 100644
index 01753bbcc0..0000000000
--- a/spree/core/db/migrate/20250120152208_add_default_locale_to_action_text_rich_texts.rb
+++ /dev/null
@@ -1,7 +0,0 @@
-class AddDefaultLocaleToActionTextRichTexts < ActiveRecord::Migration[6.1]
- def change
- if ActionText::RichText.column_defaults['locale'].nil?
- change_column_default :action_text_rich_texts, :locale, from: nil, to: :en
- end
- end
-end
diff --git a/spree/core/db/migrate/20250217171018_create_action_text_video_embeds.rb b/spree/core/db/migrate/20250217171018_create_action_text_video_embeds.rb
deleted file mode 100644
index 7a6ffb19c3..0000000000
--- a/spree/core/db/migrate/20250217171018_create_action_text_video_embeds.rb
+++ /dev/null
@@ -1,11 +0,0 @@
-class CreateActionTextVideoEmbeds < ActiveRecord::Migration[6.1]
- def change
- create_table :action_text_video_embeds, if_not_exists: true do |t|
- t.string :url, null: false
- t.string :thumbnail_url, null: false
- t.text :raw_html, null: false
-
- t.timestamps
- end
- end
-end
diff --git a/spree/core/db/migrate/20260708160054_create_spree_collections.rb b/spree/core/db/migrate/20260708160054_create_spree_collections.rb
index d0e0a5407a..1639e9d309 100644
--- a/spree/core/db/migrate/20260708160054_create_spree_collections.rb
+++ b/spree/core/db/migrate/20260708160054_create_spree_collections.rb
@@ -49,8 +49,8 @@ class CreateSpreeCollections < ActiveRecord::Migration[7.2]
add_column :spree_products, :collections_count, :integer, null: false, default: 0
# Mobility table-backend translations (mirrors spree_taxon_translations) for the
- # table-backed translatable fields. NOT ActionText-specific: the ActionText-backed
- # `description` is stored in the shared global action_text_rich_texts table.
+ # table-backed translatable fields. `description` is added here by a later
+ # migration, once collections moved off Action Text.
create_table :spree_collection_translations do |t|
t.string :name
t.string :permalink
diff --git a/spree/core/db/migrate/20260809200001_add_rich_text_columns_for_action_text_removal.rb b/spree/core/db/migrate/20260809200001_add_rich_text_columns_for_action_text_removal.rb
new file mode 100644
index 0000000000..221fe41620
--- /dev/null
+++ b/spree/core/db/migrate/20260809200001_add_rich_text_columns_for_action_text_removal.rb
@@ -0,0 +1,11 @@
+class AddRichTextColumnsForActionTextRemoval < ActiveRecord::Migration[8.1]
+ def change
+ add_column :spree_collections, :description, :text, if_not_exists: true
+ add_column :spree_collection_translations, :description, :text, if_not_exists: true
+
+ add_column :spree_policies, :body, :text, if_not_exists: true
+ add_column :spree_policy_translations, :body, :text, if_not_exists: true
+
+ add_column :spree_customers, :internal_note, :text, if_not_exists: true
+ end
+end
diff --git a/spree/core/lib/generators/spree/model/templates/model.rb.tt b/spree/core/lib/generators/spree/model/templates/model.rb.tt
index 877c1c7680..cd82eaca47 100644
--- a/spree/core/lib/generators/spree/model/templates/model.rb.tt
+++ b/spree/core/lib/generators/spree/model/templates/model.rb.tt
@@ -18,8 +18,12 @@ module Spree
belongs_to :<%= attribute.name %>, class_name: <%= belongs_to_class_name_expr(attribute) %>
<% end -%>
<% end -%>
+<% if attributes.any?(&:rich_text?) -%>
+ include Spree::SanitizableRichText
+
<% attributes.select(&:rich_text?).each do |attribute| -%>
- has_rich_text :<%= attribute.name %>
+ has_spree_rich_text :<%= attribute.name %>
+<% end -%>
<% end -%>
<% attributes.select(&:attachment?).each do |attribute| -%>
has_one_attached :<%= attribute.name %>
diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rb
index 1ad7ee370b..a760f44d03 100644
--- a/spree/core/lib/spree/core.rb
+++ b/spree/core/lib/spree/core.rb
@@ -5,8 +5,6 @@ require 'active_job/railtie'
require 'active_model/railtie'
require 'active_record/railtie'
require 'active_storage/engine'
-require 'action_text/engine'
-require 'action_cable/engine'
require 'pagy'
require 'mail'
diff --git a/spree/core/lib/spree/testing_support/action_text.rb b/spree/core/lib/spree/testing_support/action_text.rb
new file mode 100644
index 0000000000..4161c4a269
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/action_text.rb
@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Spree 6.0 stores rich text in its own columns and neither loads Action Text
+# nor creates its tables. The upgrade tasks still read
+# +action_text_rich_texts+ to copy legacy content out of it, so specs covering
+# those tasks have to stand the pre-upgrade table up themselves.
+#
+# RSpec.describe '...' do
+# include_context 'with legacy Action Text'
+# end
+RSpec.shared_context 'with legacy Action Text' do
+ before(:all) do
+ require 'action_text/engine'
+
+ connection = ActiveRecord::Base.connection
+ unless connection.table_exists?(:action_text_rich_texts)
+ connection.create_table :action_text_rich_texts do |t|
+ t.string :name, null: false
+ t.text :body
+ t.string :record_type, null: false
+ t.bigint :record_id, null: false
+ t.string :locale, null: false, default: 'en'
+ t.timestamps
+ end
+ end
+
+ ActionText::RichText.reset_column_information
+ end
+
+ after(:all) do
+ ActiveRecord::Base.connection.drop_table(:action_text_rich_texts, if_exists: true)
+ end
+end
diff --git a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
index d94679267f..d86a1492dc 100644
--- a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
+++ b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
@@ -96,6 +96,27 @@ steps:
manually once the migration is verified. Override the source with
SOURCE_USER_TABLE / SOURCE_USER_TYPE and batch size with BATCH_SIZE.
+ - id: migrate_rich_text_to_columns
+ name: "Move rich text out of Action Text into its own columns"
+ task: "spree:migrate_rich_text_to_columns"
+ notes: |
+ Copies category and collection descriptions, policy bodies, and the order
+ and customer internal notes out of action_text_rich_texts into the text
+ columns that own them in 6.0. Content is sanitized on the way in and
+ per-locale rows land in the model's translation table.
+
+ Ordering is load-bearing in both directions. Run AFTER
+ migrate_taxons_to_categories_and_collections, which retypes the Action Text
+ rows from 'Spree::Taxon' to 'Spree::Category' so they stay findable. Run
+ AFTER migrate_users_to_customers too: a note is copied onto the customer
+ row it belongs to, and those rows do not exist until that step populates
+ spree_customers — running earlier would count every legacy customer note as
+ orphaned and skip it for good.
+
+ Only copies where an Action Text row exists, so content already in the
+ column is never overwritten. Source rows are left in place as the rollback
+ path and are dropped with the Action Text tables in 6.1. Idempotent.
+
- id: migrate_shipping_to_delivery
name: "Backfill fulfillment & delivery naming"
task: "spree:migrate_shipping_to_delivery"
diff --git a/spree/core/lib/tasks/migrate_rich_text_to_columns.rake b/spree/core/lib/tasks/migrate_rich_text_to_columns.rake
new file mode 100644
index 0000000000..ea62589ff2
--- /dev/null
+++ b/spree/core/lib/tasks/migrate_rich_text_to_columns.rake
@@ -0,0 +1,128 @@
+namespace :spree do
+ desc <<~DESC
+ Copies rich text out of Action Text into the plain text columns that own it
+ in Spree 6.0 — category and collection descriptions, policy bodies, and the
+ order and customer internal notes.
+
+ Run through +spree:upgrade+. Two steps must come first:
+
+ - spree:migrate_taxons_to_categories_and_collections, which retypes the
+ Action Text rows from Spree::Taxon to Spree::Category so they stay
+ findable here.
+ - spree:upgrade:migrate_users_to_customers, which populates spree_customers.
+ A note is copied onto the customer row it belongs to, so running before
+ those rows exist would count every legacy customer note as orphaned and
+ skip it permanently.
+
+ Only copies where an Action Text row exists, so a description already living
+ in the column is never overwritten with a blank. Per-locale rows land in the
+ model's translation table. Content is sanitized on the way in, through the
+ same allowlist as any other write.
+
+ Idempotent — a row whose column already matches the sanitized Action Text
+ body is skipped, and writes go through +update_all+ so timestamps and
+ webhooks don't churn. Source rows are left in place as the rollback path and
+ are dropped with the Action Text tables in 6.1.
+ DESC
+ task migrate_rich_text_to_columns: :environment do
+ # Action Text is not loaded by Spree any more — 6.0 stores rich text in its
+ # own columns. It ships with Rails, so this one-off copy pulls it in itself
+ # rather than making every app carry the engine for a task it runs once.
+ loaded = begin
+ require 'action_text/engine'
+ ActionText::RichText.table_exists?
+ rescue LoadError, NameError, ActiveRecord::StatementInvalid
+ false
+ end
+
+ unless loaded
+ puts ' No action_text_rich_texts table — nothing to migrate.'
+ next
+ end
+
+ # Each entry maps an Action Text attachment to the column that now owns it.
+ # +translation_class+ is nil for models whose field isn't translated.
+ #
+ # +record_types+ lists the class names to match in action_text_rich_texts.
+ # migrate_users_to_customers retypes those rows; matching the legacy name as
+ # well covers an install that ran an earlier build of that task, before it
+ # retyped them. It does NOT make this step safe to run first — see above.
+ targets = [
+ { model: Spree::Category, translation_class: Spree::Category::Translation, name: 'description', column: :description },
+ { model: Spree::Collection, translation_class: Spree::Collection::Translation, name: 'description', column: :description },
+ { model: Spree::Policy, translation_class: Spree::Policy::Translation, name: 'body', column: :body },
+ { model: Spree::Order, translation_class: nil, name: 'internal_note', column: :internal_note },
+ {
+ model: Spree.customer_class, translation_class: nil, name: 'internal_note', column: :internal_note,
+ record_types: [Spree.customer_class(constantize: false), ENV.fetch('SOURCE_USER_TYPE', 'Spree::User')].compact.uniq
+ }
+ ]
+
+ default_locale = I18n.default_locale.to_s
+
+ # Writes only when the target still holds the value that was read, so an
+ # edit landing between read and write is never clobbered. Selecting the id
+ # alongside the column distinguishes a missing row from a NULL column, so
+ # this doubles as the orphan check.
+ copy = lambda do |relation, id, column, html|
+ found = relation.where(id: id).pick(:id, column)
+ next :missing if found.nil?
+
+ current = found.last
+ sanitized = Spree::RichTextSanitizer.sanitize(html)
+ next false if current == sanitized
+
+ relation.where(id: id, column => current).update_all(column => sanitized).positive?
+ end
+
+ targets.each do |target|
+ model = target[:model]
+ next if model.nil? || !model.table_exists?
+
+ column = target[:column]
+ next unless model.column_names.include?(column.to_s)
+
+ base = model.unscoped
+ copied = 0
+ translated = 0
+ missing = 0
+
+ translation_class = target[:translation_class]
+ # Mobility names the join column after the model (spree_category_id);
+ # read it off the association rather than rebuilding it by hand.
+ foreign_key = translation_class&.reflect_on_association(:translated_model)&.foreign_key
+
+ record_types = target[:record_types] || [model.name]
+ rows = ActionText::RichText.where(record_type: record_types, name: target[:name]).where.not(body: [nil, ''])
+
+ rows.find_each do |row|
+ # Read the stored column, not +body.to_s+ — the Action Text renderer
+ # wraps output in <div class="trix-content">, and migrating that wrapper
+ # would carry Trix's presentation into every column.
+ html = row.read_attribute_before_type_cast('body').to_s
+ locale = row.locale.presence || default_locale
+
+ if locale == default_locale
+ case copy.call(base, row.record_id, column, html)
+ when :missing then missing += 1
+ when true then copied += 1
+ end
+ next
+ end
+
+ next if translation_class.nil?
+
+ translation = translation_class.find_or_initialize_by(foreign_key => row.record_id, locale: locale)
+ # Create the row empty, then let the one +copy+ path fill it, so both
+ # branches share a single sanitize and a single write mechanism.
+ translation.save(validate: false) if translation.new_record?
+
+ translated += 1 if copy.call(translation_class, translation.id, column, html) == true
+ end
+
+ puts " #{model.name}: copied #{copied} #{column}(s)."
+ puts " #{model.name}: copied #{translated} translated #{column}(s)." if translated.positive?
+ puts " #{model.name}: skipped #{missing} orphaned row(s)." if missing.positive?
+ end
+ end
+end
diff --git a/spree/core/lib/tasks/migrate_users_to_customers.rake b/spree/core/lib/tasks/migrate_users_to_customers.rake
index b0bdfdbdca..fda040faed 100644
--- a/spree/core/lib/tasks/migrate_users_to_customers.rake
+++ b/spree/core/lib/tasks/migrate_users_to_customers.rake
@@ -127,7 +127,15 @@ namespace :spree do
user_identities: Spree::UserIdentity.where(user_type: old_type).update_all(user_type: new_type),
customer_group_users: Spree::CustomerGroupUser.where(customer_type: old_type).update_all(customer_type: new_type),
api_keys_created_by: Spree::ApiKey.where(created_by_type: old_type).update_all(created_by_type: new_type),
- api_keys_revoked_by: Spree::ApiKey.where(revoked_by_type: old_type).update_all(revoked_by_type: new_type)
+ api_keys_revoked_by: Spree::ApiKey.where(revoked_by_type: old_type).update_all(revoked_by_type: new_type),
+ # Internal notes, so migrate_rich_text_to_columns can find them under
+ # the new class name whichever order the two steps run in. Action Text
+ # is optional, hence the defined? guard.
+ rich_texts: if defined?(ActionText::RichText) && ActionText::RichText.table_exists?
+ ActionText::RichText.where(record_type: old_type).update_all(record_type: new_type)
+ else
+ 0
+ end
}
# Admins stay in spree_admin_users (in place) — backfill the digest from
diff --git a/spree/core/spec/db/migrate/rename_metafields_to_custom_fields_spec.rb b/spree/core/spec/db/migrate/rename_metafields_to_custom_fields_spec.rb
index 615fc6d127..8689634d26 100644
--- a/spree/core/spec/db/migrate/rename_metafields_to_custom_fields_spec.rb
+++ b/spree/core/spec/db/migrate/rename_metafields_to_custom_fields_spec.rb
@@ -4,6 +4,8 @@ require 'spec_helper'
# bodies out of Action Text. All of it is data no model can reach once the
# classes are renamed, so it is covered here rather than through a model.
RSpec.describe 'RenameMetafieldsToCustomFields migration' do
+ include_context 'with legacy Action Text'
+
let(:migration) do
require Spree::Core::Engine.root.join('db', 'migrate', '20260809000001_rename_metafields_to_custom_fields.rb')
RenameMetafieldsToCustomFields.new
diff --git a/spree/core/spec/lib/tasks/categories_and_collections_spec.rb b/spree/core/spec/lib/tasks/categories_and_collections_spec.rb
index bd0eed8a44..41e00a3e61 100644
--- a/spree/core/spec/lib/tasks/categories_and_collections_spec.rb
+++ b/spree/core/spec/lib/tasks/categories_and_collections_spec.rb
@@ -2,6 +2,8 @@ require 'spec_helper'
require 'rake'
describe 'spree:migrate_taxons_to_categories_and_collections' do
+ include_context 'with legacy Action Text'
+
subject { Rake::Task[task_name] }
let(:task_name) { 'spree:migrate_taxons_to_categories_and_collections' }
@@ -99,16 +101,25 @@ describe 'spree:migrate_taxons_to_categories_and_collections' do
let(:taxonomy) { create(:taxonomy, store: store) }
let!(:category) do
create(:category, taxonomy: taxonomy, store: store, parent: taxonomy.root).tap do |c|
- c.update!(description: '<div>Kept description</div>')
- # simulate a pre-6.0 row still typed as Spree::Taxon
- ActionText::RichText.where(record_id: c.id, name: 'description').update_all(record_type: 'Spree::Taxon')
+ # A pre-6.0 install holds the description in an Action Text row typed as
+ # Spree::Taxon. Categories store description in their own column now, so
+ # the legacy row is written directly rather than through the model.
+ ActionText::RichText.create!(
+ name: 'description', body: '<div>Kept description</div>',
+ record_type: 'Spree::Taxon', record_id: c.id
+ )
end
end
+ # The rows themselves are copied into the description column later, by
+ # spree:migrate_rich_text_to_columns — this task only has to retype them so
+ # that copy can still find them after the rename.
it 'backfills record_type so the rich-text description survives the rename' do
subject.invoke
- expect(category.reload.description.to_plain_text).to eq('Kept description')
+ row = ActionText::RichText.find_by(record_id: category.id, name: 'description')
+ expect(row.record_type).to eq('Spree::Category')
+ expect(row.body.to_plain_text).to eq('Kept description')
end
end
diff --git a/spree/core/spec/lib/tasks/migrate_rich_text_to_columns_spec.rb b/spree/core/spec/lib/tasks/migrate_rich_text_to_columns_spec.rb
new file mode 100644
index 0000000000..e07aee1242
--- /dev/null
+++ b/spree/core/spec/lib/tasks/migrate_rich_text_to_columns_spec.rb
@@ -0,0 +1,136 @@
+require 'spec_helper'
+require 'rake'
+
+describe 'spree:migrate_rich_text_to_columns' do
+ subject { Rake::Task[task_name] }
+
+ let(:task_name) { 'spree:migrate_rich_text_to_columns' }
+
+ include_context 'with legacy Action Text'
+
+ before(:all) do
+ Rake::Task.define_task(:environment)
+ load Spree::Core::Engine.root.join('lib', 'tasks', 'migrate_rich_text_to_columns.rake')
+ end
+
+ before { subject.reenable }
+
+ let(:store) { Spree::Store.default || create(:store) }
+
+ # Pre-6.0 rows live in Action Text, so they're written directly — the models
+ # store rich text in their own columns now and no longer create these.
+ def legacy_rich_text(record, name, body, locale: nil)
+ ActionText::RichText.create!(
+ name: name, body: body, record_type: record.class.name, record_id: record.id,
+ **(locale ? { locale: locale } : {})
+ )
+ end
+
+ describe 'category descriptions' do
+ let!(:category) { create(:category, store: store) }
+
+ it 'copies the body into the description column' do
+ legacy_rich_text(category, 'description', '<p>Legacy <strong>copy</strong></p>')
+
+ subject.invoke
+
+ expect(category.reload.description).to eq('<p>Legacy <strong>copy</strong></p>')
+ end
+
+ it 'sanitizes on the way in' do
+ legacy_rich_text(category, 'description', '<p>ok</p><script>alert(1)</script>')
+
+ subject.invoke
+
+ expect(category.reload.description).to eq('<p>ok</p>')
+ end
+
+ it 'leaves a description already in the column alone when no Action Text row exists' do
+ category.update!(description: '<p>Already migrated</p>')
+
+ subject.invoke
+
+ expect(category.reload.description).to eq('<p>Already migrated</p>')
+ end
+
+ it 'routes a non-default locale row to the translation table' do
+ store.update!(supported_locales: 'en,fr')
+ legacy_rich_text(category, 'description', '<p>Bonjour</p>', locale: 'fr')
+
+ subject.invoke
+
+ translation = category.translations.find_by(locale: 'fr')
+ expect(translation.description).to eq('<p>Bonjour</p>')
+ end
+
+ it 'is idempotent' do
+ legacy_rich_text(category, 'description', '<p>Once</p>')
+ subject.invoke
+ subject.reenable
+
+ expect { subject.invoke }.not_to change { category.reload.updated_at }
+ expect(category.reload.description).to eq('<p>Once</p>')
+ end
+
+ it 'skips an Action Text row whose record no longer exists' do
+ legacy_rich_text(category, 'description', '<p>Orphan</p>')
+ category.really_destroy! if category.respond_to?(:really_destroy!)
+
+ expect { subject.invoke }.not_to raise_error
+ end
+ end
+
+ describe 'policy bodies' do
+ let!(:policy) { create(:policy, owner: store) }
+
+ it 'copies the body into the body column' do
+ legacy_rich_text(policy, 'body', '<p>Terms</p>')
+
+ subject.invoke
+
+ expect(policy.reload.body).to eq('<p>Terms</p>')
+ end
+ end
+
+ describe 'order internal notes' do
+ let!(:order) { create(:order, store: store) }
+
+ it 'copies the note into the internal_note column' do
+ legacy_rich_text(order, 'internal_note', '<p>Called the customer</p>')
+
+ subject.invoke
+
+ expect(order.reload.internal_note).to eq('<p>Called the customer</p>')
+ end
+ end
+
+ describe 'customer internal notes' do
+ let!(:customer) { create(:user) }
+
+ it 'copies the note into the internal_note column' do
+ legacy_rich_text(customer, 'internal_note', '<p>VIP</p>')
+
+ subject.invoke
+
+ expect(customer.reload.internal_note).to eq('<p>VIP</p>')
+ end
+
+ # migrate_users_to_customers leaves action_text_rich_texts alone, so rows
+ # written before that step are still typed as the pre-6.0 user class.
+ it 'finds a note still typed under the legacy user class' do
+ # Inserted directly: Spree::User is gone in 6.0, so Action Text can't
+ # resolve the polymorphic owner well enough to build the record.
+ ActionText::RichText.insert!(
+ {
+ name: 'internal_note', body: '<p>Legacy type</p>', locale: 'en',
+ record_type: 'Spree::User', record_id: customer.id,
+ created_at: Time.current, updated_at: Time.current
+ }
+ )
+
+ subject.invoke
+
+ expect(customer.reload.internal_note).to eq('<p>Legacy type</p>')
+ end
+ end
+end
diff --git a/spree/core/spec/lib/tasks/migrate_users_to_customers_spec.rb b/spree/core/spec/lib/tasks/migrate_users_to_customers_spec.rb
index 2386a54dc9..aae3264b72 100644
--- a/spree/core/spec/lib/tasks/migrate_users_to_customers_spec.rb
+++ b/spree/core/spec/lib/tasks/migrate_users_to_customers_spec.rb
@@ -2,6 +2,8 @@ require 'spec_helper'
require 'rake'
describe 'spree:upgrade:migrate_users_to_customers' do
+ include_context 'with legacy Action Text'
+
subject { Rake::Task[task_name] }
let(:task_name) { 'spree:upgrade:migrate_users_to_customers' }
@@ -144,6 +146,23 @@ describe 'spree:upgrade:migrate_users_to_customers' do
expect(group_membership.reload.customer_type).to eq('Spree::Customer')
end
+ # Internal notes, so spree:migrate_rich_text_to_columns finds them under the
+ # new class name. Inserted directly — Spree::User is gone in 6.0, so Action
+ # Text cannot resolve the polymorphic owner.
+ it 'flips internal-note Action Text rows to Spree::Customer' do
+ ActionText::RichText.insert!(
+ {
+ name: 'internal_note', body: '<p>VIP</p>', locale: 'en',
+ record_type: 'Spree::User', record_id: 1,
+ created_at: Time.current, updated_at: Time.current
+ }
+ )
+
+ subject.invoke
+
+ expect(ActionText::RichText.where(name: 'internal_note').pick(:record_type)).to eq('Spree::Customer')
+ end
+
it 'leaves admin references untouched' do
admin_token = create(:refresh_token, :for_admin)
diff --git a/spree/core/spec/models/spree/category_spec.rb b/spree/core/spec/models/spree/category_spec.rb
index dec11edded..09245ca115 100644
--- a/spree/core/spec/models/spree/category_spec.rb
+++ b/spree/core/spec/models/spree/category_spec.rb
@@ -354,7 +354,7 @@ RSpec.describe Spree::Category, type: :model do
expect(category_pl_translation.name).to eq('PL name')
expect(category_pl_translation.permalink).to eq('pl-parent/pl-name')
- expect(category.description_pl.to_plain_text).to eq('PL description')
+ expect(category.description_pl).to eq('PL description')
end
end
diff --git a/spree/core/spec/models/spree/collection_spec.rb b/spree/core/spec/models/spree/collection_spec.rb
index 838afa8fdd..5fe15e722a 100644
--- a/spree/core/spec/models/spree/collection_spec.rb
+++ b/spree/core/spec/models/spree/collection_spec.rb
@@ -86,11 +86,18 @@ RSpec.describe Spree::Collection, type: :model do
end
end
- describe 'description (ActionText)' do
+ describe 'description' do
it 'round-trips rich text' do
collection = create(:collection, description: '<p>Hello <strong>world</strong></p>')
- expect(collection.reload.description.to_plain_text).to eq('Hello world')
+ expect(collection.reload.description).to eq('<p>Hello <strong>world</strong></p>')
+ expect(Spree::RichTextHelper.to_plain_text(collection.description)).to eq('Hello world')
+ end
+
+ it 'sanitizes on write' do
+ collection = create(:collection, description: '<p>ok</p><script>alert(1)</script>')
+
+ expect(collection.reload.description).to eq('<p>ok</p>')
end
end
diff --git a/spree/core/spec/models/spree/policy_spec.rb b/spree/core/spec/models/spree/policy_spec.rb
index fb9301b093..2712425e78 100644
--- a/spree/core/spec/models/spree/policy_spec.rb
+++ b/spree/core/spec/models/spree/policy_spec.rb
@@ -66,7 +66,7 @@ RSpec.describe Spree::Policy, type: :model do
expect(policy.name).to eq('Privacy Policy')
I18n.with_locale(:es) do
expect(policy.name).to eq('Política de Privacidad')
- expect(policy.body.to_plain_text).to eq('Política de Privacidad')
+ expect(policy.body).to eq('Política de Privacidad')
end
end
@@ -92,6 +92,22 @@ RSpec.describe Spree::Policy, type: :model do
end
describe 'Scopes' do
+ # These read the body column directly since 6.0 — they used to join the
+ # Action Text association, so the rewrite needs its own coverage.
+ describe '.with_body / .without_body' do
+ let!(:with_body) { create(:policy, owner: store, body: '<p>Terms</p>') }
+ let!(:blank_body) { create(:policy, owner: store, body: '') }
+ let!(:nil_body) { create(:policy, owner: store, body: nil) }
+
+ # Scoped to these ids — the seeded store ships policies of its own.
+ let(:ids) { [with_body.id, blank_body.id, nil_body.id] }
+
+ it 'partitions policies on whether the body holds content' do
+ expect(described_class.where(id: ids).with_body).to contain_exactly(with_body)
+ expect(described_class.where(id: ids).without_body).to contain_exactly(blank_body, nil_body)
+ end
+ end
+
describe '.for_store' do
let(:other_store) { create(:store) }
let!(:store1_policy) { create(:policy, owner: store) }
diff --git a/spree/core/spec/models/spree/rich_text_sanitizer_spec.rb b/spree/core/spec/models/spree/rich_text_sanitizer_spec.rb
index 1681fca336..b404b09b57 100644
--- a/spree/core/spec/models/spree/rich_text_sanitizer_spec.rb
+++ b/spree/core/spec/models/spree/rich_text_sanitizer_spec.rb
@@ -4,18 +4,46 @@ describe Spree::RichTextSanitizer do
subject { described_class.sanitize(html) }
describe '.sanitize' do
+ # The allowlist is scoped to what the dashboard's Tiptap editor emits, so
+ # its own output has to survive untouched — a sanitizer that rewrites the
+ # editor's markup would corrupt content on every save.
+ context 'with editor output' do
+ {
+ 'paragraphs and marks' => '<p>a <strong>b</strong> <em>c</em> <s>d</s> <u>e</u> <code>f</code></p>',
+ 'headings' => '<h1>1</h1><h2>2</h2><h3>3</h3><h4>4</h4><h5>5</h5><h6>6</h6>',
+ 'lists' => '<ul><li><p>a</p></li></ul><ol><li><p>b</p></li></ol>',
+ 'blockquote' => '<blockquote><p>q</p></blockquote>',
+ 'code block' => '<pre><code>x = 1</code></pre>',
+ 'code block with a language' => '<pre><code class="language-ruby">x = 1</code></pre>',
+ 'rules and hard breaks' => '<hr><p>a<br>b</p>',
+ 'links' => '<p><a href="https://example.com" target="_blank" rel="noopener" title="t">l</a></p>'
+ }.each do |description, markup|
+ context "with #{description}" do
+ let(:html) { markup }
+
+ it { is_expected.to eq(markup) }
+ end
+ end
+ end
+
context 'with a script tag' do
let(:html) { '<p>safe</p><script>alert(1)</script>' }
- it { is_expected.not_to include('<script') }
- it { is_expected.to include('<p>safe</p>') }
+ it { is_expected.to eq('<p>safe</p>') }
+ end
+
+ context 'with a style tag' do
+ let(:html) { '<p>safe</p><style>body { color: red }</style>' }
+
+ it 'drops the stylesheet rather than leaving it as visible text' do
+ expect(subject).to eq('<p>safe</p>')
+ end
end
context 'with event handler attributes' do
- let(:html) { '<img src="a.png" onerror="steal()"><div onclick="steal()">x</div>' }
+ let(:html) { '<p onclick="steal()">x</p>' }
- it { is_expected.not_to include('onerror') }
- it { is_expected.not_to include('onclick') }
+ it { is_expected.to eq('<p>x</p>') }
end
context 'with a javascript: URL' do
@@ -24,22 +52,64 @@ describe Spree::RichTextSanitizer do
it { is_expected.not_to include('javascript:') }
end
- context 'with a link' do
- let(:html) { '<a href="https://example.com" target="_blank" rel="noopener">x</a>' }
+ context 'with inline styles' do
+ let(:html) { '<p style="position: fixed; top: 0">overlay</p>' }
+
+ it 'drops style entirely — the editor emits none, and it enables overlays' do
+ expect(subject).to eq('<p>overlay</p>')
+ end
+ end
+
+ context 'with a class the editor never emits' do
+ let(:html) { '<p class="storefront-checkout-button">x</p>' }
+
+ it { is_expected.to eq('<p>x</p>') }
+ end
+
+ context 'with an extra class alongside a code language' do
+ let(:html) { '<pre><code class="language-ruby injected">x</code></pre>' }
- it { is_expected.to eq(html) }
+ it 'keeps the language hint and drops the rest' do
+ expect(subject).to eq('<pre><code class="language-ruby">x</code></pre>')
+ end
+ end
+
+ # The language hint is a code-block concern, so it must not double as a way
+ # to put a class on arbitrary markup.
+ context 'with a language class on something other than code' do
+ let(:html) { '<p class="language-ruby">x</p><a href="/y" class="language-js">z</a>' }
+
+ it { is_expected.to eq('<p>x</p><a href="/y">z</a>') }
end
- context 'with table markup' do
- let(:html) { '<table><thead><tr><th colspan="2">h</th></tr></thead><tbody><tr><td rowspan="2">c</td></tr></tbody></table>' }
+ # Legacy TinyMCE descriptions carry markup the Tiptap set has no node for.
+ # Formatting is lost on the next save, but the words are not.
+ context 'with legacy markup outside the editor set' do
+ let(:html) { '<div><span>kept</span></div><table><tr><td>cell</td></tr></table>' }
- it { is_expected.to eq(html) }
+ it 'unwraps the tags and preserves the text' do
+ expect(subject).to eq('keptcell')
+ end
end
context 'with an image' do
- let(:html) { '<img src="https://example.com/a.png" alt="a" width="10" height="20">' }
+ let(:html) { '<p>a</p><img src="https://example.com/a.png" alt="a">' }
+
+ it { is_expected.to eq('<p>a</p>') }
+
+ context 'when img is added to the allowlist' do
+ around do |example|
+ original_tags = described_class.allowed_tags
+ original_attributes = described_class.allowed_attributes
+ described_class.allowed_tags = original_tags + %w[img]
+ described_class.allowed_attributes = original_attributes + %w[src alt]
+ example.run
+ described_class.allowed_tags = original_tags
+ described_class.allowed_attributes = original_attributes
+ end
- it { is_expected.to include('src="https://example.com/a.png"', 'alt="a"', 'width="10"', 'height="20"') }
+ it { is_expected.to include('src="https://example.com/a.png"', 'alt="a"') }
+ end
end
context 'with an iframe' do
@@ -59,15 +129,6 @@ describe Spree::RichTextSanitizer do
end
end
- context 'with inline styles' do
- let(:html) { '<p style="color: red; position: fixed">x</p>' }
-
- it 'keeps allowed CSS properties and drops the rest' do
- expect(subject).to include('color:red')
- expect(subject).not_to include('position')
- end
- end
-
context 'when blank' do
it { expect(described_class.sanitize(nil)).to be_nil }
it { expect(described_class.sanitize('')).to eq('') }
diff --git a/spree/core/spec/models/spree/sanitizable_rich_text_spec.rb b/spree/core/spec/models/spree/sanitizable_rich_text_spec.rb
index ce136902bd..996fdc0360 100644
--- a/spree/core/spec/models/spree/sanitizable_rich_text_spec.rb
+++ b/spree/core/spec/models/spree/sanitizable_rich_text_spec.rb
@@ -26,4 +26,22 @@ describe Spree::SanitizableRichText do
expect(product.reload.get_field_with_locale(:fr, :description)).not_to include('<script')
end
+
+ describe '.has_spree_rich_text' do
+ it 'exposes the stored markup as field_html' do
+ product.update!(description: '<p>Soft <strong>cotton</strong></p>')
+
+ expect(product.reload.description_html).to eq('<p>Soft <strong>cotton</strong></p>')
+ end
+
+ it 'reads an empty string rather than nil when unset' do
+ expect(create(:product, store: store, description: nil).description_html).to eq('')
+ end
+
+ # There is one way to write rich text: the plain attribute. A second setter
+ # would be a second spelling of the same thing.
+ it 'defines no field_html writer' do
+ expect(product).not_to respond_to(:description_html=)
+ end
+ end
end
diff --git a/spree/core/spec/presenters/spree/data_feeds/google_presenter_spec.rb b/spree/core/spec/presenters/spree/data_feeds/google_presenter_spec.rb
index 03736127fa..5244d21699 100644
--- a/spree/core/spec/presenters/spree/data_feeds/google_presenter_spec.rb
+++ b/spree/core/spec/presenters/spree/data_feeds/google_presenter_spec.rb
@@ -39,7 +39,14 @@ RSpec.describe Spree::DataFeeds::GooglePresenter do
end
it 'includes description' do
- expect(xml).to include("<g:description>#{product.description}</g:description>")
+ expect(xml).to include("<g:description>#{Spree::RichTextHelper.to_plain_text(product.description)}</g:description>")
+ end
+
+ it 'strips markup from the description, since Google expects plain text' do
+ product.update!(description: '<p>Soft cotton.</p><p>Machine <strong>washable</strong>.</p>')
+
+ expect(xml).to include('<g:description>Soft cotton.
+Machine washable.</g:description>')
end
it 'includes link' do
diff --git a/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb b/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb
index ddcc5439a5..0f080ca8bf 100644
--- a/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb
+++ b/spree/core/spec/services/spree/imports/row_processors/product_variant_spec.rb
@@ -60,6 +60,15 @@ RSpec.describe Spree::Imports::RowProcessors::ProductVariant, type: :service do
expect { subject.process! }.to have_enqueued_job(Spree::Imports::AssignTagsJob).with(anything, 'ECO, Gold')
end
+ # The description column holds HTML: the cell is stored as-is, sanitized.
+ it 'sanitizes the description cell' do
+ row_data['description'] = '<p>Soft cotton</p><script>alert(1)</script>'
+
+ subject.process!
+
+ expect(Spree::Product.find_by(slug: 'denim-shirt').description).to eq('<p>Soft cotton</p>')
+ end
+
it 'does not touch the store when associating the product' do
expect { subject.process! }.not_to change { store.reload.updated_at }
end
diff --git a/spree/core/spec/spec_helper.rb b/spree/core/spec/spec_helper.rb
index d13f84d5a8..acfcc2d0ec 100644
--- a/spree/core/spec/spec_helper.rb
+++ b/spree/core/spec/spec_helper.rb
@@ -55,6 +55,7 @@ Dir['./spec/support/**/*.rb'].sort.each { |f| require f }
require 'spree/testing_support/i18n' if ENV['CHECK_TRANSLATIONS']
+require 'spree/testing_support/action_text'
require 'spree/testing_support/factories'
require 'spree/testing_support/jobs'
require 'spree/testing_support/store'
diff --git a/spree/core/spree_core.gemspec b/spree/core/spree_core.gemspec
index dcc98b4e2c..28b0889761 100644
--- a/spree/core/spree_core.gemspec
+++ b/spree/core/spree_core.gemspec
@@ -48,6 +48,7 @@ Gem::Specification.new do |s|
s.add_dependency 'nokogiri', '~> 1.18'
s.add_dependency 'ostruct'
s.add_dependency 'paranoia', '>= 2.4'
+ s.add_dependency 'loofah', '~> 2.21'
s.add_dependency 'rails-html-sanitizer', '~> 1.6'
s.add_dependency 'ransack', '>= 4.1'
s.add_dependency 'request_store', '~> 1.5'
@@ -62,7 +63,6 @@ Gem::Specification.new do |s|
s.add_dependency 'active_storage_validations', '>= 1.3', '< 4'
s.add_dependency 'mobility', '~> 1.3', '>= 1.3.2'
s.add_dependency 'mobility-ransack', '~> 1.2'
- s.add_dependency 'mobility-actiontext', '~> 1.1'
s.add_dependency 'friendly_id-mobility', '~> 1.0'
s.add_dependency 'wannabe_bool'
s.add_dependency 'safely_block', '>= 0.4', '< 2.0'
diff --git a/spree/lib/generators/spree/install/install_generator.rb b/spree/lib/generators/spree/install/install_generator.rb
index c1a2068a47..2d23557c54 100644
--- a/spree/lib/generators/spree/install/install_generator.rb
+++ b/spree/lib/generators/spree/install/install_generator.rb
@@ -74,7 +74,6 @@ module Spree
say_status :copying, 'migrations'
silence_stream(STDOUT) do
silence_warnings { rake 'active_storage:install:migrations' }
- silence_warnings { rake 'action_text:install:migrations' }
silence_warnings { rake 'spree:install:migrations' }
end
end