Skip to content

armgit / spree

Public Imported from GitHub
0

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

Add resource translations management to Admin API and dashboard (#14226)

Damian Legawiecd0d56c47a70a
diff --git a/CLAUDE.md b/CLAUDE.md
index 8c925e2f8e..ae1af832e8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,6 +40,7 @@ Multi-version plans (some phases shipped, some pending):
- `6.0-channels-catalogs-b2b.md` — Channel + ProductPublication (replaces StoreProduct) + single-owner Product (`belongs_to :store`) + Publishing card (legacy admin + SPA) + `Channel#default` boolean shipped in 5.5. Catalog, Company/CompanyLocation/CompanyContact for B2B pending in 6.0. Multi-store catalogs (historic `Product has_many :stores`) move to the `spree_multi_store` extension.
Pending design work (drafts, no implementation yet):
+- `5.5-6.0-resource-translations-api.md` — Admin API v3 translation management + React dashboard for all `Spree.translatable_resources`. Hybrid: embedded `translations` object on resource update + generic dedicated `…/:id/translations` endpoint (one registry-driven controller), self-describing field discovery, advisory server-side staleness. Canonical `{ locale → { field → value } }` shape (consistent with metafield-translations). Cross-record bulk = CSV import/export generalized across the registry (NOT a JSON bulk endpoint — no competitor ships one). Phase 1 (5.5) API; Phase 2 (6.0) coverage read + CSV generalization + staleness + centralized SPA page; Phase 3 folds in metafields.
- `5.4-centralized-translations-admin.md` — Centralized Translations admin page under Products, overview grid + bulk CSV import/export
- `5.4-metafield-translations.md` — Translate MetafieldDefinition names + Metafield text values (ShortText, LongText, RichText) via Mobility translation tables
- `5.5-admin-api-cli.md` — `spree api` command group in `@spree/cli` (gh-api-style generic verbs + schema introspection + layered auth, CLI-first ahead of MCP servers; core patch: `SCOPES` on `spree:cli:create_api_key`, promotions scopes)
@@ -406,6 +407,7 @@ Spree::Dependencies.cart_add_item_service = 'Spree::Cart::AddItem'
- Re-generate OpenAPI spec after API changes: `bundle exec rake rswag:specs:swaggerize`
- OpenAPI spec: `docs/api-reference/store.yaml` (generated from `spree/api/spec/integration`)
- Update developer docs in `docs/developer/` when relevant
+- DO NOT edit the OpenAPI specs manually, it is generated from the integration tests. If you need to change the spec, change the integration tests instead and run swaggerize to regenerate the spec.
---
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index d15af1772e..c0790156af 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -92,16 +92,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjVhODJiOTM1LTY0MjctNDMxZS04ODMyLTZlZDdiNTBlMmZhYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgyMzEwOTM3fQ.As8Yl71W0Cx9pHJ26y03CDtgsAjo7yn41-JrArdENO8
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjZmMmYxMGU1LTExMzgtNDQ0NC05ODRlLTEyZmI4MWNiMDczNSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgyNDc3MzkyfQ.aZvSPnctrw4IX865of2fWMW8MnQHpaZQiPe3FTfGYyY
user:
id: admin_UkLWZg9DAJ
- first_name: Carroll
- last_name: Bartoletti
- full_name: Carroll Bartoletti
+ first_name: Melvina
+ last_name: Fadel
+ full_name: Melvina Fadel
selected_locale:
- created_at: '2026-06-24T14:17:16.914Z'
- updated_at: '2026-06-24T14:17:16.914Z'
+ created_at: '2026-06-26T12:31:31.763Z'
+ updated_at: '2026-06-26T12:31:31.763Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -199,16 +199,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImQzOTY1YjAzLTk3ZjQtNDRjMi1hOTE0LWE2OTQzZDNjN2VjMiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgyMzEwOTM4fQ.fiU9GNUCy6C4S2nIt1VAWOxwDH16d0A6N6L5cC3SqzA
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjhiZTBkY2M1LTEwODQtNDEwYi1hNjgxLTZiNWE0MTg0Nzk3MyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzgyNDc3MzkyfQ.FAUoarOne_p06AtM55K5mdXphWKdG-KD2kkix0tIzTI
user:
id: admin_UkLWZg9DAJ
- first_name: Dallas
- last_name: Larkin
- full_name: Dallas Larkin
+ first_name: Lavinia
+ last_name: Bergnaum
+ full_name: Lavinia Bergnaum
selected_locale:
- created_at: '2026-06-24T14:17:18.005Z'
- updated_at: '2026-06-24T14:17:18.005Z'
+ created_at: '2026-06-26T12:31:32.958Z'
+ updated_at: '2026-06-26T12:31:32.958Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -305,13 +305,13 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Maggie
- last_name: Raynor
- full_name: Maggie Raynor
+ first_name: Verda
+ last_name: Torphy
+ full_name: Verda Torphy
selected_locale:
- created_at: '2026-06-24T14:17:50.815Z'
- updated_at: '2026-06-24T14:17:50.815Z'
+ created_at: '2026-06-26T12:32:06.875Z'
+ updated_at: '2026-06-26T12:32:06.875Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -426,13 +426,13 @@ paths:
example:
user:
id: admin_UkLWZg9DAJ
- first_name: Randal
- last_name: Robel
- full_name: Randal Robel
+ first_name: Hortense
+ last_name: Feest
+ full_name: Hortense Feest
selected_locale: de
- created_at: '2026-06-24T14:17:51.145Z'
- updated_at: '2026-06-24T14:17:51.160Z'
+ created_at: '2026-06-26T12:32:07.167Z'
+ updated_at: '2026-06-26T12:32:07.181Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -588,8 +588,8 @@ paths:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-06-24T14:17:12.233Z'
- updated_at: '2026-06-24T14:17:12.233Z'
+ created_at: '2026-06-26T12:31:27.104Z'
+ updated_at: '2026-06-26T12:31:27.104Z'
meta:
page: 1
limit: 25
@@ -673,8 +673,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
- created_at: '2026-06-24T14:17:12.829Z'
- updated_at: '2026-06-24T14:17:12.829Z'
+ created_at: '2026-06-26T12:31:27.702Z'
+ updated_at: '2026-06-26T12:31:27.702Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -761,8 +761,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-06-24T14:17:13.142Z'
- updated_at: '2026-06-24T14:17:13.142Z'
+ created_at: '2026-06-26T12:31:28.000Z'
+ updated_at: '2026-06-26T12:31:28.000Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
@@ -823,8 +823,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
- created_at: '2026-06-24T14:17:13.704Z'
- updated_at: '2026-06-24T14:17:13.994Z'
+ created_at: '2026-06-26T12:31:28.565Z'
+ updated_at: '2026-06-26T12:31:28.840Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -944,32 +944,32 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-06-24T14:17:14.669Z'
- updated_at: '2026-06-24T14:17:14.669Z'
+ created_at: '2026-06-26T12:31:29.434Z'
+ updated_at: '2026-06-26T12:31:29.434Z'
revoked_at:
last_used_at:
- plaintext_token: pk_FTCQ1tXHTUTET7krhkGNCmP4
+ plaintext_token: pk_QFnf4MHeFQZvPE2z3vbr6ctb
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_S216ueYvh
+ token_prefix: sk_wMhGygHyA
scopes:
- write_all
- created_at: '2026-06-24T14:17:14.671Z'
- updated_at: '2026-06-24T14:17:14.671Z'
+ created_at: '2026-06-26T12:31:29.434Z'
+ updated_at: '2026-06-26T12:31:29.434Z'
revoked_at:
last_used_at:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: illo
+ name: repellat
key_type: secret
- token_prefix: sk_3MXhBhxVF
+ token_prefix: sk_bN8N8sthG
scopes:
- write_all
- created_at: '2026-06-24T14:17:14.673Z'
- updated_at: '2026-06-24T14:17:14.673Z'
+ created_at: '2026-06-26T12:31:29.435Z'
+ updated_at: '2026-06-26T12:31:29.435Z'
revoked_at:
last_used_at:
plaintext_token:
@@ -1035,15 +1035,15 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_Q15TLjrRM
+ token_prefix: sk_aGBugP4GM
scopes:
- read_orders
- created_at: '2026-06-24T14:17:15.236Z'
- updated_at: '2026-06-24T14:17:15.236Z'
+ created_at: '2026-06-26T12:31:29.991Z'
+ updated_at: '2026-06-26T12:31:29.991Z'
revoked_at:
last_used_at:
- plaintext_token: sk_Q15TLjrRML4Dbis3JDSCmMJt
- created_by_email: [email protected]
+ plaintext_token: sk_aGBugP4GMPCyDjbXosLsmWJc
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -1132,11 +1132,11 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-06-24T14:17:15.520Z'
- updated_at: '2026-06-24T14:17:15.520Z'
+ created_at: '2026-06-26T12:31:30.285Z'
+ updated_at: '2026-06-26T12:31:30.285Z'
revoked_at:
last_used_at:
- plaintext_token: pk_1FdASiupjiUG2DhWcBYxuDQv
+ plaintext_token: pk_gEfVUhGWyNXfkb2328mW6brm
created_by_email:
patch:
summary: Update an API key
@@ -1190,11 +1190,11 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration (renamed)
key_type: secret
- token_prefix: sk_Q8Lgqw4ok
+ token_prefix: sk_97m61quPM
scopes:
- write_all
- created_at: '2026-06-24T14:17:15.800Z'
- updated_at: '2026-06-24T14:17:16.077Z'
+ created_at: '2026-06-26T12:31:30.579Z'
+ updated_at: '2026-06-26T12:31:30.869Z'
revoked_at:
last_used_at:
plaintext_token:
@@ -1290,13 +1290,13 @@ paths:
application/json:
example:
id: key_EfhxLZ9ck8
- name: enim
+ name: nam
key_type: secret
- token_prefix: sk_12NrCMUno
+ token_prefix: sk_BUWcACXEd
scopes:
- write_all
- created_at: '2026-06-24T14:17:16.367Z'
- updated_at: '2026-06-24T14:17:16.367Z'
+ created_at: '2026-06-26T12:31:31.187Z'
+ updated_at: '2026-06-26T12:31:31.187Z'
revoked_at:
last_used_at:
plaintext_token:
@@ -1353,12 +1353,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_QLDYfWBTK
+ token_prefix: sk_uYaqjWiBs
scopes:
- write_all
- created_at: '2026-06-24T14:17:16.378Z'
- updated_at: '2026-06-24T14:17:16.652Z'
- revoked_at: '2026-06-24T14:17:16.652Z'
+ created_at: '2026-06-26T12:31:31.205Z'
+ updated_at: '2026-06-26T12:31:31.492Z'
+ revoked_at: '2026-06-26T12:31:31.492Z'
last_used_at:
plaintext_token:
created_by_email:
@@ -1423,16 +1423,16 @@ paths:
active: true
default: true
preferred_order_routing_strategy:
- created_at: '2026-06-24T14:17:10.910Z'
- updated_at: '2026-06-24T14:17:10.910Z'
+ created_at: '2026-06-26T12:31:25.663Z'
+ updated_at: '2026-06-26T12:31:25.663Z'
- id: ch_gbHJdmfrXB
name: Wholesale
code: wholesale
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-24T14:17:18.614Z'
- updated_at: '2026-06-24T14:17:18.614Z'
+ created_at: '2026-06-26T12:31:33.606Z'
+ updated_at: '2026-06-26T12:31:33.606Z'
meta:
page: 1
limit: 25
@@ -1513,8 +1513,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-24T14:17:19.188Z'
- updated_at: '2026-06-24T14:17:19.188Z'
+ created_at: '2026-06-26T12:31:34.214Z'
+ updated_at: '2026-06-26T12:31:34.214Z'
requestBody:
content:
application/json:
@@ -1586,8 +1586,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-24T14:17:19.197Z'
- updated_at: '2026-06-24T14:17:19.197Z'
+ created_at: '2026-06-26T12:31:34.226Z'
+ updated_at: '2026-06-26T12:31:34.226Z'
patch:
summary: Update a channel
tags:
@@ -1637,8 +1637,8 @@ paths:
active: true
default: false
preferred_order_routing_strategy:
- created_at: '2026-06-24T14:17:19.483Z'
- updated_at: '2026-06-24T14:17:19.766Z'
+ created_at: '2026-06-26T12:31:34.596Z'
+ updated_at: '2026-06-26T12:31:34.934Z'
requestBody:
content:
application/json:
@@ -1913,8 +1913,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-24T14:17:21.154Z'
- updated_at: '2026-06-24T14:17:21.154Z'
+ created_at: '2026-06-26T12:31:36.545Z'
+ updated_at: '2026-06-26T12:31:36.545Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -1922,8 +1922,8 @@ paths:
field_type: short_text
resource_type: Spree::Order
storefront_visible: true
- created_at: '2026-06-24T14:17:21.155Z'
- updated_at: '2026-06-24T14:17:21.155Z'
+ created_at: '2026-06-26T12:31:36.546Z'
+ updated_at: '2026-06-26T12:31:36.546Z'
meta:
page: 1
limit: 25
@@ -1989,8 +1989,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-24T14:17:21.742Z'
- updated_at: '2026-06-24T14:17:21.742Z'
+ created_at: '2026-06-26T12:31:37.136Z'
+ updated_at: '2026-06-26T12:31:37.136Z'
requestBody:
content:
application/json:
@@ -2087,8 +2087,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: true
- created_at: '2026-06-24T14:17:21.747Z'
- updated_at: '2026-06-24T14:17:21.747Z'
+ created_at: '2026-06-26T12:31:37.143Z'
+ updated_at: '2026-06-26T12:31:37.143Z'
patch:
summary: Update a custom field definition
tags:
@@ -2145,8 +2145,8 @@ paths:
field_type: short_text
resource_type: Spree::Product
storefront_visible: false
- created_at: '2026-06-24T14:17:22.045Z'
- updated_at: '2026-06-24T14:17:22.335Z'
+ created_at: '2026-06-26T12:31:37.431Z'
+ updated_at: '2026-06-26T12:31:37.823Z'
requestBody:
content:
application/json:
@@ -2288,14 +2288,14 @@ paths:
name: VIPs
description: Top spenders
customers_count: 0
- created_at: '2026-06-24T14:17:22.636Z'
- updated_at: '2026-06-24T14:17:22.636Z'
+ created_at: '2026-06-26T12:31:38.180Z'
+ updated_at: '2026-06-26T12:31:38.180Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
- created_at: '2026-06-24T14:17:22.637Z'
- updated_at: '2026-06-24T14:17:22.637Z'
+ created_at: '2026-06-26T12:31:38.181Z'
+ updated_at: '2026-06-26T12:31:38.181Z'
meta:
page: 1
limit: 25
@@ -2384,8 +2384,8 @@ paths:
name: Wholesale 2
description: B2B accounts
customers_count: 1
- created_at: '2026-06-24T14:17:23.511Z'
- updated_at: '2026-06-24T14:17:23.511Z'
+ created_at: '2026-06-26T12:31:39.119Z'
+ updated_at: '2026-06-26T12:31:39.119Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -2494,24 +2494,24 @@ paths:
name: VIPs
description: Top spenders
customers_count: 1
- created_at: '2026-06-24T14:17:24.116Z'
- updated_at: '2026-06-24T14:17:24.116Z'
+ created_at: '2026-06-26T12:31:39.762Z'
+ updated_at: '2026-06-26T12:31:39.762Z'
customers:
- id: cus_UkLWZg9DAJ
- first_name: Skye
- last_name: Howe
+ first_name: Fredia
+ last_name: Armstrong
phone:
accepts_email_marketing: false
- full_name: Skye Howe
+ full_name: Fredia Armstrong
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-24T14:17:24.386Z'
- updated_at: '2026-06-24T14:17:24.386Z'
+ created_at: '2026-06-26T12:31:40.024Z'
+ updated_at: '2026-06-26T12:31:40.024Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -2594,8 +2594,8 @@ paths:
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
- created_at: '2026-06-24T14:17:25.024Z'
- updated_at: '2026-06-24T14:17:25.317Z'
+ created_at: '2026-06-26T12:31:40.625Z'
+ updated_at: '2026-06-26T12:31:40.906Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -2754,8 +2754,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-06-24T14:17:26.244Z'
- updated_at: '2026-06-24T14:17:26.244Z'
+ created_at: '2026-06-26T12:31:41.750Z'
+ updated_at: '2026-06-26T12:31:41.750Z'
customer_id: cus_UkLWZg9DAJ
meta:
page: 1
@@ -2848,8 +2848,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-06-24T14:17:27.712Z'
- updated_at: '2026-06-24T14:17:27.712Z'
+ created_at: '2026-06-26T12:31:43.294Z'
+ updated_at: '2026-06-26T12:31:43.294Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -2963,8 +2963,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-06-24T14:17:27.989Z'
- updated_at: '2026-06-24T14:17:28.546Z'
+ created_at: '2026-06-26T12:31:43.670Z'
+ updated_at: '2026-06-26T12:31:44.215Z'
customer_id: cus_UkLWZg9DAJ
requestBody:
content:
@@ -3103,8 +3103,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-06-24T14:17:29.681Z'
- updated_at: '2026-06-24T14:17:29.681Z'
+ created_at: '2026-06-26T12:31:45.346Z'
+ updated_at: '2026-06-26T12:31:45.346Z'
meta:
page: 1
limit: 25
@@ -3194,8 +3194,8 @@ paths:
customer_id: cus_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-06-24T14:17:30.272Z'
- updated_at: '2026-06-24T14:17:30.272Z'
+ created_at: '2026-06-26T12:31:45.954Z'
+ updated_at: '2026-06-26T12:31:45.954Z'
delete:
summary: Delete a customer credit card
tags:
@@ -3320,8 +3320,8 @@ paths:
currency: USD
memo:
metadata: {}
- created_at: '2026-06-24T14:17:31.782Z'
- updated_at: '2026-06-24T14:17:31.782Z'
+ created_at: '2026-06-26T12:31:47.423Z'
+ updated_at: '2026-06-26T12:31:47.423Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -3400,8 +3400,8 @@ paths:
currency: USD
memo: Goodwill
metadata: {}
- created_at: '2026-06-24T14:17:32.969Z'
- updated_at: '2026-06-24T14:17:32.969Z'
+ created_at: '2026-06-26T12:31:48.527Z'
+ updated_at: '2026-06-26T12:31:48.527Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_gbHJdmfrXB
category_id: sccat_UkLWZg9DAJ
@@ -3496,8 +3496,8 @@ paths:
currency: USD
memo: Updated
metadata: {}
- created_at: '2026-06-24T14:17:33.536Z'
- updated_at: '2026-06-24T14:17:33.841Z'
+ created_at: '2026-06-26T12:31:49.077Z'
+ updated_at: '2026-06-26T12:31:49.357Z'
customer_id: cus_UkLWZg9DAJ
created_by_id: admin_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -3658,8 +3658,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-24T14:17:35.056Z'
- updated_at: '2026-06-24T14:17:35.056Z'
+ created_at: '2026-06-26T12:31:50.430Z'
+ updated_at: '2026-06-26T12:31:50.430Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3747,8 +3747,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-24T14:17:35.963Z'
- updated_at: '2026-06-24T14:17:35.963Z'
+ created_at: '2026-06-26T12:31:51.250Z'
+ updated_at: '2026-06-26T12:31:51.250Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3868,8 +3868,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-24T14:17:36.259Z'
- updated_at: '2026-06-24T14:17:36.259Z'
+ created_at: '2026-06-26T12:31:51.520Z'
+ updated_at: '2026-06-26T12:31:51.520Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -3947,8 +3947,8 @@ paths:
metadata: {}
last_sign_in_at:
current_sign_in_at:
- created_at: '2026-06-24T14:17:36.830Z'
- updated_at: '2026-06-24T14:17:37.121Z'
+ created_at: '2026-06-26T12:31:52.061Z'
+ updated_at: '2026-06-26T12:31:52.338Z'
sign_in_count: 0
failed_attempts: 0
last_sign_in_ip:
@@ -4397,11 +4397,11 @@ paths:
example:
data:
- id: exp_UkLWZg9DAJ
- number: EF248493701
+ number: EF798554810
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-24T14:17:41.370Z'
- updated_at: '2026-06-24T14:17:41.370Z'
+ created_at: '2026-06-26T12:31:56.659Z'
+ updated_at: '2026-06-26T12:31:56.659Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -4471,11 +4471,11 @@ paths:
application/json:
example:
id: exp_gbHJdmfrXB
- number: EF825853225
+ number: EF844039218
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-24T14:17:41.684Z'
- updated_at: '2026-06-24T14:17:41.684Z'
+ created_at: '2026-06-26T12:31:56.960Z'
+ updated_at: '2026-06-26T12:31:56.960Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -4565,11 +4565,11 @@ paths:
application/json:
example:
id: exp_UkLWZg9DAJ
- number: EF591248460
+ number: EF691531998
type: Spree::Exports::Products
format: csv
- created_at: '2026-06-24T14:17:41.956Z'
- updated_at: '2026-06-24T14:17:41.956Z'
+ created_at: '2026-06-26T12:31:57.453Z'
+ updated_at: '2026-06-26T12:31:57.453Z'
user_id: admin_UkLWZg9DAJ
done: false
filename:
@@ -4751,7 +4751,7 @@ paths:
example:
data:
- id: ful_UkLWZg9DAJ
- number: H66502702375
+ number: H29454192483
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4776,8 +4776,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-24T14:17:53.823Z'
- updated_at: '2026-06-24T14:17:53.902Z'
+ created_at: '2026-06-26T12:32:09.891Z'
+ updated_at: '2026-06-26T12:32:09.967Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
meta:
@@ -4863,7 +4863,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H55612322489
+ number: H61782868825
tracking: U10000
tracking_url:
cost: '10.0'
@@ -4888,8 +4888,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-24T14:17:54.562Z'
- updated_at: '2026-06-24T14:17:54.619Z'
+ created_at: '2026-06-26T12:32:10.565Z'
+ updated_at: '2026-06-26T12:32:10.618Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
patch:
@@ -4951,7 +4951,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H33179685534
+ number: H25934860852
tracking: 1Z999AA10123456784
tracking_url: https://wwwapps.ups.com/WebTracking/track?track=yes&trackNums=1Z999AA10123456784
cost: '10.0'
@@ -4976,8 +4976,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-24T14:17:55.215Z'
- updated_at: '2026-06-24T14:17:55.559Z'
+ created_at: '2026-06-26T12:32:11.224Z'
+ updated_at: '2026-06-26T12:32:11.551Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
requestBody:
@@ -5050,7 +5050,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H83673495611
+ number: H11930439244
tracking: U10000
tracking_url:
cost: '10.0'
@@ -5067,7 +5067,7 @@ paths:
display_tax_total: "$0.00"
status: shipped
fulfillment_type: shipping
- fulfilled_at: '2026-06-24T14:17:56Z'
+ fulfilled_at: '2026-06-26T12:32:12Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -5075,8 +5075,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-24T14:17:55.915Z'
- updated_at: '2026-06-24T14:17:56.285Z'
+ created_at: '2026-06-26T12:32:11.862Z'
+ updated_at: '2026-06-26T12:32:12.192Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":
@@ -5138,7 +5138,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H14338892185
+ number: H20100319423
tracking: U10000
tracking_url:
cost: '10.0'
@@ -5163,8 +5163,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-24T14:17:56.619Z'
- updated_at: '2026-06-24T14:17:57.002Z'
+ created_at: '2026-06-26T12:32:12.509Z'
+ updated_at: '2026-06-26T12:32:12.852Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":
@@ -5226,7 +5226,7 @@ paths:
application/json:
example:
id: ful_UkLWZg9DAJ
- number: H59772175670
+ number: H81741738087
tracking: U10000
tracking_url:
cost: '10.0'
@@ -5251,8 +5251,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-24T14:17:57.326Z'
- updated_at: '2026-06-24T14:17:57.683Z'
+ created_at: '2026-06-26T12:32:13.172Z'
+ updated_at: '2026-06-26T12:32:13.520Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":
@@ -5316,7 +5316,7 @@ paths:
example:
data:
- id: ful_gbHJdmfrXB
- number: H06978194601
+ number: H82149236796
tracking:
tracking_url:
cost: '10.0'
@@ -5341,8 +5341,8 @@ paths:
metadata: {}
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-06-24T14:17:58.347Z'
- updated_at: '2026-06-24T14:17:58.417Z'
+ created_at: '2026-06-26T12:32:14.190Z'
+ updated_at: '2026-06-26T12:32:14.234Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
requestBody:
@@ -5441,8 +5441,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-06-24T14:17:42.562Z'
- updated_at: '2026-06-24T14:17:42.562Z'
+ created_at: '2026-06-26T12:31:58.104Z'
+ updated_at: '2026-06-26T12:31:58.104Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -5526,8 +5526,8 @@ paths:
codes_count: 5
currency: USD
prefix: NEWCAMP
- created_at: '2026-06-24T14:17:43.133Z'
- updated_at: '2026-06-24T14:17:43.133Z'
+ created_at: '2026-06-26T12:31:58.708Z'
+ updated_at: '2026-06-26T12:31:58.708Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: admin_UkLWZg9DAJ
@@ -5631,8 +5631,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-06-24T14:17:43.428Z'
- updated_at: '2026-06-24T14:17:43.428Z'
+ created_at: '2026-06-26T12:31:59.017Z'
+ updated_at: '2026-06-26T12:31:59.017Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -5738,7 +5738,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 5BB729CE1E8A8183
+ code: 062443037FD5DCF9
status: active
currency: USD
amount: '50.0'
@@ -5752,12 +5752,12 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-24T14:17:43.990Z'
- updated_at: '2026-06-24T14:17:43.990Z'
+ created_at: '2026-06-26T12:31:59.603Z'
+ updated_at: '2026-06-26T12:31:59.603Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
- code: 31F2557E8AB25F6D
+ code: 78437A5D1D7AB5D3
status: active
currency: USD
amount: '25.0'
@@ -5771,8 +5771,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-24T14:17:43.991Z'
- updated_at: '2026-06-24T14:17:43.991Z'
+ created_at: '2026-06-26T12:31:59.604Z'
+ updated_at: '2026-06-26T12:31:59.604Z'
customer_id:
created_by_id:
meta:
@@ -5860,7 +5860,7 @@ paths:
application/json:
example:
id: gc_EfhxLZ9ck8
- code: F021764CF23D7041
+ code: 6FC92C9BC55A2622
status: active
currency: USD
amount: '25.0'
@@ -5874,8 +5874,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-24T14:17:44.581Z'
- updated_at: '2026-06-24T14:17:44.581Z'
+ created_at: '2026-06-26T12:32:00.326Z'
+ updated_at: '2026-06-26T12:32:00.326Z'
customer_id:
created_by_id: admin_UkLWZg9DAJ
schema:
@@ -5984,7 +5984,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 7053C6C8F9BA830E
+ code: AFC48D9EF1485163
status: active
currency: USD
amount: '50.0'
@@ -5998,8 +5998,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-24T14:17:44.875Z'
- updated_at: '2026-06-24T14:17:44.875Z'
+ created_at: '2026-06-26T12:32:00.638Z'
+ updated_at: '2026-06-26T12:32:00.638Z'
customer_id:
created_by_id:
schema:
@@ -6062,7 +6062,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: F6B9CE9D0FF09614
+ code: AD0C98D1EAACDBCC
status: active
currency: USD
amount: '75.0'
@@ -6076,8 +6076,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-24T14:17:45.441Z'
- updated_at: '2026-06-24T14:17:45.756Z'
+ created_at: '2026-06-26T12:32:01.208Z'
+ updated_at: '2026-06-26T12:32:01.489Z'
customer_id:
created_by_id:
schema:
@@ -6233,8 +6233,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-24T14:17:47.620Z'
- updated_at: '2026-06-24T14:17:47.620Z'
+ created_at: '2026-06-26T12:32:03.667Z'
+ updated_at: '2026-06-26T12:32:03.667Z'
meta:
page: 1
limit: 25
@@ -6327,8 +6327,8 @@ paths:
supported_locales:
- en
- fr
- created_at: '2026-06-24T14:17:48.229Z'
- updated_at: '2026-06-24T14:17:48.229Z'
+ created_at: '2026-06-26T12:32:04.357Z'
+ updated_at: '2026-06-26T12:32:04.357Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -6464,8 +6464,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-24T14:17:48.574Z'
- updated_at: '2026-06-24T14:17:48.574Z'
+ created_at: '2026-06-26T12:32:04.758Z'
+ updated_at: '2026-06-26T12:32:04.758Z'
schema:
"$ref": "#/components/schemas/Market"
'404':
@@ -6544,8 +6544,8 @@ paths:
- DE
supported_locales:
- en
- created_at: '2026-06-24T14:17:49.183Z'
- updated_at: '2026-06-24T14:17:49.496Z'
+ created_at: '2026-06-26T12:32:05.395Z'
+ updated_at: '2026-06-26T12:32:05.684Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -6725,8 +6725,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-24T14:17:51.177Z'
- updated_at: '2026-06-24T14:17:51.177Z'
+ created_at: '2026-06-26T12:32:07.195Z'
+ updated_at: '2026-06-26T12:32:07.195Z'
meta:
page: 1
limit: 25
@@ -6820,8 +6820,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-24T14:17:51.759Z'
- updated_at: '2026-06-24T14:17:51.759Z'
+ created_at: '2026-06-26T12:32:07.801Z'
+ updated_at: '2026-06-26T12:32:07.801Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -6945,8 +6945,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-24T14:17:52.065Z'
- updated_at: '2026-06-24T14:17:52.065Z'
+ created_at: '2026-06-26T12:32:08.115Z'
+ updated_at: '2026-06-26T12:32:08.115Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
@@ -7019,8 +7019,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-06-24T14:17:52.630Z'
- updated_at: '2026-06-24T14:17:52.907Z'
+ created_at: '2026-06-26T12:32:08.709Z'
+ updated_at: '2026-06-26T12:32:08.987Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -7171,7 +7171,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 789AB16A35A57FDE
+ code: B154B66C8774C00A
status: active
currency: USD
amount: '10.0'
@@ -7185,8 +7185,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-06-24T14:17:58.808Z'
- updated_at: '2026-06-24T14:17:59.105Z'
+ created_at: '2026-06-26T12:32:14.565Z'
+ updated_at: '2026-06-26T12:32:14.857Z'
customer_id:
created_by_id:
requestBody:
@@ -7325,8 +7325,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 126338
- slug: product-126338
+ name: Product 128538
+ slug: product-128538
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -7358,12 +7358,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:17:59.794Z'
- updated_at: '2026-06-24T14:17:59.794Z'
+ created_at: '2026-06-26T12:32:15.531Z'
+ updated_at: '2026-06-26T12:32:15.531Z'
digital_links: []
metadata: {}
- created_at: '2026-06-24T14:18:00.078Z'
- updated_at: '2026-06-24T14:18:00.078Z'
+ created_at: '2026-06-26T12:32:15.815Z'
+ updated_at: '2026-06-26T12:32:15.815Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -7433,8 +7433,8 @@ paths:
variant_id: variant_VqXmZF31wY
quantity: 3
currency: USD
- name: Product 145177
- slug: product-145177
+ name: Product 14956
+ slug: product-14956
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -7466,12 +7466,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:18:00.998Z'
- updated_at: '2026-06-24T14:18:00.998Z'
+ created_at: '2026-06-26T12:32:16.730Z'
+ updated_at: '2026-06-26T12:32:16.730Z'
digital_links: []
metadata: {}
- created_at: '2026-06-24T14:18:01.024Z'
- updated_at: '2026-06-24T14:18:01.024Z'
+ created_at: '2026-06-26T12:32:16.758Z'
+ updated_at: '2026-06-26T12:32:16.758Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -7563,8 +7563,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 2
currency: USD
- name: Product 15719
- slug: product-15719
+ name: Product 153487
+ slug: product-153487
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -7596,12 +7596,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:18:01.116Z'
- updated_at: '2026-06-24T14:18:01.116Z'
+ created_at: '2026-06-26T12:32:16.855Z'
+ updated_at: '2026-06-26T12:32:16.855Z'
digital_links: []
metadata: {}
- created_at: '2026-06-24T14:18:01.398Z'
- updated_at: '2026-06-24T14:18:01.398Z'
+ created_at: '2026-06-26T12:32:17.145Z'
+ updated_at: '2026-06-26T12:32:17.145Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -7666,8 +7666,8 @@ paths:
variant_id: variant_gbHJdmfrXB
quantity: 5
currency: USD
- name: Product 164218
- slug: product-164218
+ name: Product 16353
+ slug: product-16353
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -7699,12 +7699,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:18:01.726Z'
- updated_at: '2026-06-24T14:18:01.726Z'
+ created_at: '2026-06-26T12:32:17.522Z'
+ updated_at: '2026-06-26T12:32:17.522Z'
digital_links: []
metadata: {}
- created_at: '2026-06-24T14:18:02.006Z'
- updated_at: '2026-06-24T14:18:02.297Z'
+ created_at: '2026-06-26T12:32:17.809Z'
+ updated_at: '2026-06-26T12:32:18.109Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -7824,8 +7824,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R969056004
+ number: R952614493
customer_note:
currency: USD
locale: en
@@ -7868,8 +7868,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-24T14:18:09.278Z'
- updated_at: '2026-06-24T14:18:09.326Z'
+ created_at: '2026-06-26T12:32:24.689Z'
+ updated_at: '2026-06-26T12:32:24.745Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8046,8 +8046,8 @@ paths:
- id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R073914460
+ number: R260841129
customer_note:
currency: USD
locale: en
@@ -8090,8 +8090,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-24T14:18:11.273Z'
- updated_at: '2026-06-24T14:18:11.273Z'
+ created_at: '2026-06-26T12:32:26.490Z'
+ updated_at: '2026-06-26T12:32:26.490Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8242,7 +8242,7 @@ paths:
id: or_gbHJdmfrXB
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R308461364
+ number: R550748383
customer_note:
currency: USD
@@ -8286,8 +8286,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-24T14:18:12.978Z'
- updated_at: '2026-06-24T14:18:12.981Z'
+ created_at: '2026-06-26T12:32:28.238Z'
+ updated_at: '2026-06-26T12:32:28.243Z'
preferred_stock_location_id: sloc_UkLWZg9DAJ
tags: []
internal_note:
@@ -8474,8 +8474,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R546304819
+ number: R898237142
customer_note:
currency: USD
locale: en
@@ -8518,8 +8518,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-24T14:18:13.269Z'
- updated_at: '2026-06-24T14:18:13.269Z'
+ created_at: '2026-06-26T12:32:28.525Z'
+ updated_at: '2026-06-26T12:32:28.525Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8594,7 +8594,7 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R801718277
+ number: R609835171
customer_note:
currency: USD
@@ -8638,8 +8638,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-24T14:18:14.408Z'
- updated_at: '2026-06-24T14:18:14.711Z'
+ created_at: '2026-06-26T12:32:29.628Z'
+ updated_at: '2026-06-26T12:32:29.912Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8826,8 +8826,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R604303273
+ number: R383644566
customer_note:
currency: USD
locale: en
@@ -8854,7 +8854,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status: ready
payment_status: paid
- completed_at: '2026-06-24T14:18:15.680Z'
+ completed_at: '2026-06-26T12:32:30.819Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8870,8 +8870,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-24T14:18:15.598Z'
- updated_at: '2026-06-24T14:18:15.714Z'
+ created_at: '2026-06-26T12:32:30.765Z'
+ updated_at: '2026-06-26T12:32:30.842Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -8955,8 +8955,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R636427554
+ number: R383466644
customer_note:
currency: USD
locale: en
@@ -8983,7 +8983,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-06-24T14:18:17.024Z'
+ completed_at: '2026-06-26T12:32:32.111Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -8997,10 +8997,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-06-24T14:18:17.330Z'
+ canceled_at: '2026-06-26T12:32:32.405Z'
approved_at:
- created_at: '2026-06-24T14:18:16.947Z'
- updated_at: '2026-06-24T14:18:17.371Z'
+ created_at: '2026-06-26T12:32:32.041Z'
+ updated_at: '2026-06-26T12:32:32.451Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -9062,8 +9062,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R207525860
+ number: R511688826
customer_note:
currency: USD
locale: en
@@ -9090,7 +9090,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-06-24T14:18:17.733Z'
+ completed_at: '2026-06-26T12:32:32.849Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -9105,9 +9105,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-06-24T14:18:18.022Z'
- created_at: '2026-06-24T14:18:17.675Z'
- updated_at: '2026-06-24T14:18:17.733Z'
+ approved_at: '2026-06-26T12:32:33.134Z'
+ created_at: '2026-06-26T12:32:32.798Z'
+ updated_at: '2026-06-26T12:32:32.849Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -9169,8 +9169,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R882091458
+ number: R504415876
customer_note:
currency: USD
locale: en
@@ -9197,7 +9197,7 @@ paths:
display_delivery_total: "$10.00"
fulfillment_status: canceled
payment_status: void
- completed_at: '2026-06-24T14:18:18.418Z'
+ completed_at: '2026-06-26T12:32:33.463Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -9211,10 +9211,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-06-24T14:18:18.715Z'
+ canceled_at: '2026-06-26T12:32:33.864Z'
approved_at:
- created_at: '2026-06-24T14:18:18.311Z'
- updated_at: '2026-06-24T14:18:18.896Z'
+ created_at: '2026-06-26T12:32:33.418Z'
+ updated_at: '2026-06-26T12:32:34.007Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -9276,8 +9276,8 @@ paths:
id: or_UkLWZg9DAJ
market_id:
channel_id: ch_UkLWZg9DAJ
- number: R270791722
+ number: R959450528
customer_note:
currency: USD
locale: en
@@ -9304,7 +9304,7 @@ paths:
display_delivery_total: "$100.00"
fulfillment_status:
payment_status:
- completed_at: '2026-06-24T14:18:19.282Z'
+ completed_at: '2026-06-26T12:32:34.345Z'
store_credit_total: '0.0'
display_store_credit_total: "$0.00"
covered_by_store_credit: false
@@ -9320,8 +9320,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-06-24T14:18:19.213Z'
- updated_at: '2026-06-24T14:18:19.282Z'
+ created_at: '2026-06-26T12:32:34.295Z'
+ updated_at: '2026-06-26T12:32:34.345Z'
preferred_stock_location_id:
tags: []
internal_note:
@@ -9399,8 +9399,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-06-24T14:18:19.609Z'
- updated_at: '2026-06-24T14:18:19.610Z'
+ created_at: '2026-06-26T12:32:34.663Z'
+ updated_at: '2026-06-26T12:32:34.664Z'
preferences: {}
preference_schema: []
meta:
@@ -9546,8 +9546,8 @@ paths:
auto_capture:
storefront_visible: true
position: 1
- created_at: '2026-06-24T14:18:20.290Z'
- updated_at: '2026-06-24T14:18:20.292Z'
+ created_at: '2026-06-26T12:32:35.246Z'
+ updated_at: '2026-06-26T12:32:35.247Z'
preferences: {}
preference_schema: []
"/api/v3/admin/orders/{order_id}/payments":
@@ -9618,8 +9618,8 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-7b539a1a1357
- number: PAO6AGT6
+ response_code: BGS-3a0be2b85319
+ number: P7HHD30V
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9637,14 +9637,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-24T14:18:03.298Z'
- updated_at: '2026-06-24T14:18:03.300Z'
+ created_at: '2026-06-26T12:32:19.073Z'
+ updated_at: '2026-06-26T12:32:19.075Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-24T14:18:03.299Z'
- updated_at: '2026-06-24T14:18:03.299Z'
+ created_at: '2026-06-26T12:32:19.074Z'
+ updated_at: '2026-06-26T12:32:19.074Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -9714,7 +9714,7 @@ paths:
id: py_gbHJdmfrXB
payment_method_id: pm_EfhxLZ9ck8
response_code:
- number: PI5PK5LU
+ number: PKA2WBT3
amount: '110.0'
display_amount: "$110.00"
status: checkout
@@ -9725,8 +9725,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-24T14:18:04.636Z'
- updated_at: '2026-06-24T14:18:04.636Z'
+ created_at: '2026-06-26T12:32:20.367Z'
+ updated_at: '2026-06-26T12:32:20.367Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -9819,8 +9819,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-c137b2a0794a
- number: PMUBOPNP
+ response_code: BGS-55a8f8adfdfe
+ number: P5E9RLIH
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9838,14 +9838,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-24T14:18:05.023Z'
- updated_at: '2026-06-24T14:18:05.026Z'
+ created_at: '2026-06-26T12:32:20.729Z'
+ updated_at: '2026-06-26T12:32:20.731Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-24T14:18:05.025Z'
- updated_at: '2026-06-24T14:18:05.025Z'
+ created_at: '2026-06-26T12:32:20.730Z'
+ updated_at: '2026-06-26T12:32:20.730Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -9908,8 +9908,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-ff6cafc63df8
- number: P107N9JA
+ response_code: BGS-454287d25087
+ number: PWI0Q7SM
amount: '110.0'
display_amount: "$110.00"
status: completed
@@ -9927,14 +9927,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-24T14:18:05.738Z'
- updated_at: '2026-06-24T14:18:05.741Z'
+ created_at: '2026-06-26T12:32:21.374Z'
+ updated_at: '2026-06-26T12:32:21.376Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-24T14:18:05.740Z'
- updated_at: '2026-06-24T14:18:06.078Z'
+ created_at: '2026-06-26T12:32:21.375Z'
+ updated_at: '2026-06-26T12:32:21.698Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -10006,8 +10006,8 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-4b94787e6c76
- number: P98C4VVS
+ response_code: void-BGS-4494b6bcde9f
+ number: P3UMP9QC
amount: '110.0'
display_amount: "$110.00"
status: void
@@ -10025,14 +10025,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-06-24T14:18:07.296Z'
- updated_at: '2026-06-24T14:18:07.299Z'
+ created_at: '2026-06-26T12:32:22.754Z'
+ updated_at: '2026-06-26T12:32:22.758Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-06-24T14:18:07.297Z'
- updated_at: '2026-06-24T14:18:07.603Z'
+ created_at: '2026-06-26T12:32:22.756Z'
+ updated_at: '2026-06-26T12:32:23.063Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
@@ -10120,8 +10120,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-24T14:18:20.644Z'
- updated_at: '2026-06-24T14:18:20.644Z'
+ created_at: '2026-06-26T12:32:35.532Z'
+ updated_at: '2026-06-26T12:32:35.532Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10135,8 +10135,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-24T14:18:20.646Z'
- updated_at: '2026-06-24T14:18:20.646Z'
+ created_at: '2026-06-26T12:32:35.533Z'
+ updated_at: '2026-06-26T12:32:35.533Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10250,8 +10250,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-24T14:18:21.751Z'
- updated_at: '2026-06-24T14:18:21.754Z'
+ created_at: '2026-06-26T12:32:36.570Z'
+ updated_at: '2026-06-26T12:32:36.573Z'
currently_active: false
products_count: 1
prices_count: 2
@@ -10414,8 +10414,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-24T14:18:22.060Z'
- updated_at: '2026-06-24T14:18:22.060Z'
+ created_at: '2026-06-26T12:32:36.870Z'
+ updated_at: '2026-06-26T12:32:36.870Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10490,8 +10490,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-24T14:18:23.970Z'
- updated_at: '2026-06-24T14:18:24.270Z'
+ created_at: '2026-06-26T12:32:38.525Z'
+ updated_at: '2026-06-26T12:32:38.805Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10679,8 +10679,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-24T14:18:24.592Z'
- updated_at: '2026-06-24T14:18:24.906Z'
+ created_at: '2026-06-26T12:32:39.106Z'
+ updated_at: '2026-06-26T12:32:39.399Z'
currently_active: true
products_count: 0
prices_count: 0
@@ -10743,8 +10743,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-06-24T14:18:24.917Z'
- updated_at: '2026-06-24T14:18:25.240Z'
+ created_at: '2026-06-26T12:32:39.409Z'
+ updated_at: '2026-06-26T12:32:39.697Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -10858,8 +10858,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-24T14:18:25.304Z'
- updated_at: '2026-06-24T14:18:25.304Z'
+ created_at: '2026-06-26T12:32:39.755Z'
+ updated_at: '2026-06-26T12:32:39.755Z'
- id: price_EfhxLZ9ck8
amount: '5.0'
amount_in_cents: 500
@@ -10870,8 +10870,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-24T14:18:25.309Z'
- updated_at: '2026-06-24T14:18:25.309Z'
+ created_at: '2026-06-26T12:32:39.759Z'
+ updated_at: '2026-06-26T12:32:39.759Z'
meta:
page: 1
limit: 25
@@ -10953,8 +10953,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_EfhxLZ9ck8
- created_at: '2026-06-24T14:18:25.988Z'
- updated_at: '2026-06-24T14:18:25.988Z'
+ created_at: '2026-06-26T12:32:40.419Z'
+ updated_at: '2026-06-26T12:32:40.419Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -11041,8 +11041,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-24T14:18:26.079Z'
- updated_at: '2026-06-24T14:18:26.079Z'
+ created_at: '2026-06-26T12:32:40.515Z'
+ updated_at: '2026-06-26T12:32:40.515Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
@@ -11107,8 +11107,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-06-24T14:18:26.985Z'
- updated_at: '2026-06-24T14:18:27.325Z'
+ created_at: '2026-06-26T12:32:41.299Z'
+ updated_at: '2026-06-26T12:32:41.583Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -11420,8 +11420,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-06-24T14:18:29.175Z'
- updated_at: '2026-06-24T14:18:29.175Z'
+ created_at: '2026-06-26T12:32:43.091Z'
+ updated_at: '2026-06-26T12:32:43.091Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -11491,8 +11491,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-06-24T14:18:29.793Z'
- updated_at: '2026-06-24T14:18:29.793Z'
+ created_at: '2026-06-26T12:32:43.725Z'
+ updated_at: '2026-06-26T12:32:43.725Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -11591,8 +11591,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-06-24T14:18:30.145Z'
- updated_at: '2026-06-24T14:18:30.145Z'
+ created_at: '2026-06-26T12:32:44.124Z'
+ updated_at: '2026-06-26T12:32:44.124Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -11656,8 +11656,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-06-24T14:18:30.460Z'
- updated_at: '2026-06-24T14:18:30.738Z'
+ created_at: '2026-06-26T12:32:44.463Z'
+ updated_at: '2026-06-26T12:32:44.748Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -11717,6 +11717,83 @@ paths:
responses:
'204':
description: custom field deleted
+ "/api/v3/admin/products/{product_id}/translations":
+ get:
+ summary: List product translations
+ tags:
+ - Products
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.
+
+ **Required scope:** `read_products` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: product_id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: translations found
+ content:
+ application/json:
+ example:
+ data:
+ resource_id: prod_UkLWZg9DAJ
+ resource_type: product
+ translations:
+ de:
+ name: Espressomaschine
+ description:
+ slug: espressomaschine
+ meta_description:
+ meta_title:
+ translated_field_count: 2
+ fr:
+ name:
+ description:
+ slug:
+ meta_description:
+ meta_title:
+ translated_field_count: 0
+ fields:
+ - key: name
+ type: string
+ source: Espresso Machine
+ - key: description
+ type: html
+ source: |-
+ Expedita repellendus alias dignissimos inventore illum nesciunt quas. Placeat sunt veritatis nulla dicta eveniet. Dolor porro distinctio dolorem iusto maxime veniam ipsam.
+ Odio deserunt omnis voluptate ex autem nostrum occaecati. Maiores impedit quisquam ducimus soluta deserunt pariatur tempore molestiae. Aliquam nobis impedit ducimus similique dignissimos deleniti. Laborum deleniti exercitationem beatae tempore ipsa molestias. Alias atque ducimus aliquam harum accusamus.
+ Minima sequi optio repellendus assumenda ratione illum. Numquam cupiditate deleniti ducimus sapiente. Magnam sint tempore quam modi adipisci hic incidunt. Praesentium accusantium dolorem corrupti minus libero. Tempore eligendi deleniti incidunt repudiandae inventore explicabo.
+ Minima quis doloremque molestias ducimus. Animi autem numquam officiis iusto ullam nesciunt commodi iure. Velit similique consectetur porro sunt quod. Aliquid dignissimos quisquam ex officia quis animi nobis.
+ - key: slug
+ type: string
+ source: espresso-machine
+ - key: meta_description
+ type: string
+ source:
+ - key: meta_title
+ type: string
+ source:
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
"/api/v3/admin/products":
get:
summary: List products
@@ -11813,8 +11890,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 573218
- slug: product-573218
+ name: Product 574714
+ slug: product-574714
meta_title:
meta_description:
meta_keywords:
@@ -11824,12 +11901,12 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Nostrum inventore sequi molestiae suscipit ipsum doloribus
- recusandae numquam. Alias ducimus aliquid modi quo itaque. Inventore
- voluptas repellendus earum deleniti deserunt.
- description_html: Nostrum inventore sequi molestiae suscipit ipsum
- doloribus recusandae numquam. Alias ducimus aliquid modi quo itaque.
- Inventore voluptas repellendus earum deleniti deserunt.
+ description: Provident perspiciatis accusamus distinctio illo. Sequi
+ rem esse dolorum natus neque iusto. Dolores numquam animi ab doloremque
+ modi non id. Nesciunt rem autem esse quas.
+ description_html: Provident perspiciatis accusamus distinctio illo.
+ Sequi rem esse dolorum natus neque iusto. Dolores numquam animi
+ ab doloremque modi non id. Nesciunt rem autem esse quas.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -11844,14 +11921,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:31.086Z'
- updated_at: '2026-06-24T14:18:31.086Z'
+ created_at: '2026-06-26T12:32:45.547Z'
+ updated_at: '2026-06-26T12:32:45.547Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-24T14:18:31.077Z'
- updated_at: '2026-06-24T14:18:31.091Z'
+ created_at: '2026-06-26T12:32:45.538Z'
+ updated_at: '2026-06-26T12:32:45.553Z'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
page: 1
@@ -11983,8 +12060,8 @@ paths:
status: draft
metadata: {}
deleted_at:
- created_at: '2026-06-24T14:18:31.826Z'
- updated_at: '2026-06-24T14:18:31.828Z'
+ created_at: '2026-06-26T12:32:46.320Z'
+ updated_at: '2026-06-26T12:32:46.321Z'
tax_category_id:
schema:
"$ref": "#/components/schemas/Product"
@@ -12189,8 +12266,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 61459
- slug: product-61459
+ name: Product 619180
+ slug: product-619180
meta_title:
meta_description:
meta_keywords:
@@ -12200,16 +12277,14 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Optio reprehenderit iusto aspernatur odit molestias beatae
- ipsum. Odio eligendi nostrum at veniam. Eveniet dolores minus nostrum
- illum ratione culpa. Maxime consectetur repellendus eos illum ut
- molestias architecto. Nisi totam cumque necessitatibus at provident
- repellendus temporibus sed.
- description_html: Optio reprehenderit iusto aspernatur odit molestias
- beatae ipsum. Odio eligendi nostrum at veniam. Eveniet dolores minus
- nostrum illum ratione culpa. Maxime consectetur repellendus eos
- illum ut molestias architecto. Nisi totam cumque necessitatibus
- at provident repellendus temporibus sed.
+ description: Maiores quos quia vel asperiores dolorum ipsum sed. Ipsam
+ dicta tenetur dolorum magnam. Eum ea neque delectus fuga omnis.
+ Molestias quam fugit neque incidunt quisquam architecto. Dolore
+ non voluptatem dicta quo accusantium nihil repudiandae quisquam.
+ description_html: Maiores quos quia vel asperiores dolorum ipsum sed.
+ Ipsam dicta tenetur dolorum magnam. Eum ea neque delectus fuga omnis.
+ Molestias quam fugit neque incidunt quisquam architecto. Dolore
+ non voluptatem dicta quo accusantium nihil repudiandae quisquam.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -12224,14 +12299,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:32.325Z'
- updated_at: '2026-06-24T14:18:32.325Z'
+ created_at: '2026-06-26T12:32:46.741Z'
+ updated_at: '2026-06-26T12:32:46.741Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-24T14:18:32.311Z'
- updated_at: '2026-06-24T14:18:32.335Z'
+ created_at: '2026-06-26T12:32:46.733Z'
+ updated_at: '2026-06-26T12:32:46.748Z'
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
@@ -12301,7 +12376,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-631331
+ slug: product-631716
meta_title:
meta_description:
meta_keywords:
@@ -12311,31 +12386,30 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Autem voluptate earum quasi accusamus. Vero dicta doloribus
- autem id. Laudantium ut voluptates consectetur temporibus eligendi
- doloribus quas. Deleniti nulla expedita velit commodi. Veritatis
- rerum iusto non temporibus quis quos sunt. Fuga at sapiente minima
- illo nam aut. Voluptatum placeat eligendi quis nostrum alias laborum.
- Praesentium architecto eius vel quas quam cupiditate. Quibusdam
- officia numquam dolores architecto quos facere. Consequuntur ipsa
- quae assumenda magni at accusantium debitis repellendus. Error voluptatibus
- nihil repellendus neque similique. Iusto sint eius praesentium voluptas
- ducimus facere quis. Magnam explicabo maxime earum nam eaque nobis
- illum. Molestiae perspiciatis sint dolorum iste ipsum nulla fugiat.
- Neque sapiente fuga quo voluptate itaque quasi magnam impedit. Quisquam
- impedit reiciendis corporis voluptatibus magni libero. Rem dolor
- asperiores illum fugit inventore facere voluptatum. Velit excepturi
- cupiditate unde molestias fugit dicta modi asperiores. Quas voluptatibus
- sed sint optio atque praesentium. Autem quibusdam excepturi sint
- nihil quas corrupti repudiandae. Quaerat earum nemo voluptatibus
- fugit totam vel suscipit placeat. Beatae ut suscipit est delectus
- dignissimos sunt rem.
+ description: Dolor nesciunt a aperiam repellendus consequatur. Expedita
+ ut aliquid ipsam illo maiores. Possimus corrupti praesentium quod
+ consequatur culpa doloremque expedita. Eius quod impedit nulla aperiam
+ dicta atque labore dignissimos. Ullam tenetur similique magni sint
+ aperiam alias consectetur. Tempore neque repudiandae libero laudantium.
+ Ullam corrupti odio reprehenderit ad a ea porro ratione. Porro deleniti
+ quaerat minima laborum nam quisquam quibusdam. Accusantium illo
+ dignissimos quidem in aut tempora. Cumque reiciendis impedit recusandae
+ ipsa sit. Nihil accusantium sint nostrum sed quibusdam. Totam blanditiis
+ soluta incidunt iusto modi. Rerum rem sint nobis totam quasi ipsa
+ excepturi aliquid. Nemo nulla aperiam mollitia porro. Neque dolore
+ natus rerum voluptatum ratione exercitationem. Iure id est ad modi.
+ Debitis distinctio iure vitae quis assumenda qui dolorem. Temporibus
+ officiis similique architecto excepturi placeat laudantium explicabo.
+ Non a necessitatibus atque dolores maiores in quae. Facere ducimus
+ labore repellendus reiciendis numquam mollitia veniam quasi. Et
+ atque doloremque adipisci quis facilis. Placeat voluptas ea laudantium
+ ex nobis.
description_html: |-
- Autem voluptate earum quasi accusamus. Vero dicta doloribus autem id. Laudantium ut voluptates consectetur temporibus eligendi doloribus quas. Deleniti nulla expedita velit commodi.
- Veritatis rerum iusto non temporibus quis quos sunt. Fuga at sapiente minima illo nam aut. Voluptatum placeat eligendi quis nostrum alias laborum. Praesentium architecto eius vel quas quam cupiditate. Quibusdam officia numquam dolores architecto quos facere.
- Consequuntur ipsa quae assumenda magni at accusantium debitis repellendus. Error voluptatibus nihil repellendus neque similique. Iusto sint eius praesentium voluptas ducimus facere quis. Magnam explicabo maxime earum nam eaque nobis illum.
- Molestiae perspiciatis sint dolorum iste ipsum nulla fugiat. Neque sapiente fuga quo voluptate itaque quasi magnam impedit. Quisquam impedit reiciendis corporis voluptatibus magni libero. Rem dolor asperiores illum fugit inventore facere voluptatum.
- Velit excepturi cupiditate unde molestias fugit dicta modi asperiores. Quas voluptatibus sed sint optio atque praesentium. Autem quibusdam excepturi sint nihil quas corrupti repudiandae. Quaerat earum nemo voluptatibus fugit totam vel suscipit placeat. Beatae ut suscipit est delectus dignissimos sunt rem.
+ Dolor nesciunt a aperiam repellendus consequatur. Expedita ut aliquid ipsam illo maiores. Possimus corrupti praesentium quod consequatur culpa doloremque expedita. Eius quod impedit nulla aperiam dicta atque labore dignissimos.
+ Ullam tenetur similique magni sint aperiam alias consectetur. Tempore neque repudiandae libero laudantium. Ullam corrupti odio reprehenderit ad a ea porro ratione. Porro deleniti quaerat minima laborum nam quisquam quibusdam. Accusantium illo dignissimos quidem in aut tempora.
+ Cumque reiciendis impedit recusandae ipsa sit. Nihil accusantium sint nostrum sed quibusdam. Totam blanditiis soluta incidunt iusto modi. Rerum rem sint nobis totam quasi ipsa excepturi aliquid.
+ Nemo nulla aperiam mollitia porro. Neque dolore natus rerum voluptatum ratione exercitationem. Iure id est ad modi. Debitis distinctio iure vitae quis assumenda qui dolorem.
+ Temporibus officiis similique architecto excepturi placeat laudantium explicabo. Non a necessitatibus atque dolores maiores in quae. Facere ducimus labore repellendus reiciendis numquam mollitia veniam quasi. Et atque doloremque adipisci quis facilis. Placeat voluptas ea laudantium ex nobis.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -12350,14 +12424,14 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:33.094Z'
- updated_at: '2026-06-24T14:18:33.094Z'
+ created_at: '2026-06-26T12:32:47.602Z'
+ updated_at: '2026-06-26T12:32:47.602Z'
original_price:
status: active
metadata: {}
deleted_at:
- created_at: '2026-06-24T14:18:33.075Z'
- updated_at: '2026-06-24T14:18:33.437Z'
+ created_at: '2026-06-26T12:32:47.589Z'
+ updated_at: '2026-06-26T12:32:47.906Z'
tax_category_id: taxcat_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/Product"
@@ -13182,15 +13256,15 @@ paths:
- id: coupon_UkLWZg9DAJ
code: AAA111
state: unused
- created_at: '2026-06-24T14:17:20.841Z'
- updated_at: '2026-06-24T14:17:20.841Z'
+ created_at: '2026-06-26T12:31:36.214Z'
+ updated_at: '2026-06-26T12:31:36.214Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
- id: coupon_gbHJdmfrXB
code: BBB222
state: unused
- created_at: '2026-06-24T14:17:20.842Z'
- updated_at: '2026-06-24T14:17:20.842Z'
+ created_at: '2026-06-26T12:31:36.215Z'
+ updated_at: '2026-06-26T12:31:36.215Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
meta:
@@ -13252,8 +13326,8 @@ paths:
example:
data:
- id: pact_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:37.507Z'
- updated_at: '2026-06-24T14:18:37.507Z'
+ created_at: '2026-06-26T12:32:52.441Z'
+ updated_at: '2026-06-26T12:32:52.441Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -13317,8 +13391,8 @@ paths:
application/json:
example:
id: pact_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:38.088Z'
- updated_at: '2026-06-24T14:18:38.088Z'
+ created_at: '2026-06-26T12:32:53.053Z'
+ updated_at: '2026-06-26T12:32:53.053Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -13446,8 +13520,8 @@ paths:
example:
data:
- id: prorule_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:38.678Z'
- updated_at: '2026-06-24T14:18:38.678Z'
+ created_at: '2026-06-26T12:32:53.748Z'
+ updated_at: '2026-06-26T12:32:53.748Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -13517,8 +13591,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:39.241Z'
- updated_at: '2026-06-24T14:18:39.241Z'
+ created_at: '2026-06-26T12:32:54.354Z'
+ updated_at: '2026-06-26T12:32:54.354Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -13609,8 +13683,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-06-24T14:18:39.534Z'
- updated_at: '2026-06-24T14:18:39.809Z'
+ created_at: '2026-06-26T12:32:54.668Z'
+ updated_at: '2026-06-26T12:32:54.947Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -13718,7 +13792,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-24T14:18:40.104Z'
+ starts_at: '2026-06-26T12:32:55.271Z'
expires_at:
usage_limit:
match_policy: all
@@ -13729,8 +13803,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-24T14:18:40.105Z'
- updated_at: '2026-06-24T14:18:40.106Z'
+ created_at: '2026-06-26T12:32:55.272Z'
+ updated_at: '2026-06-26T12:32:55.273Z'
action_ids: []
rule_ids: []
meta:
@@ -13837,7 +13911,7 @@ paths:
name: Black Friday
description:
code: blackfriday-os
- starts_at: '2026-06-24T14:18:41.021Z'
+ starts_at: '2026-06-26T12:32:56.261Z'
expires_at:
usage_limit:
match_policy: all
@@ -13848,8 +13922,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-24T14:18:41.022Z'
- updated_at: '2026-06-24T14:18:41.039Z'
+ created_at: '2026-06-26T12:32:56.263Z'
+ updated_at: '2026-06-26T12:32:56.286Z'
action_ids:
- pact_UkLWZg9DAJ
- pact_gbHJdmfrXB
@@ -14015,7 +14089,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-24T14:18:41.336Z'
+ starts_at: '2026-06-26T12:32:56.601Z'
expires_at:
usage_limit:
match_policy: all
@@ -14026,8 +14100,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-24T14:18:41.337Z'
- updated_at: '2026-06-24T14:18:41.338Z'
+ created_at: '2026-06-26T12:32:56.602Z'
+ updated_at: '2026-06-26T12:32:56.603Z'
action_ids: []
rule_ids: []
patch:
@@ -14124,7 +14198,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-06-24T14:18:42.211Z'
+ starts_at: '2026-06-26T12:32:57.586Z'
expires_at:
usage_limit:
match_policy: all
@@ -14135,8 +14209,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-06-24T14:18:42.212Z'
- updated_at: '2026-06-24T14:18:42.489Z'
+ created_at: '2026-06-26T12:32:57.592Z'
+ updated_at: '2026-06-26T12:32:57.907Z'
action_ids: []
rule_ids: []
requestBody:
@@ -14391,15 +14465,15 @@ paths:
label: Country
description:
preference_schema:
+ - key: country_id
+ type: integer
+ default:
- key: country_iso
type: string
default:
- key: country_isos
type: array
default: []
- - key: country_id
- type: integer
- default:
- type: currency
label: Currency
description:
@@ -14594,14 +14668,14 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-a489d1b733d2
+ transaction_id: BGS-62d02ba419a7
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
reimbursement_id:
metadata: {}
- created_at: '2026-06-24T14:18:08.970Z'
- updated_at: '2026-06-24T14:18:08.970Z'
+ created_at: '2026-06-26T12:32:24.395Z'
+ updated_at: '2026-06-26T12:32:24.395Z'
requestBody:
content:
application/json:
@@ -14620,6 +14694,48 @@ paths:
refund_reason_id:
type: string
description: Refund reason ID
+ "/api/v3/admin/locales":
+ get:
+ summary: List supported locales
+ tags:
+ - Settings
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: locales found
+ content:
+ application/json:
+ example:
+ data:
+ - code: de
+ name: de
+ default: false
+ rtl: false
+ - code: en
+ name: English
+ default: true
+ rtl: false
+ - code: fr
+ name: fr
+ default: false
+ rtl: false
"/api/v3/admin/store_credit_categories":
get:
summary: List store credit categories
@@ -14703,8 +14819,8 @@ paths:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-06-24T14:18:46.032Z'
- updated_at: '2026-06-24T14:18:46.032Z'
+ created_at: '2026-06-26T12:33:01.985Z'
+ updated_at: '2026-06-26T12:33:01.985Z'
non_expiring: false
meta:
page: 1
@@ -14798,8 +14914,8 @@ paths:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-06-24T14:18:46.361Z'
- updated_at: '2026-06-24T14:18:46.361Z'
+ created_at: '2026-06-26T12:33:02.281Z'
+ updated_at: '2026-06-26T12:33:02.281Z'
non_expiring: false
schema:
"$ref": "#/components/schemas/StoreCreditCategory"
@@ -14871,8 +14987,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-06-24T14:17:10.902Z'
- updated_at: '2026-06-24T14:18:46.969Z'
+ created_at: '2026-06-26T12:31:25.653Z'
+ updated_at: '2026-06-26T12:33:02.864Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -15150,8 +15266,8 @@ paths:
preferred_timezone: UTC
preferred_weight_unit: lb
preferred_unit_system: imperial
- created_at: '2026-06-24T14:17:10.902Z'
- updated_at: '2026-06-24T14:18:47.609Z'
+ created_at: '2026-06-26T12:31:25.653Z'
+ updated_at: '2026-06-26T12:33:03.477Z'
url: http://www.example.com:3000
supported_currencies:
- USD
@@ -15463,6 +15579,198 @@ paths:
code: invalid_taggable_type
message: taggable_type must be one of Spree::Product, Spree::Order,
Spree::LegacyUser
+ "/api/v3/admin/translatable_resources":
+ get:
+ summary: List translatable resources
+ tags:
+ - Settings
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.
+
+ **Required scope:** `read_settings` (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: translatable resources found
+ content:
+ application/json:
+ example:
+ data:
+ - resource_type: option_type
+ fields:
+ - key: label
+ type: string
+ readable: true
+ - resource_type: option_value
+ fields:
+ - key: label
+ type: string
+ readable: false
+ - resource_type: product
+ fields:
+ - key: name
+ type: string
+ - key: description
+ type: html
+ - key: slug
+ type: string
+ - key: meta_description
+ type: string
+ - key: meta_title
+ type: string
+ readable: true
+ - resource_type: category
+ fields:
+ - key: name
+ type: string
+ - key: pretty_name
+ type: string
+ - key: description
+ type: html
+ - key: permalink
+ type: string
+ readable: true
+ - resource_type: taxonomy
+ fields:
+ - key: name
+ type: string
+ readable: false
+ - resource_type: store
+ fields:
+ - key: name
+ type: string
+ - key: meta_description
+ type: string
+ - key: meta_keywords
+ type: string
+ - key: seo_title
+ type: string
+ - key: customer_support_email
+ type: string
+ - key: address
+ type: string
+ - key: contact_phone
+ type: string
+ readable: false
+ - resource_type: policy
+ fields:
+ - key: name
+ type: string
+ - key: body
+ type: html
+ readable: false
+ "/api/v3/admin/translations/batch":
+ post:
+ summary: Batch upsert translations
+ tags:
+ - Settings
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.
+
+ **Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: translations upserted
+ content:
+ application/json:
+ example:
+ data:
+ - resource_id: opt_UkLWZg9DAJ
+ resource_type: option_type
+ translations:
+ de:
+ label: Größe
+ translated_field_count: 1
+ fr:
+ label:
+ translated_field_count: 0
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
+ - resource_id: optval_UkLWZg9DAJ
+ resource_type: option_value
+ translations:
+ de:
+ label: Klein
+ translated_field_count: 1
+ fr:
+ label:
+ translated_field_count: 0
+ default_locale: en
+ supported_locales:
+ - de
+ - en
+ - fr
+ '422':
+ description: unsupported locale rolls back the whole batch
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: 'Unsupported locale(s): es'
+ details:
+ translations:
+ '0':
+ - 'Unsupported locale(s): es'
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - translations
+ properties:
+ translations:
+ type: array
+ items:
+ type: object
+ required:
+ - resource_type
+ - resource_id
+ - values
+ properties:
+ resource_type:
+ type: string
+ description: Translatable resource type token, e.g. `option_type`
+ resource_id:
+ type: string
+ description: Prefixed id of the record
+ values:
+ type: object
+ description: 'Map of locale code to { field: value }'
+ additionalProperties:
+ type: object
+ additionalProperties: true
"/api/v3/admin/admin_users":
get:
summary: List staff
@@ -15509,13 +15817,13 @@ paths:
example:
data:
- id: admin_UkLWZg9DAJ
- first_name: Raphael
- last_name: Prohaska
- full_name: Raphael Prohaska
+ first_name: Victor
+ last_name: Kihn
+ full_name: Victor Kihn
selected_locale:
- created_at: '2026-06-24T14:17:11.228Z'
- updated_at: '2026-06-24T14:17:11.228Z'
+ created_at: '2026-06-26T12:31:25.992Z'
+ updated_at: '2026-06-26T12:31:25.992Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -15576,13 +15884,13 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
- first_name: Idalia
- last_name: Glover
- full_name: Idalia Glover
+ first_name: Frank
+ last_name: Brown
+ full_name: Frank Brown
selected_locale:
- created_at: '2026-06-24T14:17:11.606Z'
- updated_at: '2026-06-24T14:17:11.606Z'
+ created_at: '2026-06-26T12:31:26.462Z'
+ updated_at: '2026-06-26T12:31:26.462Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -15638,13 +15946,13 @@ paths:
application/json:
example:
id: admin_UkLWZg9DAJ
first_name: Renamed
- last_name: Streich
- full_name: Renamed Streich
+ last_name: Adams
+ full_name: Renamed Adams
selected_locale:
- created_at: '2026-06-24T14:17:11.887Z'
- updated_at: '2026-06-24T14:17:11.903Z'
+ created_at: '2026-06-26T12:31:26.751Z'
+ updated_at: '2026-06-26T12:31:26.769Z'
roles:
- id: role_UkLWZg9DAJ
name: admin
@@ -15755,15 +16063,15 @@ paths:
example:
data:
- id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-06-24T14:17:46.688Z'
- updated_at: '2026-06-24T14:17:46.688Z'
- expires_at: '2026-07-08T14:17:46.685Z'
+ created_at: '2026-06-26T12:32:02.362Z'
+ updated_at: '2026-06-26T12:32:02.362Z'
+ expires_at: '2026-07-10T12:32:02.347Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=dzH2dSNttxHDgHeC2qJBiTks"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=LgUYjpfzkL5v2LP65tuRc953"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -15827,13 +16135,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-06-24T14:17:46.991Z'
- updated_at: '2026-06-24T14:17:46.991Z'
- expires_at: '2026-07-08T14:17:46.989Z'
+ created_at: '2026-06-26T12:32:02.704Z'
+ updated_at: '2026-06-26T12:32:02.704Z'
+ expires_at: '2026-07-10T12:32:02.701Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=h8htwquQFrL8TdKMEFdmNNTe"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=dZASM2gfQsGs3oT8tzRUSbwk"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -15946,15 +16254,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-06-24T14:17:47.556Z'
- updated_at: '2026-06-24T14:17:47.556Z'
- expires_at: '2026-07-08T14:17:47.553Z'
+ created_at: '2026-06-26T12:32:03.317Z'
+ updated_at: '2026-06-26T12:32:03.317Z'
+ expires_at: '2026-07-10T12:32:03.315Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=b4byJezY2wySnRe9qKvGzDBC"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=P91eEo4XeZX2C98UeRFbbKiM"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -16006,8 +16314,8 @@ paths:
data:
- id: role_UkLWZg9DAJ
name: admin
- created_at: '2026-06-24T14:18:43.386Z'
- updated_at: '2026-06-24T14:18:43.386Z'
+ created_at: '2026-06-26T12:32:58.873Z'
+ updated_at: '2026-06-26T12:32:58.873Z'
meta:
page: 1
limit: 25
@@ -16123,14 +16431,14 @@ paths:
example:
data:
- id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_47
+ state_abbr: STATE_ABBR_48
name: Brooklyn warehouse
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_47
+ state_text: STATE_ABBR_48
admin_name:
address2:
state_name:
@@ -16145,8 +16453,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-06-24T14:18:43.686Z'
- updated_at: '2026-06-24T14:18:43.686Z'
+ created_at: '2026-06-26T12:32:59.199Z'
+ updated_at: '2026-06-26T12:32:59.199Z'
meta:
page: 1
limit: 25
@@ -16260,8 +16568,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 30
pickup_instructions:
- created_at: '2026-06-24T14:18:44.266Z'
- updated_at: '2026-06-24T14:18:44.266Z'
+ created_at: '2026-06-26T12:33:00.025Z'
+ updated_at: '2026-06-26T12:33:00.025Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -16416,14 +16724,14 @@ paths:
application/json:
example:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_51
+ state_abbr: STATE_ABBR_52
name: Brooklyn warehouse
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_51
+ state_text: STATE_ABBR_52
admin_name:
address2:
state_name:
@@ -16438,8 +16746,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes:
pickup_instructions:
- created_at: '2026-06-24T14:18:44.557Z'
- updated_at: '2026-06-24T14:18:44.557Z'
+ created_at: '2026-06-26T12:33:00.428Z'
+ updated_at: '2026-06-26T12:33:00.428Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'404':
@@ -16506,14 +16814,14 @@ paths:
application/json:
example:
id: sloc_UkLWZg9DAJ
- state_abbr: STATE_ABBR_53
+ state_abbr: STATE_ABBR_54
name: Renamed warehouse
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
country_iso: US
country_name: United States of America
- state_text: STATE_ABBR_53
+ state_text: STATE_ABBR_54
admin_name:
address2:
state_name:
@@ -16528,8 +16836,8 @@ paths:
pickup_stock_policy: local
pickup_ready_in_minutes: 45
pickup_instructions:
- created_at: '2026-06-24T14:18:45.137Z'
- updated_at: '2026-06-24T14:18:45.427Z'
+ created_at: '2026-06-26T12:33:01.126Z'
+ updated_at: '2026-06-26T12:33:01.406Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -16737,7 +17045,7 @@ paths:
data:
- id: variant_UkLWZg9DAJ
product_id: prod_UkLWZg9DAJ
- sku: SKU-97
+ sku: SKU-98
options_text: ''
track_inventory: true
media_count: 0
@@ -16769,16 +17077,16 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-24T14:18:49.092Z'
- updated_at: '2026-06-24T14:18:49.111Z'
+ created_at: '2026-06-26T12:33:05.806Z'
+ updated_at: '2026-06-26T12:33:05.816Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 795595
+ product_name: Product 794854
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-98
+ sku: SKU-99
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -16786,10 +17094,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 135.1
- height: 105.16
- width: 172.67
- depth: 167.81
+ weight: 50.88
+ height: 116.8
+ width: 96.16
+ depth: 111.27
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -16812,8 +17120,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:18:49.134Z'
- updated_at: '2026-06-24T14:18:49.134Z'
+ created_at: '2026-06-26T12:33:05.831Z'
+ updated_at: '2026-06-26T12:33:05.831Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -16822,13 +17130,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-24T14:18:49.130Z'
- updated_at: '2026-06-24T14:18:49.146Z'
+ created_at: '2026-06-26T12:33:05.828Z'
+ updated_at: '2026-06-26T12:33:05.841Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 795595
+ product_name: Product 794854
meta:
page: 1
limit: 25
@@ -16940,8 +17248,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:18:49.858Z'
- updated_at: '2026-06-24T14:18:49.858Z'
+ created_at: '2026-06-26T12:33:06.549Z'
+ updated_at: '2026-06-26T12:33:06.549Z'
metadata: {}
position: 3
cost_price:
@@ -16950,13 +17258,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-24T14:18:49.862Z'
- updated_at: '2026-06-24T14:18:49.864Z'
+ created_at: '2026-06-26T12:33:06.553Z'
+ updated_at: '2026-06-26T12:33:06.555Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 803559
+ product_name: Product 802613
'422':
description: validation error
content:
@@ -17136,7 +17444,7 @@ paths:
example:
id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-104
+ sku: SKU-105
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -17144,10 +17452,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 194.97
- height: 96.9
- width: 167.57
- depth: 166.29
+ weight: 10.6
+ height: 195.24
+ width: 165.59
+ depth: 196.73
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -17170,8 +17478,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:18:50.272Z'
- updated_at: '2026-06-24T14:18:50.272Z'
+ created_at: '2026-06-26T12:33:06.994Z'
+ updated_at: '2026-06-26T12:33:06.994Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -17180,13 +17488,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-24T14:18:50.270Z'
- updated_at: '2026-06-24T14:18:50.281Z'
+ created_at: '2026-06-26T12:33:06.991Z'
+ updated_at: '2026-06-26T12:33:07.004Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 82228
+ product_name: Product 823185
'404':
description: variant not found
content:
@@ -17268,10 +17576,10 @@ paths:
purchasable: true
in_stock: false
backorderable: true
- weight: 47.63
- height: 1.71
- width: 133.63
- depth: 195.79
+ weight: 50.28
+ height: 155.32
+ width: 195.83
+ depth: 57.91
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -17294,8 +17602,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-06-24T14:18:50.985Z'
- updated_at: '2026-06-24T14:18:50.985Z'
+ created_at: '2026-06-26T12:33:07.688Z'
+ updated_at: '2026-06-26T12:33:07.688Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -17304,13 +17612,13 @@ paths:
weight_unit: lb
dimensions_unit:
deleted_at:
- created_at: '2026-06-24T14:18:50.982Z'
- updated_at: '2026-06-24T14:18:51.309Z'
+ created_at: '2026-06-26T12:33:07.685Z'
+ updated_at: '2026-06-26T12:33:07.989Z'
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 847472
+ product_name: Product 845670
requestBody:
content:
application/json:
@@ -17559,9 +17867,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-24T14:18:51.740Z'
- updated_at: '2026-06-24T14:18:51.740Z'
- delivered_at: '2026-06-24T14:18:51.740Z'
+ created_at: '2026-06-26T12:33:08.439Z'
+ updated_at: '2026-06-26T12:33:08.439Z'
+ delivered_at: '2026-06-26T12:33:08.439Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
- id: whd_UkLWZg9DAJ
@@ -17577,9 +17885,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-24T14:18:51.739Z'
- updated_at: '2026-06-24T14:18:51.739Z'
- delivered_at: '2026-06-24T14:18:51.739Z'
+ created_at: '2026-06-26T12:33:08.438Z'
+ updated_at: '2026-06-26T12:33:08.438Z'
+ delivered_at: '2026-06-26T12:33:08.438Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
meta:
@@ -17682,9 +17990,9 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-24T14:18:52.373Z'
- updated_at: '2026-06-24T14:18:52.373Z'
- delivered_at: '2026-06-24T14:18:52.373Z'
+ created_at: '2026-06-26T12:33:14.630Z'
+ updated_at: '2026-06-26T12:33:14.630Z'
+ delivered_at: '2026-06-26T12:33:14.630Z'
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
'404':
@@ -17773,8 +18081,8 @@ paths:
event: order.created
data:
id: 1
- created_at: '2026-06-24T14:18:53.304Z'
- updated_at: '2026-06-24T14:18:53.304Z'
+ created_at: '2026-06-26T12:33:15.898Z'
+ updated_at: '2026-06-26T12:33:15.898Z'
delivered_at:
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks
@@ -17873,8 +18181,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-24T14:18:53.339Z'
- updated_at: '2026-06-24T14:18:53.339Z'
+ created_at: '2026-06-26T12:33:16.056Z'
+ updated_at: '2026-06-26T12:33:16.056Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -17969,10 +18277,10 @@ paths:
subscriptions:
- order.completed
disabled_reason:
- created_at: '2026-06-24T14:18:54.039Z'
- updated_at: '2026-06-24T14:18:54.039Z'
+ created_at: '2026-06-26T12:33:17.122Z'
+ updated_at: '2026-06-26T12:33:17.122Z'
disabled_at:
- secret_key: f342021f0b23db9eaf3b71134af83c77f2a2a673473800122676c71819b686af
+ secret_key: 834a8a6e7467139f32085a9d8ce2903943c946b5c7dc3883fc5cdb8a63f2345a
last_delivery_at:
recent_delivery_count: 0
recent_failure_count: 0
@@ -18095,8 +18403,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-24T14:18:54.421Z'
- updated_at: '2026-06-24T14:18:54.421Z'
+ created_at: '2026-06-26T12:33:17.803Z'
+ updated_at: '2026-06-26T12:33:17.803Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -18175,8 +18483,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-24T14:18:55.267Z'
- updated_at: '2026-06-24T14:18:55.566Z'
+ created_at: '2026-06-26T12:33:18.664Z'
+ updated_at: '2026-06-26T12:33:18.946Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -18334,15 +18642,15 @@ paths:
response_body:
success:
payload:
- id: 29fba051-7f33-4a9c-bb1e-ff8ec470f8d2
+ id: 550cd4bd-1640-4028-8bac-11e52380d42d
name: webhook.test
- created_at: '2026-06-24T14:18:56Z'
+ created_at: '2026-06-26T12:33:19Z'
data:
message: This is a test webhook from Spree.
metadata:
spree_version: 5.5.0
- created_at: '2026-06-24T14:18:56.557Z'
- updated_at: '2026-06-24T14:18:56.557Z'
+ created_at: '2026-06-26T12:33:19.922Z'
+ updated_at: '2026-06-26T12:33:19.922Z'
delivered_at:
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks/orders
@@ -18408,8 +18716,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-06-24T14:18:56.700Z'
- updated_at: '2026-06-24T14:18:56.993Z'
+ created_at: '2026-06-26T12:33:19.950Z'
+ updated_at: '2026-06-26T12:33:20.226Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -18486,9 +18794,9 @@ paths:
- order.completed
- product.created
disabled_reason: Investigating
- created_at: '2026-06-24T14:18:57.055Z'
- updated_at: '2026-06-24T14:18:57.621Z'
- disabled_at: '2026-06-24T14:18:57.621Z'
+ created_at: '2026-06-26T12:33:20.258Z'
+ updated_at: '2026-06-26T12:33:20.537Z'
+ disabled_at: '2026-06-26T12:33:20.537Z'
secret_key:
last_delivery_at:
recent_delivery_count: 0
@@ -19166,6 +19474,8 @@ components:
type: array
items:
"$ref": "#/components/schemas/CustomField"
+ translations:
+ type: object
metadata:
type: object
pretty_name:
@@ -20295,6 +20605,8 @@ components:
type: number
kind:
type: string
+ translations:
+ type: object
metadata:
type: object
filterable:
@@ -21074,6 +21386,8 @@ components:
allOf:
- "$ref": "#/components/schemas/PriceHistory"
nullable: true
+ translations:
+ type: object
status:
type: string
metadata:
diff --git a/docs/plans/5.5-6.0-resource-translations-api.md b/docs/plans/5.5-6.0-resource-translations-api.md
new file mode 100644
index 0000000000..0e65328441
--- /dev/null
+++ b/docs/plans/5.5-6.0-resource-translations-api.md
@@ -0,0 +1,376 @@
+# Resource Translations — Admin API & Dashboard
+
+**Status:** Draft
+**Target:** Spree 5.5 (Phase 1 API) → 6.0 (staleness + bulk + metafields fold-in)
+**Depends on:** Mobility / `Spree::TranslatableResource` (shipped), Markets (locale config, shipped), Admin API v3 (shipped), `5.4-centralized-translations-admin.md`, `5.4-metafield-translations.md`
+**Author:** Damian + Claude
+**Last updated:** 2026-06-24
+
+## Summary
+
+Spree stores translations via Mobility (table backend, one `*_translations` row per `(record_id, locale)`), and **reads are already locale-aware** — the Store/Admin serializers return the value for `Mobility.locale`, which `Spree::Api::V3::LocaleAndCurrency` resolves from the `x-spree-locale` header. What is missing is a **write** path in the API v3 and a way for the React dashboard to **manage all locales at once**. Today the only translation-editing UI is the legacy Rails admin `TranslationsController` (Turbo drawer, Mobility locale accessors like `name_fr=`).
+
+This plan adds translation management to the **Admin API v3** and the **`@spree/dashboard` SPA**, covering every model in the `Spree.translatable_resources` registry (`Product`, `Taxon`/category, `Taxonomy`, `OptionType`, `OptionValue`, `Store`, `Policy` — and later `MetafieldDefinition`/`Metafield`). After comparing Shopify, Vendure, Medusa, and Saleor, **writes go through a single atomic batch endpoint** (`POST /admin/translations/batch`, a flat list of per-record `{ locale → { field → value } }` writes — so one request saves an option type **and** all its values together), while **reads** are a registry-driven, read-only per-resource matrix (`GET …/:id/translations`, with nested translatable children) plus an opt-in **`?expand=translations`**. Backed by **self-describing field discovery** and **server-side, advisory staleness** (Shopify's idea minus its mandatory-digest footgun).
+
+## How competitors do it (and what we take)
+
+| Platform | Write shape | Read shape | Field discovery | Staleness | Locale model |
+|---|---|---|---|---|---|
+| **Shopify** | Dedicated `translationsRegister` (per field+locale, batched per resource) | `translatableResource` (all locales + source + digest); storefront via `@inContext` | `translatableContent` enumerates keys + `type` | **Hard digest** (SHA-256 of sanitized source; required on every write) | `shopLocales` (primary + published) |
+| **Vendure** | **Embedded** `translations: [{ languageCode, … }]` on entity create/update; upsert by `languageCode`, omit-to-leave-alone, never implicit-delete | Dual: active-locale value at top level **and** sibling `translations` array | Schema-declared (`LocaleString` fields + `XTranslationInput`) | **None** | `availableLanguages` (global) + per-channel `defaultLanguageCode`/`availableLanguageCodes` |
+| **Medusa v2** | Dedicated Translation Module; `{ reference, reference_id, locale_code, translations: {field→value} }` (one locale per row, JSON bag of fields) | Read-time **overlay** onto native fields; locale via `?locale=` / `x-medusa-locale`; `GET /store/locales` discovery | Model `.translatable()` + admin Settings toggles | **None** (only `translated_field_count`) | `Locale` rows + store-level active set |
+| **Saleor** | **Per-resource** `productTranslate(id, languageCode, input)` — one resource, one language, many fields | Inline `translation(languageCode:)` returns a `*Translation` object beside default fields | `*TranslatableContent` types + top-level `translations(kind:)` enumeration | **None** | Global `LanguageCodeEnum`; no per-store allowlist |
+
+**Decisions distilled from the matrix:**
+
+- **Use the `{ locale → { field → value } }` object shape** Vendure pioneered (but as an object, not an array — Mobility stores per-field, so a single field can be written without resending the row). It rides on the dedicated endpoint, not embedded in the resource update.
+- **Take Shopify/Medusa's dedicated endpoint** for standalone/per-resource and coverage workflows — but make it **one generic controller** resolved from the registry (Saleor's per-resource explosion is the cautionary tale; we already have a generic legacy `TranslationsController` proving the pattern). **Cross-record bulk stays on CSV** (async import/export), not a JSON endpoint — no competitor ships a generic JSON bulk route and Spree already has the CSV machinery.
+- **Take Shopify's self-describing discovery** — fold it into the dedicated read, plus a registry endpoint, so the SPA renders editors and grid columns with **zero per-model code**.
+- **Take Shopify's staleness idea, drop its hard requirement** — track a source digest server-side, expose a `stale` flag, but **never require a digest on write** (client-side digest computation is a footgun; sanitizer differences make it unreproducible).
+- **Reuse markets for locales** — `supported_locales_list` (enabled) + `default_locale` (primary); no new `Locale` entity, no published/staged distinction in v1.
+
+## Key Decisions (do not deviate without discussion)
+
+1. **Single write surface: the batch endpoint.** All translation writes go through **`POST /api/v3/admin/translations/batch`** — a flat array of `{ resource_type, resource_id, values: { locale: { field } } }`, upserted atomically in one transaction via `TranslatableResource#upsert_translations` (a model method beside the existing readers — no service/DI). One entry = the degenerate single-resource case (a product); N entries = a multi-record save (an option type **plus** all its option values, in one atomic request). **Reads** are a separate, read-only per-resource matrix (`GET …/:id/translations`, with nested translatable children) plus an opt-in `?expand=translations`. **No per-resource write endpoint** — the dashboard's only write path is the batch endpoint, so a separate per-resource POST/DELETE would be pure redundancy (decided after the Medusa research: Medusa proves one atomic `{create/update/delete}`-style batch beats N per-resource requests; the multi-entity dual-save genuinely needs atomicity a per-resource endpoint can't give). **No embedded write** (3 of 4 competitors keep writes off the resource update). **Reject per-model translate controllers** (Saleor's verbosity). **Reject a JSON cross-record bulk endpoint distinct from this** — cross-*record* bulk is CSV import/export (§C); the batch endpoint is bounded (one editor's worth of entities), not a mass-import tool.
+2. **One generic `Spree::Api::V3::Admin::TranslationsController`**, mounted via a `:translatable` route concern (mirroring the existing `:custom_fieldable` concern), with the parent model resolved by `set_parent` and validated against `Spree.translatable_resources`. No per-model translation controllers.
+3. **Canonical payload shape is `{ locale → { field → value } }`.** This matches the `5.4-metafield-translations.md` plan's already-committed shape (`"translations": { "fr": { "value": … } }`), so metafields fold in as just-another-registered-resource later.
+4. **Upsert semantics: omit-to-leave-alone, never implicit-delete** (Vendure's confirmed contract). Locale absent → untouched. Field absent within a present locale → untouched (per-field partial PATCH). Field = `""` → write empty string (explicit clear; read falls back to source via `column_fallback`). Field = `null` → delete that field's translation cell. All of this flows through the single batch endpoint; there is no separate per-locale DELETE route.
+5. **Read symmetry is preserved and unchanged for the storefront.** The Store API continues to overlay the active-locale value onto the native field (`name`, `description`) via Mobility + `x-spree-locale` — **no parallel `name_translations` field on the storefront**. Only the **admin** gains an all-locales read and the write surfaces. Read and write use the **same field keys** everywhere (where a column is legacy-named, the model alias already bridges it — e.g. `OptionType#label`/`label=`).
+6. **Self-describing fields.** The dedicated read returns a `fields[]` array (`key` + `type` + `source`) so the SPA renders generically; plus a `GET /api/v3/admin/translatable_resources` registry endpoint for the no-record case (centralized page columns, tooling).
+7. **Locales come from markets.** Enabled = `current_store.supported_locales_list`; primary = `current_store.default_locale`; read-time selection = existing `x-spree-locale` resolution; missing-translation fallback = existing `column_fallback` + `store_based_fallbacks`. Writes to an unsupported locale return a typed `422` (à la Vendure's `LanguageNotAvailableError`), never a silent accept.
+8. **Staleness is server-side and advisory (Phase 2).** Store a `source_digest` per translation cell; compute `stale` at read time; **never require a digest on write**. Purely additive — does not break the Phase 1 contract.
+9. **OptionValue is its own translatable resource**, not a nested special-case of OptionType. It declares `TRANSLATABLE_FIELDS` and is in the registry, so it's writable via the batch endpoint and discoverable. For reads it's returned **inline as a child** of an option type's matrix (one editor fetches the type plus all its values in one request), so it needs no standalone read route. (The legacy admin special-cases OptionValue inside OptionType — we keep the one-request read but drop the special-casing in the write path.)
+10. **Feature is registry-driven, not hardcoded.** Adding a translatable model = add it to `Spree.translatable_resources` + declare `TRANSLATABLE_FIELDS`. No new controller, route, or serializer per model.
+11. **`translations` on GET is opt-in via `?expand=translations`**, never an always-on serializer attribute (the existing `CountrySerializer` `states`/`market` precedent). The matrix is costly (non-default locales × fields × joins) and unwanted on list/most-detail reads. `params[:expand]` is already in the HTTP cache key, so this is free and conventional. Expand returns values only; discovery metadata (`fields[]`/`source`/`type`) stays on the dedicated `…/:id/translations` endpoint.
+12. **Cross-record bulk is product-only and already covered by CSV.** In practice bulk translation matters for products; Spree already ships async product translation CSV import/export. Per-resource *editing* + discovery remain registry-generic (taxons, options, etc. translate via the API), but no new bulk surface is built for them in Phase 1 — generalizing CSV across the registry is a Phase 2 nicety, not a blocker.
+
+## Design Details
+
+### Locale resolution recap (already built — no change)
+
+`Spree::Api::V3::LocaleAndCurrency` resolves the request locale: `x-spree-locale` header → `params[:locale]` → `Spree::Current.locale` (market → store fallback), validated against `supported_locale?`. It sets `Mobility.locale` / `I18n.locale` and configures store fallbacks. The base `ResourceController#scope` already calls `.i18n` for translatable models. **Storefront reads need zero new work.**
+
+### The write API lives on `TranslatableResource` (not a service)
+
+The write mechanics belong on the model that already owns translation behavior — every translatable model includes `Spree::TranslatableResource`, which already declares `translatable_fields` and the `get_field_with_locale` reader. Two instance methods sit beside them, so no `ServiceModule` ceremony, no DI registration, and no `record.store` indirection (the model knows its own store). The earlier draft routed this through a `Spree::Translations::Upsert`/`DestroyLocale` service pair — collapsed into the model because each was a thin wrapper over a single operation called from one or two places.
+
+```ruby
+module Spree
+ module TranslatableResource
+ # ...existing reader + class methods...
+
+ # Omit-to-leave-alone; "" clears, nil deletes a cell. Field/locale filtering
+ # and validation happen here.
+ # @raise [ActiveRecord::RecordInvalid] on an unsupported locale or invalid save
+ def upsert_translations(values)
+ return self if values.blank?
+
+ validate_translation_locales!(values.keys)
+ allowed = self.class.translatable_fields.map(&:to_s)
+
+ transaction do
+ values.each do |locale, fields|
+ Mobility.with_locale(locale) do
+ fields.to_h.slice(*allowed).each { |field, value| public_send("#{field}=", value) }
+ end
+ end
+ save!
+ end
+ self
+ end
+
+ # Deletes the locale's translation row directly (a presence-validated field
+ # like Product#name would reject a nil-and-resave).
+ def destroy_locale_translation(locale)
+ rows = translations
+ rows = rows.with_deleted if rows.respond_to?(:with_deleted)
+ rows.where(locale: locale.to_s).delete_all
+ reload
+ self
+ end
+
+ private
+
+ def validate_translation_locales!(locales)
+ supported = translatable_store&.supported_locales_list || []
+ unsupported = locales.map(&:to_s) - supported.map(&:to_s)
+ return if unsupported.empty?
+
+ errors.add(:base, :unsupported_locale, message: "Unsupported locale(s): #{unsupported.join(', ')}")
+ raise ActiveRecord::RecordInvalid, self
+ end
+ end
+end
+```
+
+Both write paths call `record.upsert_translations(values)` and rescue `ActiveRecord::RecordInvalid` → `render_validation_error(e.record.errors)` (422). Value normalization (HTML sanitization, slug parameterization) stays on the model's own field writers — `upsert_translations` only routes values to them. No `Spree::Dependencies` entry: the behavior is on the model, overridable like any model method via a decorator.
+
+> **Note on rich text:** `Taxon#description` and `Policy#body` use the ActionText Mobility backend today. Translated HTML must be sanitized on write per the `6.0-rich-text-descriptions.md` plan. The `fields[].type == "html"` hint (below) tells both the serializer and the sanitizer how to treat the field.
+
+### A. Dedicated nested endpoint (contract of record)
+
+Route concern mirrors `:custom_fieldable`:
+
+```ruby
+# spree/api/config/routes.rb (Admin namespace)
+# Read-only — writes go through POST /translations/batch (decision #1).
+concern :translatable do
+ resources :translations, only: [:index], controller: 'translations'
+end
+
+resources :products, concerns: [:custom_fieldable, :translatable] do … end
+resources :categories, only: [:index, :show], concerns: [:custom_fieldable, :translatable]
+resources :option_types, concerns: [:custom_fieldable, :translatable]
+# Phase 1 mounts the read route on products, categories, and option_types only.
+# Other registered resources (option_value, taxonomy, store, policy) are still
+# writable via the batch endpoint; the discovery registry flags each entry with
+# `readable` so a client never GETs a matrix that isn't routed. Mounting their
+# read routes is a follow-up.
+```
+
+One generic controller:
+
+```ruby
+module Spree::Api::V3::Admin
+ # Generic translations controller. The parent model is resolved from the
+ # nested route and validated against Spree.translatable_resources. One
+ # controller serves every translatable model — no per-model subclasses.
+ class TranslationsController < ResourceController
+ before_action :set_parent
+ before_action :ensure_translatable!
+
+ # GET .../:parent/:parent_id/translations (read-only)
+ def index
+ render json: serialize_translations(parent_resource)
+ end
+
+ # Reads only. Per decision #1, the single write surface is
+ # POST /api/v3/admin/translations/batch — there is no per-resource
+ # create/update/destroy here.
+
+ private
+
+ def ensure_translatable!
+ raise ActiveRecord::RecordNotFound unless Spree.translatable_resources.include?(@parent.class)
+ end
+ end
+end
+```
+
+**`GET …/products/prod_86Rf07xd4z/translations`** — management read (all locales + source + discovery):
+
+```json
+{
+ "data": {
+ "resource_type": "product",
+ "resource_id": "prod_86Rf07xd4z",
+ "default_locale": "en",
+ "supported_locales": ["en", "de", "fr", "es"],
+ "fields": [
+ { "key": "name", "type": "string", "source": "Espresso Machine" },
+ { "key": "description", "type": "html", "source": "<p>Pulls a great shot.</p>" },
+ { "key": "slug", "type": "slug", "source": "espresso-machine" },
+ { "key": "meta_title", "type": "string", "source": "Espresso Machine | Acme" },
+ { "key": "meta_description", "type": "string", "source": "Buy the Acme espresso machine." }
+ ],
+ "translations": {
+ "de": { "name": "Espressomaschine", "description": "<p>Zieht…</p>", "slug": "espressomaschine", "meta_title": "Espressomaschine | Acme", "meta_description": "Kaufen…", "translated_field_count": 5 },
+ "fr": { "name": "Machine à espresso", "description": null, "slug": "machine-a-espresso", "meta_title": null, "meta_description": null, "translated_field_count": 2 },
+ "es": { "name": null, "description": null, "slug": null, "meta_title": null, "meta_description": null, "translated_field_count": 0 }
+ }
+ }
+}
+```
+
+`fields[].type` (`string` / `html` / `slug`) drives generic SPA rendering (plain input vs rich-text editor vs slug field). `translated_field_count` (Medusa's cheap completeness counter) drives progress bars on the centralized page.
+
+**`POST …/products/prod_86Rf07xd4z/translations`** — upsert:
+
+```json
+{
+ "translations": {
+ "fr": { "description": "<p>Tire un excellent shot.</p>", "meta_title": "Machine à espresso | Acme" },
+ "es": { "name": "Máquina de espresso", "slug": "maquina-de-espresso" }
+ }
+}
+```
+
+Response `200` echoes the `GET` shape. Validation errors (unsupported locale, invalid slug, sanitizer rejection) return standard v3 `422` keyed `translations.fr.slug` so `mapSpreeErrorsToForm` routes them inline.
+
+**`DELETE …/products/prod_86Rf07xd4z/translations/fr`** → `204`.
+
+### B. `?expand=translations` read on the resource (no embedded write)
+
+There is **no embedded write** — translations are written only through the dedicated `…/:id/translations` endpoint (§A). The research is decisive: 3 of 4 competitors (Shopify, Medusa, Saleor) keep translation writes on a separate surface; only Vendure embeds them in the resource update. Adding an embedded write meant a controller concern overriding `create`/`update` plus transaction-wrapping that interfered with other inline-nested writes (custom fields), for a convenience nothing in the SPA uses (the translations UI saves through the dedicated endpoint). Cut.
+
+The **read** side stays as a convenience: the admin `ProductSerializer` exposes a `translations` matrix attribute, opt-in via the existing `?expand=` convention (`CountrySerializer`'s `states`/`market` precedent), so a client can fetch the matrix alongside a product in one read without a second call.
+
+```ruby
+module Spree::Api::V3::Admin
+ class ProductSerializer < V3::ProductSerializer
+ attribute :translations, if: proc { expand?('translations') } do |product|
+ Spree::Translations.matrix_for(product) # { "de" => { "name" => …, "translated_field_count" => 5 }, … }
+ end
+ end
+end
+```
+
+**Why opt-in, not always-on:** the matrix is non-default-locales × translatable fields × translation-table joins — wasteful on list views and detail views that don't edit translations. `params[:expand]` is already part of the HTTP cache key, so expanded and non-expanded responses cache separately for free. **Store serializers never get `translations`** — customers see only the resolved active-locale value.
+
+**Expand returns values only; the dedicated endpoint returns values + discovery.** `?expand=translations` returns just `{ locale → { field → value } }`. The discovery metadata (`fields[]` with `key`/`type`/`source`, `supported_locales`) lives **only** on `GET …/:id/translations` (§A) — that's what the dashboard editor consumes, since it needs `source` + `type` to render fields generically.
+
+### C. Bulk = CSV import/export (generalized), not a JSON bulk endpoint
+
+**Decision: no dedicated JSON bulk-write endpoint.** It would be redundant and the weaker tool. The bulk story is two things, neither of which is a new synchronous JSON route:
+
+1. **True bulk = CSV import/export, generalized across the registry.** A slug/identifier-keyed CSV importer + exporter, run async (background `Spree::Import`/`Spree::Export` job), is already the right shape for "translate 500 products across 6 locales" — and it's the channel the `5.4-centralized-translations-admin.md` plan already commits to.
+2. **Coverage read = a thin GET** the centralized grid needs to render `✓/—` cells — cheap, and not redundant with import.
+
+**Why no JSON bulk endpoint:**
+- **CSV already covers it, async.** A synchronous JSON `POST …/bulk` over hundreds of records × locales is a timeout/partial-failure hazard; the existing `Spree::Import` runs in the background and reports per-row errors — strictly better for the actual bulk job.
+- **No competitor validates a generic cross-resource JSON bulk endpoint.** Shopify (`translationsRegister`), Vendure (embedded array), and Medusa all write **one resource per call**. Saleor reluctantly added `productBulkTranslate` *only* to amortize GraphQL round-trips — still product-only, one language per entry, never generic/cross-resource. REST + the registry-driven per-resource endpoint (§A) doesn't have the round-trip problem that forced Saleor's hand.
+- **The per-resource endpoint (§A) already batches** multi-locale + multi-field in one call. The genuinely different shape — many *records* at once — is the CSV job's job.
+
+**The real gap to close (Phase 2):** Spree's CSV import/export exists for **products only** (`Spree::Imports/Exports::ProductTranslations`, slug-keyed, fields `name`/`description`/`meta_title`/`meta_description`). There is no taxon/option-type/policy/store translation importer. Generalize the existing pattern across `Spree.translatable_resources`:
+- A registry-driven `Spree::Imports::ResourceTranslations` / `Spree::Exports::ResourceTranslations` parameterized by `resource_type`, keyed by the resource's natural identifier (slug/permalink/name), columns derived from `TRANSLATABLE_FIELDS` (one column per `field` × non-default `locale`, or a long format with a `locale` column as products do today).
+- Reuses the existing async `Spree::Import`/`Spree::Export` machinery, the admin `ExportsController`, and the import/export drawer plumbing (`5.5-admin-spa-csv-export.md`).
+- Keep the existing `ProductTranslations` types working (back-compat) or fold them into the generic one.
+
+**Coverage read (keep — drives the grid):**
+
+**`GET /api/v3/admin/translations?resource_type=product&q[…]&page=1`** — paginated coverage matrix (single `array_agg(locale)` query, no per-row N+1 — replaces the legacy `ProductTranslationsController#build_translated_locales_map`):
+
+```json
+{
+ "data": {
+ "resource_type": "product",
+ "default_locale": "en",
+ "locales": ["de", "fr", "es"],
+ "coverage": [
+ { "locale": "de", "translated": 36, "total": 36, "coverage": 1.0 },
+ { "locale": "fr", "translated": 34, "total": 36, "coverage": 0.94 },
+ { "locale": "es", "translated": 0, "total": 36, "coverage": 0.0 }
+ ],
+ "records": [
+ { "id": "prod_86Rf07xd4z", "name": "Espresso Machine", "locales": { "de": true, "fr": true, "es": false } },
+ { "id": "prod_9aKd21mn7p", "name": "Drip Coffee Maker", "locales": { "de": true, "fr": false, "es": false } }
+ ]
+ },
+ "meta": { "total_count": 36, "total_pages": 2, "page": 1 }
+}
+```
+
+Inline grid edits (e.g. "fill the missing `es` name on this row") write through the per-resource endpoint (§A), one record at a time — the user is already looking at that row. Mass fills go through CSV.
+
+### Discovery endpoints
+
+**`GET /api/v3/admin/translatable_resources`** — the registry made public (drives centralized-page columns + tooling, no record needed):
+
+```json
+{
+ "data": [
+ { "resource_type": "product", "fields": [ {"key":"name","type":"string"}, {"key":"description","type":"html"}, {"key":"slug","type":"slug"}, {"key":"meta_title","type":"string"}, {"key":"meta_description","type":"string"} ] },
+ { "resource_type": "category", "fields": [ {"key":"name","type":"string"}, {"key":"description","type":"html"}, {"key":"permalink","type":"slug"} ] },
+ { "resource_type": "option_type", "fields": [ {"key":"presentation","type":"string"} ] },
+ { "resource_type": "option_value", "fields": [ {"key":"presentation","type":"string"} ] },
+ { "resource_type": "taxonomy", "fields": [ {"key":"name","type":"string"} ] },
+ { "resource_type": "store", "fields": [ {"key":"name","type":"string"}, {"key":"seo_title","type":"string"} ] },
+ { "resource_type": "policy", "fields": [ {"key":"name","type":"string"}, {"key":"body","type":"html"} ] }
+ ]
+}
+```
+
+Derived from `Spree.translatable_resources.map { |k| [k, k.translatable_fields] }` plus a small `type` inference (`html` for `description`/`body`, `slug` for `slug`/`permalink`, else `string`).
+
+**`GET /api/v3/locales`** (Store) and **`GET /api/v3/admin/locales`** (Admin) — so clients enumerate instead of hardcoding (Medusa's `GET /store/locales`):
+
+```json
+{
+ "data": [
+ { "code": "en", "name": "English", "default": true, "rtl": false },
+ { "code": "de", "name": "Deutsch", "default": false, "rtl": false },
+ { "code": "fr", "name": "Français", "default": false, "rtl": false },
+ { "code": "ar", "name": "العربية", "default": false, "rtl": true }
+ ]
+}
+```
+
+Built from `supported_locales_list` + `default_locale`; names via the existing `Spree::LocaleHelper`.
+
+### Staleness (Phase 2 — additive)
+
+- Add a `source_digest` column to each `*_translations` table (or a shared mechanism in `TranslatableResource`). On each cell write, store `Digest::SHA256.hexdigest(current_source_value)` for that field.
+- Compute `stale = stored_source_digest != current_source_digest` at serialization time. Surface it in a **verbose** mode of the management read (`?include=staleness`), which enriches each value to an object — keeping the default flat `{ field → value }` shape simple for the common form path:
+
+```json
+"fr": {
+ "name": { "value": "Machine à espresso", "stale": true, "updated_at": "2026-01-10T…" },
+ "slug": { "value": "machine-a-espresso", "stale": false, "updated_at": "2026-06-01T…" }
+}
+```
+
+- **Writes never send a digest.** Optionally support an advisory `If-Source-Digest` per-field guard (opt-in `409` on mismatch) for concurrency-sensitive tooling; default is accept-and-record. This gives Spree Shopify's "outdated" UX without the mandatory-round-trip footgun, and beats Vendure/Saleor/Medusa's zero tracking.
+
+### React dashboard UX
+
+One API contract powers both surfaces (the `5.4-centralized-translations-admin.md` plan + the per-resource drawer):
+
+**Surface 1 — Per-resource translation editor: a full-page spreadsheet dialog** (opened from a "Translations" launcher card on the product edit page; **not** a side sheet like the legacy Rails admin). Modeled on Medusa's translations editor and our bulk-price editor dialog (`bulk-price-editor-dialog.tsx`):
+- A **locale dropdown** in the header (like the currency `Select` in the bulk price editor) picks one target locale at a time, showing its localized name (from `GET /admin/locales`).
+- A compact 3-column spreadsheet: **rows = translatable fields**, columns = `Field | Original (read-only source) | <selected locale>`. Editable cells are borderless `Textarea`s that fill the cell (true spreadsheet feel); `type: html` fields use the rich-text editor.
+- Edits **accumulate across locales** (switching the dropdown keeps pending edits) and persist in one `POST …/translations` with the full `{ locale → { field → value } }` matrix. Dirty count + discard-confirm in the header. 422s toast via `mapSpreeErrorsToForm`.
+- Fetches the matrix from the dedicated `GET …/:id/translations` (its own dirty-state/submit, independent of the product form). SDK calls go through a `useProductTranslations(id)` hook; query key includes `useStore().storeId` (per repo convention).
+
+**Surface 2 — Centralized Translations page** (under Products in the nav, per the existing plan):
+- Coverage grid powered by `GET /api/v3/admin/translations?resource_type=product` (one query). Phase 2 `stale` flags add an amber "outdated" cell state.
+- Bulk Import/Export reuse the existing CSV infra via the `ExportsController` + exports drawer (`5.5-admin-spa-csv-export.md`), generalized across the registry (§C). Inline single-row cell edits write through the per-resource endpoint (§A); mass fills go through CSV. **No JSON bulk endpoint.**
+- Clicking a row/cell deep-links to Surface 1 for that resource+locale.
+- Tabs per `resource_type` (Products → Categories → Options …) come **free** — the grid read is parameterized by `resource_type` and the column set comes from `GET /admin/translatable_resources`. Adding a tab is config, not code.
+
+All labels go through i18next across every language file in `packages/dashboard/src/locales/` and `packages/dashboard-core/src/locales/` (en/de/fr/zh-CN/ar/pl), per repo convention. Locale-name display reuses `GET /admin/locales`.
+
+## Migration Path
+
+**Phase 1 (5.5) — read-all + write, no staleness:**
+1. `TranslatableResource#upsert_translations` + `#destroy_locale_translation` (write API on the concern every translatable model already includes; no service/DI).
+2. `:translatable` route concern + generic `Spree::Api::V3::Admin::TranslationsController` (`index`/`create`/`destroy`).
+3. Promote `OptionValue` to its own nested translatable route (`…/option_types/:id/option_values/:id/translations`).
+4. (removed — no embedded write path.)
+5. `translations` `?expand` attribute on the admin serializers for registry members (extends store serializer, admin-only — never on store serializers).
+6. `GET /api/v3/admin/translatable_resources` + `GET /api/v3/{,admin/}locales` discovery endpoints + serializers.
+7. Integration specs (happy path + 422 for unsupported locale / invalid slug) to generate OpenAPI examples; controller specs for upsert/destroy semantics, locale/field allowlisting, authorization (CanCanCan `:update` on parent). Run the full type-generation pipeline (typelizer → zod → rswag) per CLAUDE.md.
+
+**Phase 2 (6.0) — bulk + staleness + SPA centralized page:**
+8. `GET /api/v3/admin/translations` coverage matrix; generalize CSV import/export across the registry (`Spree::Imports/Exports::ResourceTranslations`, parameterized by `resource_type`) — no JSON bulk endpoint.
+9. `source_digest` columns (data backfill via rake task, never in migration) + `stale` computation + `?include=staleness` verbose read.
+10. Dashboard: per-resource translation tab (Surface 1) + centralized Translations page (Surface 2) consuming the above.
+
+**Phase 3 (6.0) — fold in metafields:**
+11. Per `5.4-metafield-translations.md`, register `MetafieldDefinition` (translatable `name`) and `Metafield` (translatable `value`, text types only) in `Spree.translatable_resources`. They become just-another-registered-resource — the `{locale:{field}}` write shape that plan already committed to is a subset of this contract, so no new endpoint is needed.
+
+## Constraints on Current Work
+
+- **Never add a parallel `*_translations` field to a Store (customer-facing) serializer.** Storefront reads resolve to the active locale via Mobility — `translations` matrices are admin-only.
+- **Read/write field-name symmetry is mandatory.** A field exposed in the `translations` matrix under key `X` must be writable under key `X`. Legacy-named columns get a model-level alias (the OptionType `label`/`label=` precedent), never a controller/serializer/client-side mapper.
+- **When adding a translatable model**, add it to `Spree.translatable_resources` and declare `TRANSLATABLE_FIELDS`. Do **not** write a per-model translation controller, route, or serializer — the generic controller + registry handle it.
+- **Translate HTML fields safely:** translated `description`/`body` (and future RichText metafields) must be sanitized on write per `6.0-rich-text-descriptions.md`. Use the `fields[].type == "html"` hint.
+- **Validate locales at the store boundary, not per-record.** Writes to a locale outside `supported_locales_list` return `422`, never a silent accept.
+- **Do not require a digest on write** if/when staleness lands — it stays advisory.
+
+## Open Questions
+
+1. **Store translations route** — Store is a singleton in the SPA's store-scoped context; does its translation editor live under store settings (`…/settings/general/translations`) rather than a nested resource route? Likely yes; confirm the route shape.
+2. **Published vs enabled locales** — Shopify distinguishes published (buyer-visible) from enabled (translatable but staged). Spree has no such distinction; `supported_locales_list` = enabled = visible. If staging is later wanted, add a `published_locales` subset on Market — out of scope for v1; flagged, not built.
+3. **Per-market translation overrides** — Shopify allows a translation scoped to a single market (`marketId` on the translation). Spree's Mobility model is per-locale, not per-market. Defer unless a concrete need emerges; would require a schema change (market_id on translation rows).
+4. **Slug translation conflicts** — translated `slug`/`permalink` must stay unique within the store per locale; confirm the existing `TranslatableResourceSlug` + uniqueness handling covers API writes, and that a `422` surfaces cleanly.
+5. **Variant `name` / option_value generated presentations** — do generated/derived fields need translation, or only authored ones? Restrict to authored `TRANSLATABLE_FIELDS` for v1.
+6. **Generalized CSV schema** — when extending CSV import/export across the registry, pick the row format: long (one `locale` column, as products do today) vs wide (one column per `field`×`locale`). Long is simpler and matches the existing product importer; wide is friendlier for a translator editing one spreadsheet. And the join key per resource type (slug/permalink/name) — confirm each registry member has a stable, unique-per-store natural identifier for the CSV to key on.
+
+## References
+
+- `docs/plans/5.4-centralized-translations-admin.md` — centralized overview grid + CSV bulk (the dashboard Surface 2 this API powers); keep consistent.
+- `docs/plans/5.4-metafield-translations.md` — already commits to the `{locale:{field}}` write shape; folds in as Phase 3.
+- `docs/plans/6.0-rich-text-descriptions.md` — HTML sanitization for translated rich-text fields.
+- `docs/plans/6.0-replace-taxons-with-categories.md` — Taxon→Category naming for the category translatable resource.
+- Existing infra: `spree/core/app/models/concerns/spree/translatable_resource.rb`, `spree/admin/app/controllers/spree/admin/translations_controller.rb` (generic-controller + OptionValue-nesting template), `spree/core/lib/spree/core/engine.rb:245` (registry), `spree/api/app/controllers/concerns/spree/api/v3/locale_and_currency.rb` (locale resolution), `spree/api/config/routes.rb` (`:custom_fieldable` concern to mirror), `spree/core/app/models/concerns/spree/stores/markets.rb` (`supported_locales_list`/`default_locale`).
+- Competitor docs: Shopify `translationsRegister`/`translatableResource`; Vendure translatable guide + `translation-differ.ts`; Medusa v2 Translation Module (`docs.medusajs.com/resources/commerce-modules/translation`); Saleor translations API conventions.
diff --git a/packages/admin-sdk/.changeset/admin-translations-management.md b/packages/admin-sdk/.changeset/admin-translations-management.md
new file mode 100644
index 0000000000..4019577956
--- /dev/null
+++ b/packages/admin-sdk/.changeset/admin-translations-management.md
@@ -0,0 +1,5 @@
+---
+"@spree/admin-sdk": minor
+---
+
+Add translation management for translatable resources. `client.translatableResources.list()` discovers every translatable resource type, its translatable fields, and whether each one exposes a dedicated read route (`readable`); `client.locales.list()` returns the locales a merchant can translate content into for the current store. Per-resource reads are available via `client.products.translations.get(id)` and `client.optionTypes.translations.get(id)`, each returning the full locale × field matrix plus any nested translatable children (e.g. an option type's option values) in one request. All writes go through `client.translations.batch(entries)` — a single atomic endpoint that upserts translations across many records of any registered type, so an option type and all its option values can be translated in one save. New `Locale`, `TranslatableResource`, `TranslatableField`, `ResourceTranslations`, `ResourceTranslationsNode`, and `TranslationBatchEntry` types describe these shapes.
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index 209d7b476c..ef89a13761 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -165,6 +165,7 @@ import type {
GiftCardBatch,
Invitation,
LineItem,
+ Locale,
Market,
Media,
OptionType,
@@ -178,6 +179,8 @@ import type {
PromotionAction,
PromotionRule,
Refund,
+ ResourceTranslations,
+ ResourceTranslationsNode,
Role,
StockItem,
StockLocation,
@@ -186,6 +189,8 @@ import type {
StoreCredit,
StoreCreditCategory,
TaxCategory,
+ TranslatableResource,
+ TranslationBatchEntry,
Variant,
WebhookDelivery,
WebhookEndpoint,
@@ -269,6 +274,24 @@ export class AdminClient {
}
}
+ /**
+ * Builds a read-only `translations` accessor for a translatable parent
+ * resource. `get` returns the full matrix (source values + per-locale
+ * translations + nested translatable children). Writes go through
+ * `client.translations.batch(...)`, the single atomic write surface.
+ * @internal
+ */
+ private parentScopedTranslations(basePath: string) {
+ return {
+ get: (parentId: string, options?: RequestOptions): Promise<ResourceTranslations> =>
+ this.request<{ data: ResourceTranslations }>(
+ 'GET',
+ `${basePath}/${parentId}/translations`,
+ options,
+ ).then((r) => r.data),
+ }
+ }
+
/**
* Generic accessor for any custom-field-bearing resource. Use the
* first-class accessors (`client.products.customFields`, etc.) when
@@ -436,6 +459,38 @@ export class AdminClient {
this.request<Store>('PATCH', '/store', { ...options, body: params }),
}
+ /** The locales a merchant can translate content into for the current store. */
+ readonly locales = {
+ list: (options?: RequestOptions): Promise<Locale[]> =>
+ this.request<{ data: Locale[] }>('GET', '/locales', options).then((r) => r.data),
+ }
+
+ /** Every translatable resource type and its translatable fields (registry). */
+ readonly translatableResources = {
+ list: (options?: RequestOptions): Promise<TranslatableResource[]> =>
+ this.request<{ data: TranslatableResource[] }>(
+ 'GET',
+ '/translatable_resources',
+ options,
+ ).then((r) => r.data),
+ }
+
+ /**
+ * Translation writes that span multiple records (e.g. an option type plus
+ * all its option values) in one atomic request. Each entry names its own
+ * resource_type + resource_id; all succeed or none do.
+ */
+ readonly translations = {
+ batch: (
+ entries: TranslationBatchEntry[],
+ options?: RequestOptions,
+ ): Promise<ResourceTranslationsNode[]> =>
+ this.request<{ data: ResourceTranslationsNode[] }>('POST', '/translations/batch', {
+ ...options,
+ body: { translations: entries },
+ }).then((r) => r.data),
+ }
+
// ============================================
// Products
// ============================================
@@ -664,6 +719,8 @@ export class AdminClient {
},
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::Product']),
+
+ translations: this.parentScopedTranslations('/products'),
}
// ============================================
@@ -964,6 +1021,8 @@ export class AdminClient {
this.request<void>('DELETE', `/option_types/${id}`, options),
customFields: this.parentScopedCustomFields(CUSTOM_FIELD_OWNER_PATHS['Spree::OptionType']),
+
+ translations: this.parentScopedTranslations('/option_types'),
}
// ============================================
diff --git a/packages/admin-sdk/src/types/generated/Category.ts b/packages/admin-sdk/src/types/generated/Category.ts
index c900812204..d98e0ee5dc 100644
--- a/packages/admin-sdk/src/types/generated/Category.ts
+++ b/packages/admin-sdk/src/types/generated/Category.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 2a68628bc9ccd18fda78c94ec72a0039
+// Typelizer digest d6f9417c8877ac349d6c73e2fda11bb1
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {CustomField} from '@/types'
@@ -25,6 +25,7 @@ interface Category {
children?: Array<Category>;
ancestors?: Array<Category>;
custom_fields?: Array<CustomField>;
+ translations?: Record<string, Record<string, string | number | null>>;
metadata: Record<string, unknown>;
pretty_name: string;
lft: number;
diff --git a/packages/admin-sdk/src/types/generated/OptionType.ts b/packages/admin-sdk/src/types/generated/OptionType.ts
index 8fd0edfdc3..8888fa4e5b 100644
--- a/packages/admin-sdk/src/types/generated/OptionType.ts
+++ b/packages/admin-sdk/src/types/generated/OptionType.ts
@@ -1,4 +1,4 @@
-// Typelizer digest cf1a6f218cd866074bc2c46e5d506ef3
+// Typelizer digest 17914f500d22dc2715a4cb31604d0afd
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {OptionValue} from '@/types'
@@ -9,6 +9,7 @@ interface OptionType {
label: string;
position: number;
kind: string;
+ translations?: Record<string, Record<string, string | number | null>>;
metadata: Record<string, unknown>;
filterable: boolean;
created_at: string;
diff --git a/packages/admin-sdk/src/types/generated/Product.ts b/packages/admin-sdk/src/types/generated/Product.ts
index 8fa8ab1bb3..4f35a3c96f 100644
--- a/packages/admin-sdk/src/types/generated/Product.ts
+++ b/packages/admin-sdk/src/types/generated/Product.ts
@@ -1,4 +1,4 @@
-// Typelizer digest a3696537fb0f9c325efa658ecdf83f2d
+// Typelizer digest 47443a1c7df7c3bb43f46bd5e4ba940a
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
import type {Price, PriceHistory, Media, Variant, OptionType, OptionValue, Category, CustomField, ProductPublication, Channel} from '@/types'
@@ -32,6 +32,7 @@ interface Product {
categories?: Array<Category>;
custom_fields?: Array<CustomField>;
prior_price?: PriceHistory | null;
+ translations?: Record<string, Record<string, string | number | null>>;
status: string;
metadata: Record<string, unknown>;
deleted_at: string | null;
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index a1cf51c986..34dd47b913 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -66,3 +66,16 @@ export type { default as TaxCategory } from './generated/TaxCategory'
export type { default as Variant } from './generated/Variant'
export type { default as WebhookDelivery } from './generated/WebhookDelivery'
export type { default as WebhookEndpoint } from './generated/WebhookEndpoint'
+
+// Hand-written translation-management types (controller-shaped, not generated)
+export type {
+ Locale,
+ LocaleTranslations,
+ ResourceTranslations,
+ ResourceTranslationsNode,
+ TranslatableField,
+ TranslatableFieldType,
+ TranslatableResource,
+ TranslationBatchEntry,
+ TranslationsUpsertParams,
+} from './translations'
diff --git a/packages/admin-sdk/src/types/translations.ts b/packages/admin-sdk/src/types/translations.ts
new file mode 100644
index 0000000000..0bc4c8023c
--- /dev/null
+++ b/packages/admin-sdk/src/types/translations.ts
@@ -0,0 +1,80 @@
+/**
+ * Hand-written types for the translation management endpoints. These are
+ * controller-shaped responses (not Alba serializer output), so they are not
+ * part of the generated type set.
+ */
+
+/** Content kind of a translatable field, driving generic editor rendering. */
+export type TranslatableFieldType = 'string' | 'html'
+
+/** A translatable field with its source (default-locale) value. */
+export interface TranslatableField {
+ key: string
+ type: TranslatableFieldType
+ source: string | null
+}
+
+/**
+ * Translated values for one locale: a map of field key to value, plus a
+ * computed completeness counter. A field absent or null has no translation.
+ */
+export interface LocaleTranslations {
+ translated_field_count: number
+ [field: string]: string | number | null
+}
+
+/** Full translation matrix for a single resource (the dedicated endpoint). */
+export interface ResourceTranslations {
+ resource_type: string
+ resource_id: string
+ default_locale: string
+ supported_locales: string[]
+ fields: TranslatableField[]
+ translations: Record<string, LocaleTranslations>
+ /**
+ * Translatable child records nested under the parent (e.g. an option type
+ * carries its option values), so an editor fetches both in one read. Writes
+ * stay flat via the batch endpoint.
+ */
+ children?: ResourceTranslationsNode[]
+}
+
+/** A nested translation node (parent or child) — same shape minus locale meta. */
+export interface ResourceTranslationsNode {
+ resource_type: string
+ resource_id: string
+ fields: TranslatableField[]
+ translations: Record<string, LocaleTranslations>
+ children?: ResourceTranslationsNode[]
+}
+
+/** Upsert payload: locale => { field => value }. null deletes a cell. */
+export type TranslationsUpsertParams = Record<string, Record<string, string | null>>
+
+/** One entry in a batch translation upsert. */
+export interface TranslationBatchEntry {
+ resource_type: string
+ resource_id: string
+ values: TranslationsUpsertParams
+}
+
+/** A supported locale as returned by `GET /admin/locales`. */
+export interface Locale {
+ code: string
+ name: string
+ default: boolean
+ rtl: boolean
+}
+
+/** A translatable resource entry from `GET /admin/translatable_resources`. */
+export interface TranslatableResource {
+ resource_type: string
+ fields: Array<{ key: string; type: TranslatableFieldType }>
+ /**
+ * Whether this resource has a dedicated `…/:id/translations` read route.
+ * When `false` it is still writable via the batch endpoint and readable
+ * inline (e.g. option values are returned as children of an option type) —
+ * don't request a standalone matrix for it.
+ */
+ readable: boolean
+}
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index 1a6bdec2ec..073d36ad24 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/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, definition is admin-only (was `display_on: back_end`)"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_abbr":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., category, store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / category / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"category_id":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Spree::Exports::Products","Spree::Exports::Orders","Spree::Exports::Customers","Spree::Exports::ProductTranslations","Spree::Exports::GiftCards","Spree::Exports::CouponCodes","Spree::Exports::NewsletterSubscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true}}}}}}}},"/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":{}}}}}},"/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 shipment (tracking, shipping 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"},"selected_shipping_rate_id":{"type":"string"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[state_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_isos` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_isos":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_isos"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_isos` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_isos":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"special_instructions":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resume":{"patch":{"summary":"Resume a canceled order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a previously canceled order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices, no product_ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids to seed the list with."},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server alternative to `product_ids`: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)`. Mix-and-match with `product_ids` is supported but typically unnecessary — `prices` alone tells the server which variants belong to the list and what the override amount is.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids — reconciles list membership (adds + removes)."},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (taxon) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/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/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the roles available for staff role pickers. Roles are global, not per-store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_abbr":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the master variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["options"],"properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"Required. A variant created here is always non-master, so it must declare at least one option pair (e.g. size + color) or creation fails with 422. One pair per option type the variant participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_iso":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_name":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true}},"required":["id","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_iso","state_text","state_abbr","quick_checkout","is_default_billing","is_default_shipping","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"Adjustment":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"display_amount":{"type":"string"},"included":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","label","display_amount","included","created_at","updated_at","amount","order_id"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","roles"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"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","plaintext_token","created_by_email"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"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","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"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","code","active","default","preferred_order_routing_strategy","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":"object"},"updated_at":{"type":"object"}},"required":["iso","iso3","name","states_required","zipcode_required","created_at","updated_at"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"login":{"type":"string","nullable":true},"metadata":{"type":"object"},"last_sign_in_at":{"type":"string","nullable":true},"current_sign_in_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"sign_in_count":{"type":"number"},"failed_attempts":{"type":"number"},"last_sign_in_ip":{"type":"string","nullable":true},"current_sign_in_ip":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","login","metadata","last_sign_in_at","current_sign_in_at","created_at","updated_at","sign_in_count","failed_attempts","last_sign_in_ip","current_sign_in_ip","tags","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","code","created_at","updated_at"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","created_at","updated_at"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"type":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","type","format","created_at","updated_at","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"metadata":{"type":"object"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","number","tracking","tracking_url","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","items","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"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"},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","variant_id","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},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"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"},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"}},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}},"return_authorizations":{"type":"array","items":{"$ref":"#/components/schemas/ReturnAuthorization"}},"reimbursements":{"type":"array","items":{"$ref":"#/components/schemas/Reimbursement"}}},"required":["id","market_id","channel_id","number","email","customer_note","currency","locale","total_quantity","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","fulfillment_status","payment_status","completed_at","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","tags","internal_note","approver_id","canceler_id","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","amount","display_amount","status","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"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},"purchasable":{"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},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_category_id":{"type":"string","nullable":true},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","purchasable","in_stock","backorderable","available","description","description_html","default_variant_id","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","tax_category_id"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"reimbursement_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"},"reimbursement":{"$ref":"#/components/schemas/Reimbursement"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","reimbursement_id","metadata","created_at","updated_at"],"x-typelizer":true},"Reimbursement":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reimbursement_status":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"customer_return_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","reimbursement_status","total","order_id","customer_return_id","created_at","updated_at"],"x-typelizer":true},"ReturnAuthorization":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"return_authorization_reason_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","order_id","stock_location_id","return_authorization_reason_id","created_at","updated_at"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","created_at","updated_at"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"object"},"updated_at":{"type":"object"}},"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"},"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"url":{"type":"string"},"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","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","created_at","updated_at","url","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"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},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","thumbnail_url","purchasable","in_stock","backorderable","weight","height","width","depth","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","deleted_at","created_at","updated_at","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"payload":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","payload","created_at","updated_at","delivered_at","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
+{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, definition is admin-only (was `display_on: back_end`)"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_abbr":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., category, store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / category / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"category_id":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Spree::Exports::Products","Spree::Exports::Orders","Spree::Exports::Customers","Spree::Exports::ProductTranslations","Spree::Exports::GiftCards","Spree::Exports::CouponCodes","Spree::Exports::NewsletterSubscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true}}}}}}}},"/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":{}}}}}},"/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 shipment (tracking, shipping 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"},"selected_shipping_rate_id":{"type":"string"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[state_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_isos` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_isos":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_isos"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_isos` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_isos":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"special_instructions":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_iso":{"type":"string"},"state_abbr":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resume":{"patch":{"summary":"Resume a canceled order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a previously canceled order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/resend_confirmation":{"post":{"summary":"Resend confirmation email","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the order.completed event to trigger confirmation email delivery.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"confirmation resent","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods":{"get":{"summary":"List payment methods","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's configured payment methods. Use `source_required: true` to know which methods need a saved source.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment methods found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/types":{"get":{"summary":"List available payment provider types","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PaymentMethod subclasses that can be used to create new payment methods. Useful for populating a \"Provider\" dropdown in admin UIs.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"provider types found","content":{"application/json":{}}}}}},"/api/v3/admin/payment_methods/{id}":{"get":{"summary":"Show a payment method","tags":["Payment Methods"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a payment method by ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,type,active). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment method found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments":{"get":{"summary":"List payments","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all payments for an order.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payments found","content":{"application/json":{}}}}},"post":{"summary":"Create a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new payment for the order.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"payment created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_method_id"],"properties":{"payment_method_id":{"type":"string","description":"Payment method ID"},"amount":{"type":"string"},"source_id":{"type":"string","description":"Payment source ID"}}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}":{"get":{"summary":"Show a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific payment.\n\n**Required scope:** `read_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method, source). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,status,number,response_code). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"payment found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/capture":{"patch":{"summary":"Capture a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Captures a pending payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment captured","content":{"application/json":{}}},"422":{"description":"capture failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/orders/{order_id}/payments/{id}/void":{"patch":{"summary":"Void a payment","tags":["Payments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Voids a payment.\n\n**Required scope:** `write_payments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Payment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"payment voided","content":{"application/json":{}}}}}},"/api/v3/admin/price_lists":{"get":{"summary":"List price lists","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the price lists configured for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `price_rules`.","schema":{"type":"string"}}],"responses":{"200":{"description":"price lists found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft price list.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price list created (server-to-server — rules + prices, no product_ids)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids to seed the list with."},"rules":{"type":"array","description":"STI-typed price rules to attach on create. Existing rules on the same payload via PATCH reconcile by id.","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Server-to-server alternative to `product_ids`: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)`. Mix-and-match with `product_ids` is supported but typically unnecessary — `prices` alone tells the server which variants belong to the list and what the override amount is.","items":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/price_lists/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}},"404":{"description":"price list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a price list. The optional `rules:` array reconciles nested\nSTI-typed price rules in a single round-trip — existing rules update\nby `id`, new rules build, missing rules destroy. Mirrors the\npromotion editor's \"save the whole thing on Save\" pattern.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list updated with nested rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer"},"product_ids":{"type":"array","items":{"type":"string"},"description":"Prefixed product ids — reconciles list membership (adds + removes)."},"rules":{"type":"array","items":{"type":"object","required":["type"],"properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"prices":{"type":"array","description":"Individual price overrides (the spreadsheet payload). Each row updates by `id` if shipped, otherwise upserts on the unique key `(variant_id, currency, price_list_id)`.","items":{"type":"object","oneOf":[{"required":["id"]},{"required":["variant_id","currency"]}],"properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}},"delete":{"summary":"Delete a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price list. Associated prices are removed asynchronously.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price list deleted"}}}},"/api/v3/admin/price_lists/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transitions a draft / inactive list to `active`. If `starts_at` is\nin the future the list is marked `scheduled` instead, matching the\nlegacy admin behaviour.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/price_lists/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a price list","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price list deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PriceList"}}}}}}},"/api/v3/admin/prices":{"get":{"summary":"List prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Generic prices endpoint covering both base prices and price-list\noverrides. Filter with Ransack: `q[price_list_id_eq]=…`,\n`q[currency_eq]=USD`, `q[price_list_id_null]=true` (base prices only).\n\nThe admin spreadsheet uses this with server-side pagination so it\nscales past the metadata-PATCH path on `/price_lists/:id`.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[price_list_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[price_list_id_null]","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"q[currency_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Comma-separated sort keys. Supports e.g. `variant_product_name,variant_id`.","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `variant`.","schema":{"type":"string"}}],"responses":{"200":{"description":"prices found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a single price. Omit `price_list_id` to create a base price.\nFor more than a handful of rows, prefer `POST /admin/prices/bulk_upsert`.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"price created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","currency"],"properties":{"variant_id":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/prices/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"404":{"description":"price not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"price updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a price","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the price (acts_as_paranoid).\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"price deleted"}}}},"/api/v3/admin/prices/bulk_upsert":{"post":{"summary":"Bulk-upsert prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Upserts a batch of prices in a single SQL round trip.\n\nEach row either:\n* targets an existing price by `id`, OR\n* matches on the unique key `(variant_id, currency, price_list_id)` —\n updating the existing row if one exists, creating one otherwise.\n\nModel callbacks (e.g. PriceHistory) are bypassed; this is a\nbulk-write fast path for the admin spreadsheet. The response\ncarries `price_count` — the number of rows touched.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices upserted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}},"422":{"description":"missing prices key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prices"],"properties":{"prices":{"type":"array","items":{"type":"object","required":["variant_id","currency"],"properties":{"id":{"type":"string","nullable":true},"variant_id":{"type":"string"},"currency":{"type":"string"},"price_list_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/prices/bulk_destroy":{"delete":{"summary":"Bulk-delete prices","tags":["Pricing"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each price in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"prices deleted","content":{"application/json":{"schema":{"type":"object","properties":{"price_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields":{"get":{"summary":"List product custom fields","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the product's custom field values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom fields found","content":{"application/json":{}}}}},"post":{"summary":"Create a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets a custom field value on the product. Requires an existing CustomFieldDefinition; pass its prefixed `cfdef_…` id.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"custom field created","content":{"application/json":{}}},"422":{"description":"duplicate definition for the same product","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["custom_field_definition_id","value"],"properties":{"custom_field_definition_id":{"type":"string","description":"Prefixed `cfdef_…` id"},"value":{"description":"Value matching the definition's `field_type`"}}}}}}}},"/api/v3/admin/products/{product_id}/custom_fields/{id}":{"get":{"summary":"Show a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., custom_field_definition). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,value,namespace). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"custom field found","content":{"application/json":{}}}}},"patch":{"summary":"Update a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the custom field's `value`. The linked definition cannot be changed — delete and recreate to switch.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"custom field updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["value"],"properties":{"value":{"description":"New value"}}}}}}},"delete":{"summary":"Delete a product custom field","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"custom field deleted"}}}},"/api/v3/admin/products/{product_id}/translations":{"get":{"summary":"List product translations","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the full translation matrix for the product: the source value and content type per translatable field, plus the translated value for every supported locale.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations found","content":{"application/json":{}}}}}},"/api/v3/admin/products":{"get":{"summary":"List products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of products for the current store.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., name, -name, price, -price, best_selling)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new product. Supports nested variants with prices and option types.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}},"required":["name"]}}}}}},"/api/v3/admin/products/{id}":{"get":{"summary":"Get a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID (e.g., prod_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variants, media, option_types, categories). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,slug,price,status). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"product found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"200":{"description":"product updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["draft","active","archived"]},"tax_category_id":{"type":"string","description":"Tax category ID"},"category_ids":{"type":"array","items":{"type":"string"},"description":"Array of category IDs"},"tags":{"type":"array","items":{"type":"string"}},"prices":{"type":"array","description":"Shorthand for a simple (no-options) product: per-currency prices that forward to the product's sole variant. For products with options, set prices per variant under `variants:` instead.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"variants":{"type":"array","description":"Array of variant payloads. Variants can declare multiple option pairs via `options:` and per-currency prices via `prices:`. Stock counts go in `stock_items:` (per stock location).","items":{"type":"object","properties":{"sku":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}}}},"delete":{"summary":"Delete a product","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a product.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product deleted"}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (taxon) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/promotions/{promotion_id}/coupon_codes":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List coupon codes for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the auto-generated coupon codes for a multi-code promotion. Single-code promotions store the code on the promotion itself; this endpoint returns an empty list for them.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"coupon codes found","content":{"application/json":{}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List actions for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"actions found","content":{"application/json":{}}}}},"post":{"summary":"Create an action on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new action to a promotion. The `type` is the wire shorthand from `GET /promotion_actions/types` (e.g. `free_shipping`, `create_item_adjustments`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"action created","content":{"application/json":{}}},"422":{"description":"unknown action type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_actions/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Delete an action from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"action deleted"}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List rules for a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create a rule on a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new rule to a promotion. The `type` is the wire shorthand from `GET /promotion_rules/types` (e.g. `currency`, `item_total`, `product`). Fully-qualified Ruby class names are also accepted for backward compatibility.\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created with preferences","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/promotions/{promotion_id}/promotion_rules/{id}":{"parameters":[{"name":"promotion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a rule's preferences","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete a rule from a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/promotions":{"get":{"summary":"List promotions","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's promotions, including manual coupon and automatic promotions.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotions found","content":{"application/json":{}}}}},"post":{"summary":"Create a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new promotion. `code` is required for single-code coupon promotions;\npass `multi_codes: true` with `number_of_codes` to auto-generate a batch.\n\nRules and actions can be created in the same request by passing arrays of\n`{ type, preferences, ... }` rows. The server reconciles to the desired set:\nnew rows are built, existing rows (by `id`) are updated, omitted rows are removed.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"promotion created with rules and actions","content":{"application/json":{}}},"422":{"description":"invalid params","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"integer","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}},"required":["name"]}}}}}},"/api/v3/admin/promotions/{id}":{"get":{"summary":"Show a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"promotion found","content":{"application/json":{}}}}},"patch":{"summary":"Update a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a promotion. The `rules` and `actions` arrays are treated as\na *desired set* — rows with `id` update in place, rows without `id` are\nbuilt fresh, and any existing row not present in the array is destroyed.\nPass `rules: []` or `actions: []` to clear them.\n\n\n**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules and actions cleared with empty arrays","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"usage_limit":{"type":"integer","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"kind":{"type":"string","enum":["coupon_code","automatic"]},"promotion_category_id":{"type":"string","nullable":true},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"description":"Pass to update an existing rule; omit to build a new one"},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"product_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"customer_ids":{"type":"array","items":{"type":"string"}}},"required":["type"]}},"actions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"calculator":{"type":"object","properties":{"type":{"type":"string"},"preferences":{"type":"object","additionalProperties":true}}}},"required":["type"]}}}}}}}},"delete":{"summary":"Delete a promotion","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"promotion deleted"}}}},"/api/v3/admin/promotion_actions/types":{"get":{"summary":"List available promotion action types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionAction subclasses with their preference schemas. Used by admin UIs to populate the \"Add action\" picker and render generic preference forms.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"action types found","content":{"application/json":{}}}}}},"/api/v3/admin/promotion_rules/types":{"get":{"summary":"List available promotion rule types","tags":["Promotions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the registered Spree::PromotionRule subclasses with their preference schemas.\n\n**Required scope:** `read_promotions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule types found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all refunds for an order.\n\n**Required scope:** `read_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment, refund_reason). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,reason,transaction_id). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"refunds found","content":{"application/json":{}}}}},"post":{"summary":"Create a refund","tags":["Refunds"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a refund for a payment on the order. The refund is automatically processed via the payment gateway.\n\n**Required scope:** `write_refunds` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"refund created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["payment_id","amount"],"properties":{"payment_id":{"type":"string","description":"Payment ID"},"amount":{"type":"string"},"refund_reason_id":{"type":"string","description":"Refund reason ID"}}}}}}}},"/api/v3/admin/locales":{"get":{"summary":"List supported locales","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the locales a merchant can translate content into for the current store, with the default and right-to-left flags.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locales found","content":{"application/json":{}}}}}},"/api/v3/admin/store_credit_categories":{"get":{"summary":"List store credit categories","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured store credit categories. Categories classify\nstore credits (e.g., \"Goodwill\", \"Gift Card\", \"Refund\") and surface\nin the admin UI as a dropdown when issuing or editing a store\ncredit. Category names matching `Spree::Config[:non_expiring_credit_types]`\nare flagged via `non_expiring: true`.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditCategory"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credit_categories/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Store credit category ID","schema":{"type":"string"}}],"get":{"summary":"Get a store credit category","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single store credit category by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCreditCategory"}}}},"404":{"description":"store credit category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store":{"get":{"summary":"Get the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current store configuration. The store is resolved from the request context (host or admin selection); there is no `id` parameter.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current store","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the current store configuration.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"store updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Store"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"preferred_admin_locale":{"type":"string"},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_unit_system":{"type":"string"}}}}}}}},"/api/v3/admin/tags":{"get":{"summary":"List tags","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns tag names for a given taggable type. Used for autocomplete in tag inputs on products, orders, and customers.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"taggable_type","in":"query","required":true,"description":"Taggable type (`Spree::Product`, `Spree::Order`, or `Spree::User`)","schema":{"type":"string"}},{"name":"q","in":"query","required":false,"description":"Optional case-insensitive substring filter","schema":{"type":"string"}}],"responses":{"200":{"description":"tags found","content":{"application/json":{}}},"422":{"description":"invalid taggable type","content":{"application/json":{}}}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the roles available for staff role pickers. Roles are global, not per-store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_abbr":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_iso":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the master variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["options"],"properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"Required. A variant created here is always non-master, so it must declare at least one option pair (e.g. size + color) or creation fails with 422. One pair per option type the variant participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}}},"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"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"Address":{"type":"object","properties":{"id":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_name":{"type":"string"},"country_iso":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_abbr":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_name":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true}},"required":["id","first_name","last_name","full_name","address1","address2","postal_code","city","phone","company","country_name","country_iso","state_text","state_abbr","quick_checkout","is_default_billing","is_default_shipping","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"Adjustment":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"display_amount":{"type":"string"},"included":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","label","display_amount","included","created_at","updated_at","amount","order_id"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","roles"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"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","plaintext_token","created_by_email"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"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","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"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","code","active","default","preferred_order_routing_strategy","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":"object"},"updated_at":{"type":"object"}},"required":["iso","iso3","name","states_required","zipcode_required","created_at","updated_at"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"login":{"type":"string","nullable":true},"metadata":{"type":"object"},"last_sign_in_at":{"type":"string","nullable":true},"current_sign_in_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"sign_in_count":{"type":"number"},"failed_attempts":{"type":"number"},"last_sign_in_ip":{"type":"string","nullable":true},"current_sign_in_ip":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","login","metadata","last_sign_in_at","current_sign_in_at","created_at","updated_at","sign_in_count","failed_attempts","last_sign_in_ip","current_sign_in_ip","tags","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","code","created_at","updated_at"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","created_at","updated_at"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"type":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","type","format","created_at","updated_at","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"delivery_rates":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryRate"}},"metadata":{"type":"object"},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","number","tracking","tracking_url","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","items","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"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"},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}}},"required":["id","variant_id","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},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"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"},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"}},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"status":{"type":"string"},"last_ip_address":{"type":"string","nullable":true},"considered_risky":{"type":"boolean"},"confirmation_delivered":{"type":"boolean"},"store_owner_notification_delivered":{"type":"boolean"},"payment_total":{"type":"string"},"display_payment_total":{"type":"string"},"metadata":{"type":"object"},"canceled_at":{"type":"string","nullable":true},"approved_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferred_stock_location_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"adjustments":{"type":"array","items":{"$ref":"#/components/schemas/Adjustment"}},"return_authorizations":{"type":"array","items":{"$ref":"#/components/schemas/ReturnAuthorization"}},"reimbursements":{"type":"array","items":{"$ref":"#/components/schemas/Reimbursement"}}},"required":["id","market_id","channel_id","number","email","customer_note","currency","locale","total_quantity","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","fulfillment_status","payment_status","completed_at","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","tags","internal_note","approver_id","canceler_id","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","amount","display_amount","status","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"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},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tax_category_id":{"type":"string","nullable":true},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","purchasable","in_stock","backorderable","available","description","description_html","default_variant_id","thumbnail_url","tags","price","original_price","status","metadata","deleted_at","created_at","updated_at","tax_category_id"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"reimbursement_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"},"reimbursement":{"$ref":"#/components/schemas/Reimbursement"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","reimbursement_id","metadata","created_at","updated_at"],"x-typelizer":true},"Reimbursement":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reimbursement_status":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"customer_return_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","reimbursement_status","total","order_id","customer_return_id","created_at","updated_at"],"x-typelizer":true},"ReturnAuthorization":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"return_authorization_reason_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","order_id","stock_location_id","return_authorization_reason_id","created_at","updated_at"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","created_at","updated_at"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"object"},"updated_at":{"type":"object"}},"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"},"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"url":{"type":"string"},"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","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","created_at","updated_at","url","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"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},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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","thumbnail_url","purchasable","in_stock","backorderable","weight","height","width","depth","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","deleted_at","created_at","updated_at","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"payload":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","payload","created_at","updated_at","delivered_at","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
diff --git a/packages/cli/src/generated/resource-paths.json b/packages/cli/src/generated/resource-paths.json
index f59ec27cd6..720efb4a7a 100644
--- a/packages/cli/src/generated/resource-paths.json
+++ b/packages/cli/src/generated/resource-paths.json
@@ -1 +1 @@
-["/admin_users","/allowed_origins","/api_keys","/auth","/channels","/custom_field_definitions","/customer_groups","/customers","/exports","/gift_card_batches","/gift_cards","/invitations","/markets","/me","/option_types","/orders","/payment_methods","/price_lists","/prices","/products","/promotion_actions","/promotion_rules","/promotions","/roles","/stock_locations","/store","/store_credit_categories","/tags","/webhook_endpoints"]
\ No newline at end of file
+["/admin_users","/allowed_origins","/api_keys","/auth","/channels","/custom_field_definitions","/customer_groups","/customers","/exports","/gift_card_batches","/gift_cards","/invitations","/locales","/markets","/me","/option_types","/orders","/payment_methods","/price_lists","/prices","/products","/promotion_actions","/promotion_rules","/promotions","/roles","/stock_locations","/store","/store_credit_categories","/tags","/translatable_resources","/translations","/webhook_endpoints"]
\ No newline at end of file
diff --git a/packages/dashboard/e2e/option-type-translations.spec.ts b/packages/dashboard/e2e/option-type-translations.spec.ts
new file mode 100644
index 0000000000..696bc8a185
--- /dev/null
+++ b/packages/dashboard/e2e/option-type-translations.spec.ts
@@ -0,0 +1,45 @@
+import { expect, test } from '@playwright/test'
+import { gotoIndex, login } from './helpers'
+import { OPTIONS_PATH, seedOptionType } from './products-helpers'
+
+// The e2e store has a US (en) + Europe (de) market, so `de` is a non-default
+// translation locale and the translations editor renders.
+test.describe('option type + value translations', () => {
+ test('translates an option type and one of its values in one save', async ({ page }) => {
+ const creds = await login(page)
+ const label = await seedOptionType(page, creds.store_id, 'size', ['small', 'large'])
+
+ // Open the option type's edit sheet, then its translations editor.
+ await gotoIndex(page, OPTIONS_PATH(creds.store_id), /add option type/i)
+ await page.getByRole('button', { name: label }).click()
+ await page.getByRole('button', { name: /manage translations/i }).click()
+
+ // Scope to the translations modal (the option-type edit sheet stays open
+ // underneath, so a page-level dialog selector is ambiguous).
+ const dialog = page
+ .getByRole('dialog')
+ .filter({ has: page.getByRole('button', { name: /^save translations$/i }) })
+ await expect(dialog.getByText('Original', { exact: true })).toBeVisible({ timeout: 15_000 })
+
+ // Row 0 is the option type (field `label`); the value rows are labelled by
+ // their source ("Small", "Large").
+ const suffix = Date.now()
+ const typeDe = `Größe ${suffix}`
+ const valueDe = `Klein ${suffix}`
+ await dialog.getByLabel('label de').fill(typeDe)
+ await dialog.getByLabel('Small de').fill(valueDe)
+
+ // One Save batches both the type and the value.
+ await dialog.getByRole('button', { name: /^save translations$/i }).click()
+ await expect(page.getByText(/translations saved/i)).toBeVisible({ timeout: 15_000 })
+
+ // Reopen and confirm both persisted.
+ await dialog.getByRole('button', { name: /^close$/i }).click()
+ await page.getByRole('button', { name: /manage translations/i }).click()
+ const reopened = page
+ .getByRole('dialog')
+ .filter({ has: page.getByRole('button', { name: /^save translations$/i }) })
+ await expect(reopened.getByLabel('label de')).toHaveValue(typeDe, { timeout: 15_000 })
+ await expect(reopened.getByLabel('Small de')).toHaveValue(valueDe)
+ })
+})
diff --git a/packages/dashboard/e2e/products-translations.spec.ts b/packages/dashboard/e2e/products-translations.spec.ts
new file mode 100644
index 0000000000..4b2465a562
--- /dev/null
+++ b/packages/dashboard/e2e/products-translations.spec.ts
@@ -0,0 +1,63 @@
+import { expect, test } from '@playwright/test'
+import { login } from './helpers'
+import { createProduct } from './products-helpers'
+
+// The e2e store has a US/USD (default_locale en) market plus a Europe/EUR
+// (default_locale de) market (see global-setup), so `de` is available as a
+// non-default translation locale and the translations editor renders.
+test.describe('product translations', () => {
+ test('translates a product name into a non-default locale', async ({ page }) => {
+ const creds = await login(page)
+
+ const suffix = Date.now()
+ const name = `E2E Translatable ${suffix}`
+ await createProduct(page, creds.store_id, name)
+
+ // Open the full-page translations editor from the launcher card.
+ await page.getByRole('button', { name: /manage translations/i }).click()
+
+ // The editor shows the Field | Original | <locale> spreadsheet. The
+ // Original column shows the source value read-only.
+ const dialog = page.getByRole('dialog')
+ await expect(dialog.getByText('Original', { exact: true })).toBeVisible({ timeout: 15_000 })
+ await expect(dialog.getByTestId('source-name')).toContainText(name)
+
+ // Grid cell for the `name` field in the `de` locale column.
+ const translated = `Übersetzt ${suffix}`
+ await dialog.getByLabel('name de').fill(translated)
+ await dialog.getByRole('button', { name: /^save translations$/i }).click()
+
+ // Success toast confirms persistence (UI-only assertion).
+ await expect(page.getByText(/translations saved/i)).toBeVisible({ timeout: 15_000 })
+
+ // Reopen the editor and confirm the translated value persisted.
+ await page.getByRole('button', { name: /^close$/i }).click()
+ await page.getByRole('button', { name: /manage translations/i }).click()
+ await expect(page.getByRole('dialog').getByLabel('name de')).toHaveValue(translated, {
+ timeout: 15_000,
+ })
+ })
+
+ test('focusing a rich-text cell without typing does not mark the editor dirty', async ({
+ page,
+ }) => {
+ const creds = await login(page)
+ await createProduct(page, creds.store_id, `E2E RichText ${Date.now()}`)
+
+ await page.getByRole('button', { name: /manage translations/i }).click()
+ const dialog = page.getByRole('dialog')
+ await expect(dialog.getByText('Original', { exact: true })).toBeVisible({ timeout: 15_000 })
+
+ // Save is disabled while nothing is dirty.
+ const save = dialog.getByRole('button', { name: /^save translations$/i })
+ await expect(save).toBeDisabled()
+
+ // Click into the description (rich-text) cell — its editor emits `<p></p>`
+ // on mount/focus, which must NOT register as a change. Exact match so it
+ // doesn't also resolve `meta_description de`.
+ await dialog.getByLabel('description de', { exact: true }).click()
+
+ await expect(save).toBeDisabled()
+ await expect(dialog.getByText(/unsaved change/i)).toHaveCount(0)
+ })
+})
diff --git a/packages/dashboard/src/components/spree/products/option-type-translations-dialog.tsx b/packages/dashboard/src/components/spree/products/option-type-translations-dialog.tsx
new file mode 100644
index 0000000000..7fbf7e9a7a
--- /dev/null
+++ b/packages/dashboard/src/components/spree/products/option-type-translations-dialog.tsx
@@ -0,0 +1,42 @@
+import type { TranslatableField } from '@spree/admin-sdk'
+import { useTranslation } from 'react-i18next'
+import { ResourceTranslationsDialog } from '@/components/spree/translations/resource-translations-dialog'
+import { useOptionTypeTranslations } from '@/hooks/use-translations'
+
+interface OptionTypeTranslationsDialogProps {
+ optionTypeId: string
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}
+
+/**
+ * Option type translations editor — a thin adapter over the generic
+ * <ResourceTranslationsDialog>. Fetches the option type's translation matrix
+ * with its option values nested under `children`, so the dialog renders the
+ * type and all its values as rows and saves them in one batch.
+ */
+export function OptionTypeTranslationsDialog({
+ optionTypeId,
+ open,
+ onOpenChange,
+}: OptionTypeTranslationsDialogProps) {
+ const { t } = useTranslation()
+ const { data, isLoading, isError, refetch } = useOptionTypeTranslations(optionTypeId)
+
+ const fieldLabel = (resourceType: string, field: TranslatableField) =>
+ t([`admin.fields.${resourceType}.${field.key}.label`, `admin.fields.${field.key}.label`], {
+ defaultValue: field.key,
+ })
+
+ return (
+ <ResourceTranslationsDialog
+ open={open}
+ onOpenChange={onOpenChange}
+ data={data}
+ isLoading={isLoading}
+ isError={isError}
+ fieldLabel={fieldLabel}
+ onSaved={() => refetch()}
+ />
+ )
+}
diff --git a/packages/dashboard/src/components/spree/products/product-translations-card.tsx b/packages/dashboard/src/components/spree/products/product-translations-card.tsx
new file mode 100644
index 0000000000..d66013caa3
--- /dev/null
+++ b/packages/dashboard/src/components/spree/products/product-translations-card.tsx
@@ -0,0 +1,49 @@
+import { Button, Card, CardContent, CardHeader, CardTitle } from '@spree/dashboard-ui'
+import { LanguagesIcon } from 'lucide-react'
+import { useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { ProductTranslationsDialog } from '@/components/spree/products/product-translations-dialog'
+import { useProductTranslations } from '@/hooks/use-translations'
+
+/**
+ * Launcher card for the full-page translations editor. Shows how many target
+ * locales the product is translated into and opens the spreadsheet dialog. The
+ * editing itself lives in <ProductTranslationsDialog>, not inline here.
+ */
+export function ProductTranslationsCard({ productId }: { productId: string }) {
+ const { t } = useTranslation()
+ const [open, setOpen] = useState(false)
+ const { data } = useProductTranslations(productId)
+
+ const targetLocales = data ? data.supported_locales.filter((l) => l !== data.default_locale) : []
+ const translatedCount = targetLocales.filter(
+ (l) => (data?.translations[l]?.translated_field_count ?? 0) > 0,
+ ).length
+
+ return (
+ <Card>
+ <CardHeader className="flex flex-row items-center justify-between gap-3 space-y-0">
+ <CardTitle>{t('admin.translations.title')}</CardTitle>
+ {targetLocales.length > 0 && (
+ <Button type="button" size="sm" variant="outline" onClick={() => setOpen(true)}>
+ <LanguagesIcon />
+ {t('admin.translations.manage')}
+ </Button>
+ )}
+ </CardHeader>
+ <CardContent>
+ {targetLocales.length === 0 ? (
+ <p className="text-sm text-muted-foreground">{t('admin.translations.no_locales')}</p>
+ ) : (
+ <p className="text-sm text-muted-foreground">
+ {t('admin.translations.coverage_summary', {
+ translated: translatedCount,
+ total: targetLocales.length,
+ })}
+ </p>
+ )}
+ </CardContent>
+ <ProductTranslationsDialog productId={productId} open={open} onOpenChange={setOpen} />
+ </Card>
+ )
+}
diff --git a/packages/dashboard/src/components/spree/products/product-translations-dialog.tsx b/packages/dashboard/src/components/spree/products/product-translations-dialog.tsx
new file mode 100644
index 0000000000..be79242709
--- /dev/null
+++ b/packages/dashboard/src/components/spree/products/product-translations-dialog.tsx
@@ -0,0 +1,42 @@
+import type { TranslatableField } from '@spree/admin-sdk'
+import { useTranslation } from 'react-i18next'
+import { ResourceTranslationsDialog } from '@/components/spree/translations/resource-translations-dialog'
+import { useProductTranslations } from '@/hooks/use-translations'
+
+interface ProductTranslationsDialogProps {
+ productId: string
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}
+
+/**
+ * Product translations editor — a thin adapter over the generic
+ * <ResourceTranslationsDialog>: supplies the product's translation matrix and a
+ * product-scoped field-label resolver. The dialog handles the grid, locale
+ * switching, and the batched save.
+ */
+export function ProductTranslationsDialog({
+ productId,
+ open,
+ onOpenChange,
+}: ProductTranslationsDialogProps) {
+ const { t } = useTranslation()
+ const { data, isLoading, isError, refetch } = useProductTranslations(productId)
+
+ const fieldLabel = (_resourceType: string, field: TranslatableField) =>
+ t([`admin.fields.product.${field.key}.label`, `admin.fields.${field.key}.label`], {
+ defaultValue: field.key,
+ })
+
+ return (
+ <ResourceTranslationsDialog
+ open={open}
+ onOpenChange={onOpenChange}
+ data={data}
+ isLoading={isLoading}
+ isError={isError}
+ fieldLabel={fieldLabel}
+ onSaved={() => refetch()}
+ />
+ )
+}
diff --git a/packages/dashboard/src/components/spree/translations/resource-translations-dialog.tsx b/packages/dashboard/src/components/spree/translations/resource-translations-dialog.tsx
new file mode 100644
index 0000000000..014875947b
--- /dev/null
+++ b/packages/dashboard/src/components/spree/translations/resource-translations-dialog.tsx
@@ -0,0 +1,413 @@
+import {
+ type ResourceTranslations,
+ type ResourceTranslationsNode,
+ SpreeError,
+ type TranslatableField,
+ type TranslationBatchEntry,
+} from '@spree/admin-sdk'
+import { adminClient } from '@spree/dashboard-core'
+import {
+ Button,
+ cn,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogHeader,
+ DialogTitle,
+ RichTextEditor,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+ Skeleton,
+ Textarea,
+ useConfirm,
+} from '@spree/dashboard-ui'
+import { XIcon } from 'lucide-react'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { toast } from 'sonner'
+import { useLocales } from '@/hooks/use-translations'
+
+/** One editable row in the grid: a translatable entity (the resource itself or
+ * a nested child like an option value). */
+export interface TranslationRow {
+ resourceType: string
+ resourceId: string
+ /** Visual nesting depth (0 = root, 1 = child). */
+ indent: number
+ fields: TranslatableField[]
+ /** locale → field → stored value (null/absent = untranslated). */
+ translations: Record<string, Record<string, string | number | null>>
+ /** Optional override for the left-column label (e.g. a value's own label).
+ * When omitted the field's i18n label is used (single-field rows). */
+ rowLabel?: string
+}
+
+interface ResourceTranslationsDialogProps {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+ /** Translation matrix document (root, possibly with nested `children`). */
+ data?: ResourceTranslations
+ isLoading?: boolean
+ isError?: boolean
+ /** Resolves a field key to its display label (resource-specific i18n). */
+ fieldLabel: (resourceType: string, field: TranslatableField) => string
+ /** Called after a successful save so the parent can refetch. */
+ onSaved?: () => void
+}
+
+/** Edits keyed by `${resourceId}::${locale}::${field}` → value. */
+type EditMap = Map<string, string>
+const cellKey = (resourceId: string, locale: string, field: string) =>
+ `${resourceId}::${locale}::${field}`
+
+/**
+ * Generic full-page translations editor. Renders a flat list of translatable
+ * rows (the resource plus any nested children) as a spreadsheet — locale
+ * dropdown picks the target column, "Original" shows the source. Edits
+ * accumulate across locales and rows; one Save batches them into a single
+ * atomic `POST /admin/translations/batch`. Products are the degenerate case
+ * (rows are one resource's fields); option types add value rows of another
+ * resource type. Modeled on Medusa's editor + the bulk price dialog.
+ */
+export function ResourceTranslationsDialog({
+ open,
+ onOpenChange,
+ data,
+ isLoading,
+ isError,
+ fieldLabel,
+ onSaved,
+}: ResourceTranslationsDialogProps) {
+ const { t } = useTranslation()
+ const confirm = useConfirm()
+ const { data: locales } = useLocales()
+
+ const rows = useMemo(() => (data ? flattenTree(data) : []), [data])
+ const targetLocales = useMemo(
+ () => (data ? data.supported_locales.filter((l) => l !== data.default_locale) : []),
+ [data],
+ )
+
+ const [locale, setLocale] = useState('')
+ const [edits, setEdits] = useState<EditMap>(() => new Map())
+ const [saving, setSaving] = useState(false)
+
+ useEffect(() => {
+ if (open) {
+ setEdits(new Map())
+ setLocale('')
+ }
+ }, [open])
+
+ useEffect(() => {
+ if (!locale && targetLocales.length > 0) setLocale(targetLocales[0])
+ }, [locale, targetLocales])
+
+ const dirtyCount = edits.size
+ const localeName = useCallback(
+ (code: string) => locales?.find((l) => l.code === code)?.name ?? code,
+ [locales],
+ )
+
+ const handleOpenChange = useCallback(
+ async (next: boolean) => {
+ if (next || dirtyCount === 0) {
+ onOpenChange(next)
+ return
+ }
+ const ok = await confirm({
+ title: t('admin.translations.discard_confirm.title'),
+ message: t('admin.translations.discard_confirm.message', { count: dirtyCount }),
+ variant: 'destructive',
+ confirmLabel: t('admin.actions.discard_changes'),
+ })
+ if (ok) onOpenChange(false)
+ },
+ [dirtyCount, onOpenChange, confirm, t],
+ )
+
+ async function handleSave() {
+ if (edits.size === 0) return
+ // Group flat edits into one batch entry per (resourceType, resourceId).
+ const rowById = new Map(rows.map((r) => [r.resourceId, r]))
+ const byResource = new Map<string, TranslationBatchEntry>()
+ for (const [key, value] of edits) {
+ const [resourceId, loc, field] = key.split('::')
+ const row = rowById.get(resourceId)
+ if (!row) continue
+ let entry = byResource.get(resourceId)
+ if (!entry) {
+ entry = { resource_type: row.resourceType, resource_id: resourceId, values: {} }
+ byResource.set(resourceId, entry)
+ }
+ entry.values[loc] ??= {}
+ entry.values[loc][field] = value
+ }
+
+ setSaving(true)
+ try {
+ await adminClient.translations.batch(Array.from(byResource.values()))
+ toast.success(t('admin.translations.saved'))
+ setEdits(new Map())
+ onSaved?.()
+ } catch (err) {
+ // The grid has no form to render inline errors onto, so surface the
+ // server's validation message (if any) in the toast rather than the
+ // generic fallback.
+ const message = err instanceof SpreeError ? err.message : undefined
+ toast.error(message || t('admin.translations.save_error'))
+ } finally {
+ setSaving(false)
+ }
+ }
+
+ const localeItems = useMemo(
+ () => targetLocales.map((code) => ({ value: code, label: localeName(code) })),
+ [targetLocales, localeName],
+ )
+
+ return (
+ <Dialog open={open} onOpenChange={handleOpenChange} modal>
+ <DialogContent
+ className="!inset-3 !w-auto !max-w-none !translate-x-0 !translate-y-0 flex flex-col p-0"
+ style={{ maxHeight: 'none' }}
+ showCloseButton={false}
+ >
+ <DialogHeader className="flex flex-row items-center justify-between gap-3 space-y-0 border-b p-3">
+ <div className="flex min-w-0 items-center gap-3">
+ <Button
+ type="button"
+ size="icon-sm"
+ variant="ghost"
+ onClick={() => handleOpenChange(false)}
+ aria-label={t('admin.actions.close')}
+ >
+ <XIcon />
+ </Button>
+ <DialogTitle className="sr-only">{t('admin.translations.title')}</DialogTitle>
+ {targetLocales.length > 0 && (
+ <Select items={localeItems} value={locale} onValueChange={setLocale}>
+ <SelectTrigger
+ size="sm"
+ className="w-48"
+ aria-label={t('admin.translations.locale')}
+ >
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {localeItems.map((item) => (
+ <SelectItem key={item.value} value={item.value}>
+ {item.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ </div>
+ <div className="flex items-center gap-2">
+ {dirtyCount > 0 && (
+ <span className="text-xs text-muted-foreground">
+ {t('admin.translations.dirty_summary', { count: dirtyCount })}
+ </span>
+ )}
+ <Button
+ type="button"
+ size="sm"
+ variant="ghost"
+ disabled={dirtyCount === 0 || saving}
+ onClick={() => setEdits(new Map())}
+ >
+ {t('admin.actions.discard')}
+ </Button>
+ <Button
+ type="button"
+ size="sm"
+ disabled={dirtyCount === 0 || saving}
+ onClick={handleSave}
+ >
+ {saving ? t('admin.actions.saving') : t('admin.translations.save')}
+ </Button>
+ </div>
+ </DialogHeader>
+ <DialogBody className="flex min-h-0 flex-1 flex-col overflow-auto p-0">
+ {isError ? (
+ <p className="p-3 text-sm text-destructive" role="alert">
+ {t('admin.translations.load_error')}
+ </p>
+ ) : isLoading || !data ? (
+ <Skeleton className="m-3 h-40" />
+ ) : targetLocales.length === 0 ? (
+ <p className="p-3 text-sm text-muted-foreground">
+ {t('admin.translations.no_locales')}
+ </p>
+ ) : (
+ locale && (
+ <TranslationGrid
+ rows={rows}
+ locale={locale}
+ localeName={localeName(locale)}
+ fieldLabel={fieldLabel}
+ edits={edits}
+ setEdits={setEdits}
+ />
+ )
+ )}
+ </DialogBody>
+ </DialogContent>
+ </Dialog>
+ )
+}
+
+function TranslationGrid({
+ rows,
+ locale,
+ localeName,
+ fieldLabel,
+ edits,
+ setEdits,
+}: {
+ rows: TranslationRow[]
+ locale: string
+ localeName: string
+ fieldLabel: (resourceType: string, field: TranslatableField) => string
+ edits: EditMap
+ setEdits: React.Dispatch<React.SetStateAction<EditMap>>
+}) {
+ const { t } = useTranslation()
+
+ const cellValue = useCallback(
+ (row: TranslationRow, field: string): string => {
+ const key = cellKey(row.resourceId, locale, field)
+ if (edits.has(key)) return edits.get(key) as string
+ const stored = row.translations[locale]?.[field]
+ return typeof stored === 'string' ? stored : ''
+ },
+ [edits, locale],
+ )
+
+ const handleChange = useCallback(
+ (row: TranslationRow, field: TranslatableField, next: string) => {
+ setEdits((prev) => {
+ const key = cellKey(row.resourceId, locale, field.key)
+ const stored = row.translations[locale]?.[field.key]
+ const baseline = typeof stored === 'string' ? stored : ''
+ const unchanged = field.type === 'html' ? sameRichText(next, baseline) : next === baseline
+ const out = new Map(prev)
+ if (unchanged) out.delete(key)
+ else out.set(key, next)
+ return out
+ })
+ },
+ [setEdits, locale],
+ )
+
+ return (
+ <table className="w-full table-fixed border-collapse text-sm">
+ <colgroup>
+ <col className="w-56" />
+ <col />
+ <col />
+ </colgroup>
+ <thead className="sticky top-0 z-10 bg-muted/40">
+ <tr className="text-left text-xs text-muted-foreground">
+ <th className="border-b border-r px-3 py-2 font-medium" />
+ <th className="border-b border-r px-3 py-2 font-medium">
+ {t('admin.translations.original')}
+ </th>
+ <th className="border-b px-3 py-2 font-medium">{localeName}</th>
+ </tr>
+ </thead>
+ <tbody>
+ {rows.flatMap((row) =>
+ row.fields.map((field) => {
+ // Stable cell identifier for aria-label / testid. Root rows are
+ // identified by the field key (`name`); child rows (whose field key
+ // repeats, e.g. `label`) by their source label so each is unique.
+ const cellName =
+ row.indent === 0 ? field.key : (row.rowLabel ?? field.source ?? field.key)
+ return (
+ <tr key={`${row.resourceId}.${field.key}`}>
+ <th
+ className="border-b border-r px-3 py-2 text-left align-top font-medium"
+ style={{ paddingLeft: `${0.75 + row.indent * 1}rem` }}
+ >
+ {row.rowLabel ?? fieldLabel(row.resourceType, field)}
+ </th>
+ <td
+ className="border-b border-r px-3 py-2 align-top text-muted-foreground"
+ data-testid={`source-${cellName}`}
+ >
+ {stripHtml(field.source ?? '')}
+ </td>
+ <td
+ className={cn(
+ 'relative border-b p-0 align-top',
+ 'focus-within:z-10 focus-within:ring-1 focus-within:ring-ring focus-within:ring-inset',
+ )}
+ >
+ {field.type === 'html' ? (
+ <RichTextEditor
+ ariaLabel={`${cellName} ${locale}`}
+ className="rounded-none border-0 bg-transparent shadow-none focus-within:border-0 focus-within:shadow-none [&_.tiptap]:min-h-20"
+ value={cellValue(row, field.key)}
+ onChange={(next: string) => handleChange(row, field, next)}
+ />
+ ) : (
+ <Textarea
+ aria-label={`${cellName} ${locale}`}
+ rows={1}
+ className="min-h-0 resize-none rounded-none border-0 bg-transparent px-3 py-2 shadow-none focus:border-transparent focus:shadow-none focus-visible:ring-0"
+ value={cellValue(row, field.key)}
+ onChange={(e) => handleChange(row, field, e.target.value)}
+ />
+ )}
+ </td>
+ </tr>
+ )
+ }),
+ )}
+ </tbody>
+ </table>
+ )
+}
+
+/** Flattens the matrix tree (root + nested children) into ordered rows.
+ * A child's left-column label is its own source value (e.g. "Small"), so the
+ * grid reads as a hierarchy; the root's rows use the field i18n labels. */
+function flattenTree(data: ResourceTranslations): TranslationRow[] {
+ const rows: TranslationRow[] = []
+
+ const pushNode = (node: ResourceTranslations | ResourceTranslationsNode, indent: number) => {
+ rows.push({
+ resourceType: node.resource_type,
+ resourceId: node.resource_id,
+ indent,
+ fields: node.fields,
+ translations: node.translations,
+ // Children typically have a single field; label the row by its source so
+ // the hierarchy reads naturally ("Size" → "Small", "Medium").
+ rowLabel: indent > 0 ? (node.fields[0]?.source ?? undefined) : undefined,
+ })
+ for (const child of node.children ?? []) pushNode(child, indent + 1)
+ }
+
+ pushNode(data, 0)
+ return rows
+}
+
+// Plain text of an HTML fragment. DOMParser handles nested/malformed tags
+// correctly — a single-pass regex strip can leak tags via patterns like
+// `<scr<script>ipt>` (CodeQL js/incomplete-multi-character-sanitization).
+function stripHtml(html: string): string {
+ return (new DOMParser().parseFromString(html, 'text/html').body.textContent ?? '').trim()
+}
+
+// Equal markup, or both empty-equivalent (`""`, `<p></p>`, `<p><br></p>`) — the
+// latter prevents the rich-text editor's mount-time `<p></p>` emission from
+// registering as a change against an empty baseline.
+function sameRichText(a: string, b: string): boolean {
+ return a === b || (!stripHtml(a) && !stripHtml(b))
+}
diff --git a/packages/dashboard/src/hooks/use-translations.ts b/packages/dashboard/src/hooks/use-translations.ts
new file mode 100644
index 0000000000..18f503935d
--- /dev/null
+++ b/packages/dashboard/src/hooks/use-translations.ts
@@ -0,0 +1,36 @@
+import type { Locale } from '@spree/admin-sdk'
+import { adminClient, useResourceKey } from '@spree/dashboard-core'
+import { useQuery } from '@tanstack/react-query'
+
+/** The locales a merchant can translate content into (for nice display names). */
+export function useLocales() {
+ return useQuery<Locale[]>({
+ queryKey: useResourceKey('locales'),
+ queryFn: () => adminClient.locales.list(),
+ })
+}
+
+/**
+ * Full translation matrix for a product: source values + content type per
+ * translatable field, plus the translated value for every supported locale.
+ * Writes go through the batch endpoint (see ResourceTranslationsDialog).
+ */
+export function useProductTranslations(productId: string) {
+ return useQuery({
+ queryKey: useResourceKey('products', productId, 'translations'),
+ queryFn: () => adminClient.products.translations.get(productId),
+ enabled: !!productId,
+ })
+}
+
+/**
+ * Translation matrix for an option type, with its option values nested under
+ * `children` so the editor renders type + values together.
+ */
+export function useOptionTypeTranslations(optionTypeId: string) {
+ return useQuery({
+ queryKey: useResourceKey('option-types', optionTypeId, 'translations'),
+ queryFn: () => adminClient.optionTypes.translations.get(optionTypeId),
+ enabled: !!optionTypeId,
+ })
+}
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index c3bbf18943..249b7d7d8e 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -2413,6 +2413,25 @@
"stock_updated": "تم تحديث المخزون",
"stock_item_deleted": "تم حذف عنصر المخزون"
}
+ },
+ "translations": {
+ "title": "الترجمات",
+ "locale": "اللغة",
+ "source": "المصدر",
+ "save": "حفظ الترجمات",
+ "saved": "تم حفظ الترجمات",
+ "save_error": "تعذر حفظ الترجمات",
+ "no_locales": "أضف المزيد من اللغات إلى متجرك لترجمة هذا المنتج.",
+ "manage": "إدارة الترجمات",
+ "field": "الحقل",
+ "coverage_summary": "تمت ترجمة {{translated}} من {{total}} لغة",
+ "dirty_summary": "{{count}} تغيير(ات) غير محفوظة",
+ "discard_confirm": {
+ "title": "تجاهل التغييرات؟",
+ "message": "لديك {{count}} تغيير(ات) ترجمة غير محفوظة. هل تريد تجاهلها؟"
+ },
+ "original": "الأصل",
+ "load_error": "تعذر تحميل الترجمات"
}
}
}
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index 5d49a790a2..39583dc65d 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -2413,6 +2413,25 @@
"stock_updated": "Bestand aktualisiert",
"stock_item_deleted": "Bestandsposition gelöscht"
}
+ },
+ "translations": {
+ "title": "Übersetzungen",
+ "locale": "Sprache",
+ "source": "Quelle",
+ "save": "Übersetzungen speichern",
+ "saved": "Übersetzungen gespeichert",
+ "save_error": "Übersetzungen konnten nicht gespeichert werden",
+ "no_locales": "Fügen Sie Ihrem Shop weitere Sprachen hinzu, um dieses Produkt zu übersetzen.",
+ "manage": "Übersetzungen verwalten",
+ "field": "Feld",
+ "coverage_summary": "{{translated}} von {{total}} Sprachen übersetzt",
+ "dirty_summary": "{{count}} nicht gespeicherte Änderung(en)",
+ "discard_confirm": {
+ "title": "Änderungen verwerfen?",
+ "message": "Sie haben {{count}} nicht gespeicherte Übersetzungsänderung(en). Verwerfen?"
+ },
+ "original": "Original",
+ "load_error": "Übersetzungen konnten nicht geladen werden"
}
}
}
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index cd66d10aec..309e973199 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -2413,6 +2413,25 @@
"stock_updated": "Stock updated",
"stock_item_deleted": "Stock item deleted"
}
+ },
+ "translations": {
+ "title": "Translations",
+ "locale": "Locale",
+ "source": "Source",
+ "save": "Save translations",
+ "saved": "Translations saved",
+ "save_error": "Could not save translations",
+ "no_locales": "Add more locales to your store to translate this product.",
+ "manage": "Manage translations",
+ "field": "Field",
+ "coverage_summary": "{{translated}} of {{total}} locales translated",
+ "dirty_summary": "{{count}} unsaved change(s)",
+ "discard_confirm": {
+ "title": "Discard changes?",
+ "message": "You have {{count}} unsaved translation change(s). Discard them?"
+ },
+ "original": "Original",
+ "load_error": "Could not load translations"
}
}
}
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index b37b63a75a..93cafbac98 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -2413,6 +2413,25 @@
"stock_updated": "Stock mis à jour",
"stock_item_deleted": "Article en stock supprimé"
}
+ },
+ "translations": {
+ "title": "Traductions",
+ "locale": "Langue",
+ "source": "Source",
+ "save": "Enregistrer les traductions",
+ "saved": "Traductions enregistrées",
+ "save_error": "Impossible d enregistrer les traductions",
+ "no_locales": "Ajoutez d autres langues à votre boutique pour traduire ce produit.",
+ "manage": "Gérer les traductions",
+ "field": "Champ",
+ "coverage_summary": "{{translated}} sur {{total}} langues traduites",
+ "dirty_summary": "{{count}} modification(s) non enregistrée(s)",
+ "discard_confirm": {
+ "title": "Annuler les modifications ?",
+ "message": "Vous avez {{count}} modification(s) de traduction non enregistrée(s). Les annuler ?"
+ },
+ "original": "Original",
+ "load_error": "Impossible de charger les traductions"
}
}
}
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index 5b40da0305..2c12f9d7dd 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -2445,6 +2445,25 @@
"stock_updated": "Zaktualizowano stan magazynowy",
"stock_item_deleted": "Usunięto pozycję magazynową"
}
+ },
+ "translations": {
+ "title": "Tłumaczenia",
+ "locale": "Język",
+ "source": "Źródło",
+ "save": "Zapisz tłumaczenia",
+ "saved": "Tłumaczenia zapisane",
+ "save_error": "Nie można zapisać tłumaczeń",
+ "no_locales": "Dodaj więcej języków do swojego sklepu, aby przetłumaczyć ten produkt.",
+ "manage": "Zarządzaj tłumaczeniami",
+ "field": "Pole",
+ "coverage_summary": "Przetłumaczono {{translated}} z {{total}} języków",
+ "dirty_summary": "{{count}} niezapisanych zmian",
+ "discard_confirm": {
+ "title": "Odrzucić zmiany?",
+ "message": "Masz {{count}} niezapisanych zmian tłumaczeń. Odrzucić je?"
+ },
+ "original": "Oryginał",
+ "load_error": "Nie można załadować tłumaczeń"
}
}
}
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index 48e15c08d8..8f8d36af32 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -2413,6 +2413,25 @@
"stock_updated": "库存已更新",
"stock_item_deleted": "库存项已删除"
}
+ },
+ "translations": {
+ "title": "翻译",
+ "locale": "语言",
+ "source": "源",
+ "save": "保存翻译",
+ "saved": "翻译已保存",
+ "save_error": "无法保存翻译",
+ "no_locales": "向您的商店添加更多语言以翻译此产品。",
+ "manage": "管理翻译",
+ "field": "字段",
+ "coverage_summary": "已翻译 {{total}} 种语言中的 {{translated}} 种",
+ "dirty_summary": "{{count}} 项未保存的更改",
+ "discard_confirm": {
+ "title": "放弃更改?",
+ "message": "您有 {{count}} 项未保存的翻译更改。要放弃吗?"
+ },
+ "original": "原文",
+ "load_error": "无法加载翻译"
}
}
}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
index 554171a844..b545e79056 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
@@ -32,6 +32,7 @@ import {
TaxCard,
VariantsCard,
} from '@/components/spree/products/product-form-cards'
+import { ProductTranslationsCard } from '@/components/spree/products/product-translations-card'
import { PublishingCard } from '@/components/spree/products/publishing-card'
import { useDeleteProduct, useProduct, useUpdateProduct } from '@/hooks/use-product'
import { useProductMedia } from '@/hooks/use-product-media'
@@ -400,6 +401,7 @@ function ProductForm({ product }: { product: Product }) {
>
<CustomFieldsInlineCard />
</ApiBackedCustomFieldsProvider>
+ <ProductTranslationsCard productId={productId} />
<MetadataCard
metadata={product.metadata}
title={t('admin.components.metadata_card.title')}
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsx
index 427eaae7c8..067e723120 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/options.tsx
@@ -65,7 +65,14 @@ import {
} from '@spree/dashboard-ui'
import { useQueryClient } from '@tanstack/react-query'
import { createFileRoute, useNavigate } from '@tanstack/react-router'
-import { ImageIcon, PlusIcon, Trash2Icon, UploadCloudIcon, XIcon } from 'lucide-react'
+import {
+ ImageIcon,
+ LanguagesIcon,
+ PlusIcon,
+ Trash2Icon,
+ UploadCloudIcon,
+ XIcon,
+} from 'lucide-react'
import { type CSSProperties, useEffect, useId, useRef, useState } from 'react'
import {
type Control,
@@ -77,6 +84,7 @@ import {
import { useTranslation } from 'react-i18next'
import { toast } from 'sonner'
import { z } from 'zod/v4'
+import { OptionTypeTranslationsDialog } from '@/components/spree/products/option-type-translations-dialog'
import {
useCreateOptionType,
useDeleteOptionType,
@@ -313,15 +321,39 @@ function EditOptionTypeSheet({
}
}
+ const [translationsOpen, setTranslationsOpen] = useState(false)
+
return (
<Sheet open={open} onOpenChange={onOpenChange}>
<SheetContent className="sm:max-w-2xl">
<SheetHeader>
- <SheetTitle>
- {optionType?.name ?? t('admin.pages.products.options.sheet_title_edit')}
- </SheetTitle>
- <SheetDescription>{t('admin.products.options.edit_description')}</SheetDescription>
+ <div className="flex items-start justify-between gap-3">
+ <div className="min-w-0">
+ <SheetTitle>
+ {optionType?.name ?? t('admin.pages.products.options.sheet_title_edit')}
+ </SheetTitle>
+ <SheetDescription>{t('admin.products.options.edit_description')}</SheetDescription>
+ </div>
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ onClick={() => setTranslationsOpen(true)}
+ >
+ <LanguagesIcon className="size-4" />
+ {t('admin.translations.manage')}
+ </Button>
+ </div>
</SheetHeader>
+ {/* Mounted only when opened so its translation fetch doesn't fire on
+ every option-type edit. */}
+ {translationsOpen && (
+ <OptionTypeTranslationsDialog
+ optionTypeId={id}
+ open={translationsOpen}
+ onOpenChange={setTranslationsOpen}
+ />
+ )}
{isLoading ? (
<div className="p-4 text-sm text-muted-foreground">{t('admin.common.loading')}</div>
) : (
diff --git a/packages/sdk/src/types/generated/Locale.ts b/packages/sdk/src/types/generated/Locale.ts
index 640eec80cf..d2458e6761 100644
--- a/packages/sdk/src/types/generated/Locale.ts
+++ b/packages/sdk/src/types/generated/Locale.ts
@@ -1,10 +1,12 @@
-// Typelizer digest 355a23a807446572a75af3eba29d7d83
+// Typelizer digest ea08de9001e7af2870da3f0636d77859
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
interface Locale {
code: string;
name: string;
+ default: boolean;
+ rtl: boolean;
}
export default Locale;
diff --git a/packages/sdk/src/zod/generated/Locale.ts b/packages/sdk/src/zod/generated/Locale.ts
index c7c660da75..cb84831c9f 100644
--- a/packages/sdk/src/zod/generated/Locale.ts
+++ b/packages/sdk/src/zod/generated/Locale.ts
@@ -4,6 +4,8 @@ import { z } from 'zod';
export const LocaleSchema = z.object({
code: z.string(),
name: z.string(),
+ default: z.boolean(),
+ rtl: z.boolean(),
});
export type Locale = z.infer<typeof LocaleSchema>;
diff --git a/spree/admin/app/controllers/spree/admin/countries_controller.rb b/spree/admin/app/controllers/spree/admin/countries_controller.rb
index 44b9c08159..141a30be5e 100644
--- a/spree/admin/app/controllers/spree/admin/countries_controller.rb
+++ b/spree/admin/app/controllers/spree/admin/countries_controller.rb
@@ -10,13 +10,13 @@ module Spree
# country name); `label` is the localized, flag-prefixed display string.
def select_options
countries = Spree::Country.accessible_by(current_ability, :show).
- sort_by { |country| Spree::LocalizedNames.country_name(country.iso, fallback: country.name) }
+ sort_by(&:localized_name)
options = countries.map do |country|
{
id: country.id,
name: country.name,
- label: Spree::LocalizedNames.country_option_label(country)
+ label: country.option_label
}
end
diff --git a/spree/admin/app/helpers/spree/admin/base_helper.rb b/spree/admin/app/helpers/spree/admin/base_helper.rb
index d8b6e5de7a..8d475eb1a5 100644
--- a/spree/admin/app/helpers/spree/admin/base_helper.rb
+++ b/spree/admin/app/helpers/spree/admin/base_helper.rb
@@ -41,6 +41,11 @@ module Spree
@available_countries_iso ||= current_store.countries_available_for_checkout.pluck(:iso)
end
+ # @return [Array<Spree::Country>] the available countries for checkout
+ def available_countries
+ @available_countries ||= available_countries_iso.map { |iso| Spree::Country.new(iso: iso) }
+ end
+
# returns the available display on options, eg backend, frontend, both
# @return [Array<Array<String, String>>] the available display on options
def display_on_options(model = nil)
diff --git a/spree/admin/app/helpers/spree/admin/rtl_helper.rb b/spree/admin/app/helpers/spree/admin/rtl_helper.rb
index 8373dc08ee..9143a33b3d 100644
--- a/spree/admin/app/helpers/spree/admin/rtl_helper.rb
+++ b/spree/admin/app/helpers/spree/admin/rtl_helper.rb
@@ -1,12 +1,14 @@
module Spree
module Admin
+ # View helpers for the legacy admin's layout direction (`<html dir>`).
+ # RTL detection itself lives on Spree::Locale (the single source of truth).
module RtlHelper
def rtl_locale?(locale = I18n.locale)
- Spree::Admin::Rtl.rtl_locale?(locale)
+ Spree::Locale.new(code: locale).rtl?
end
def html_dir(locale = I18n.locale)
- Spree::Admin::Rtl.html_dir(locale)
+ Spree::Locale.new(code: locale).direction
end
end
end
diff --git a/spree/admin/app/views/spree/admin/promotion_rules/forms/_country.html.erb b/spree/admin/app/views/spree/admin/promotion_rules/forms/_country.html.erb
index 52c7010dbe..c6969c0ca2 100644
--- a/spree/admin/app/views/spree/admin/promotion_rules/forms/_country.html.erb
+++ b/spree/admin/app/views/spree/admin/promotion_rules/forms/_country.html.erb
@@ -1,7 +1,7 @@
<div class="form-group">
<%= f.label :preferred_country_iso, Spree.t(:country) %>
<%= f.select :preferred_country_iso,
- available_countries_iso.map { |iso| [Spree::LocalizedNames.country_name(iso, fallback: iso), iso] },
+ available_countries.map { |country| [country.localized_name, country.iso] },
{ selected: f.object.preferred_country_iso || current_store.default_market&.default_country&.iso },
{ data: { controller: 'autocomplete-select' } } %>
</div>
diff --git a/spree/admin/lib/spree/admin/engine.rb b/spree/admin/lib/spree/admin/engine.rb
index dbb2561fe1..ebc9806c00 100644
--- a/spree/admin/lib/spree/admin/engine.rb
+++ b/spree/admin/lib/spree/admin/engine.rb
@@ -1,5 +1,4 @@
require_relative 'runtime_configuration'
-require_relative 'rtl'
module Spree
module Admin
diff --git a/spree/admin/lib/spree/admin/rtl.rb b/spree/admin/lib/spree/admin/rtl.rb
deleted file mode 100644
index 0fcf847eb1..0000000000
--- a/spree/admin/lib/spree/admin/rtl.rb
+++ /dev/null
@@ -1,26 +0,0 @@
-module Spree
- module Admin
- # Detects right-to-left locales for the legacy admin UI layout direction
- # (`<html dir="rtl">`). Admin-only — the React dashboard handles RTL itself
- # via i18next, so this lives in the admin gem rather than core.
- module Rtl
- # ISO 639-1 language codes that use right-to-left scripts.
- RTL_LANGUAGE_CODES = %w[ar he fa ur yi].freeze
-
- module_function
-
- # @param locale [String, Symbol]
- # @return [Boolean]
- def rtl_locale?(locale = I18n.locale)
- language_code = locale.to_s.tr('_', '-').split('-', 2).first
- RTL_LANGUAGE_CODES.include?(language_code)
- end
-
- # @param locale [String, Symbol]
- # @return [String] "rtl" or "ltr"
- def html_dir(locale = I18n.locale)
- rtl_locale?(locale) ? 'rtl' : 'ltr'
- end
- end
- end
-end
diff --git a/spree/admin/spec/lib/spree/admin/rtl_spec.rb b/spree/admin/spec/lib/spree/admin/rtl_spec.rb
deleted file mode 100644
index d7f4051a17..0000000000
--- a/spree/admin/spec/lib/spree/admin/rtl_spec.rb
+++ /dev/null
@@ -1,30 +0,0 @@
-require 'spec_helper'
-
-describe Spree::Admin::Rtl do
- describe '.rtl_locale?' do
- it 'returns true for Arabic' do
- expect(described_class.rtl_locale?(:ar)).to be(true)
- expect(described_class.rtl_locale?('ar-SA')).to be(true)
- end
-
- it 'returns true for other RTL languages' do
- expect(described_class.rtl_locale?(:he)).to be(true)
- expect(described_class.rtl_locale?(:fa)).to be(true)
- end
-
- it 'returns false for LTR languages' do
- expect(described_class.rtl_locale?(:en)).to be(false)
- expect(described_class.rtl_locale?(:de)).to be(false)
- end
- end
-
- describe '.html_dir' do
- it 'returns rtl for RTL locales' do
- expect(described_class.html_dir(:ar)).to eq('rtl')
- end
-
- it 'returns ltr for LTR locales' do
- expect(described_class.html_dir(:en)).to eq('ltr')
- end
- end
-end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/locales_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/locales_controller.rb
new file mode 100644
index 0000000000..080c0d122c
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/locales_controller.rb
@@ -0,0 +1,29 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Lists the locales a merchant can translate content into for the
+ # current store (its supported_locales_list), so the dashboard's locale
+ # switcher enumerates locales instead of hardcoding them.
+ class LocalesController < Admin::BaseController
+ scoped_resource :settings
+
+ # GET /api/v3/admin/locales
+ def index
+ render json: {
+ data: current_store.supported_locales.map do |locale|
+ Spree.api.locale_serializer.new(locale).to_h
+ end
+ }
+ end
+
+ private
+
+ def action_kind
+ 'read'
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/translatable_resources_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/translatable_resources_controller.rb
new file mode 100644
index 0000000000..1cab797921
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/translatable_resources_controller.rb
@@ -0,0 +1,38 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Self-describing discovery of every translatable resource and its
+ # translatable fields (the Spree.translatable_resources registry made
+ # public). Lets the dashboard render translation editors and the
+ # centralized translations grid generically, with no per-model code.
+ class TranslatableResourcesController < Admin::BaseController
+ scoped_resource :settings
+
+ # Public resource types with a dedicated nested read route
+ # (`…/:id/translations`). Other registered types are writable via the
+ # batch endpoint and readable inline (e.g. option values are returned
+ # as children of an option type), so the dashboard must not GET a
+ # standalone matrix for them. Keep in sync with the `:translatable`
+ # route concern mounts in `spree/api/config/routes.rb`.
+ READABLE_RESOURCE_TYPES = %w[product category option_type].freeze
+
+ # GET /api/v3/admin/translatable_resources
+ def index
+ data = Spree::Translations.registry.map do |entry|
+ entry.merge('readable' => READABLE_RESOURCE_TYPES.include?(entry['resource_type']))
+ end
+
+ render json: { data: data }
+ end
+
+ private
+
+ def action_kind
+ 'read'
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/translations/batches_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/translations/batches_controller.rb
new file mode 100644
index 0000000000..5d8168c18e
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/translations/batches_controller.rb
@@ -0,0 +1,113 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ module Translations
+ # Atomically upserts translations across MANY records of (possibly)
+ # different translatable resource types in a single request. Powers
+ # the dashboard's combined editors (e.g. an option type + all its
+ # option values saved in one go).
+ #
+ # The body is a flat list of independent registry writes — NOT a
+ # nested/parent-owns-children payload. Each entry names its own
+ # resource_type + resource_id, so the controller stays free of
+ # per-model branching.
+ #
+ # POST /api/v3/admin/translations/batch
+ # Body:
+ # { "translations": [
+ # { "resource_type": "option_type", "resource_id": "opt_…",
+ # "values": { "de": { "label": "Größe" } } },
+ # { "resource_type": "option_value", "resource_id": "optval_…",
+ # "values": { "de": { "label": "Klein" } } }
+ # ] }
+ #
+ # All entries succeed or none do — a validation failure on any entry
+ # rolls back the whole transaction and returns per-entry detail.
+ # The orchestration (resolve → upsert → rollback) lives in
+ # Spree::Translations::Batch; the controller only handles params,
+ # authorization, and rendering.
+ class BatchesController < Admin::BaseController
+ # The batch spans heterogeneous resource types, so a single static
+ # scope can't gate it. We verify the API key holds the matching
+ # write_<resource> scope for EVERY entry (see require_batch_scopes!),
+ # which is stricter than the static check and keeps the audit model.
+ skip_scope_check!
+
+ # POST /api/v3/admin/translations/batch
+ def create
+ raw = params[:translations]
+ return render_empty_batch_error unless raw.is_a?(Array) && raw.any?
+
+ batch = Spree::Translations::Batch.new(batch_params)
+ return unless require_batch_scopes!(batch)
+
+ records = batch.process! { |record| authorize!(:update, record) }
+ render json: { data: records.map { |record| serialize_translations(record) } }
+ rescue Spree::Translations::Batch::EntryError => e
+ render_error(
+ code: ERROR_CODES[:validation_error],
+ message: e.message,
+ status: :unprocessable_content,
+ details: { translations: { e.index.to_s => [e.message] } }
+ )
+ end
+
+ private
+
+ # For API-key callers, require write_<resource> for every distinct
+ # resource type in the batch. JWT callers bypass (current_api_key is
+ # nil) and rely on the per-record authorize!(:update, record) above.
+ # Returns false (and renders 403) when a scope is missing.
+ def require_batch_scopes!(batch)
+ return true unless current_api_key
+
+ missing = batch.required_scopes.reject { |scope| current_api_key.has_scope?(scope) }
+ return true if missing.empty?
+
+ render_error(
+ code: ERROR_CODES[:access_denied],
+ message: "API key lacks scope(s): #{missing.join(', ')}",
+ status: :forbidden,
+ details: { required_scopes: missing }
+ )
+ false
+ end
+
+ # [{ resource_type:, resource_id:, values: { locale => { field => value } } }]
+ def batch_params
+ Array(params[:translations]).map do |entry|
+ permitted = entry.respond_to?(:permit) ? entry.permit(:resource_type, :resource_id, values: {}) : entry
+ values = permitted[:values]
+ {
+ resource_type: permitted[:resource_type].to_s,
+ resource_id: permitted[:resource_id].to_s,
+ values: values.respond_to?(:to_unsafe_h) ? values.to_unsafe_h : (values || {}).to_h
+ }
+ end
+ end
+
+ def render_empty_batch_error
+ render_error(
+ code: ERROR_CODES[:validation_error],
+ message: 'translations must be a non-empty array',
+ status: :unprocessable_content
+ )
+ end
+
+ # Write echo: matrix + locale envelope, no discovery fields/children.
+ def serialize_translations(record)
+ Spree.api.admin_resource_translations_serializer.new(
+ record, params: serializer_params.merge(fields: false, envelope: true)
+ ).to_h
+ end
+
+ def action_kind
+ 'write'
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/translations_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/translations_controller.rb
new file mode 100644
index 0000000000..8010cbf3ad
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/translations_controller.rb
@@ -0,0 +1,96 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Read-only translation matrix for any parent in the
+ # +Spree.translatable_resources+ registry. Mounted via the
+ # +:translatable+ route concern; the parent class is inferred from
+ # whichever +<segment>_id+ route param matches a registered translatable
+ # resource. One controller serves every model.
+ #
+ # Writes go through the batch endpoint (+POST /admin/translations/batch+)
+ # — a single atomic surface that also handles multi-record saves (an
+ # option type plus all its option values). There is no per-resource
+ # write here.
+ class TranslationsController < ResourceController
+ # This controller acts on the @parent (set by set_parent), never on a
+ # @resource of its own, so the base set_resource lookup (which needs a
+ # model_class) must not run.
+ skip_before_action :set_resource
+ before_action :ensure_translatable!
+
+ # GET /api/v3/admin/<parent>/<parent_id>/translations
+ # Returns the matrix + discovery fields, with nested translatable
+ # children (e.g. an option type's values) so an editor fetches the
+ # whole tree in one read.
+ def index
+ render json: { data: serialize_translations(@parent) }
+ end
+
+ protected
+
+ def set_parent
+ raise ActiveRecord::RecordNotFound, 'Parent resource not found' unless parent_lookup
+
+ @parent = parent_relation.find_by_prefix_id!(parent_lookup.value)
+ authorize!(:show, @parent)
+ end
+
+ # Resolves the parent within the current store so a token for one
+ # store can't read or write another store's translations. Preloads
+ # translatable children + their translation rows so the nested matrix
+ # read (e.g. an option type's values) avoids an N+1 over the child
+ # translation tables.
+ def parent_relation
+ klass = parent_lookup.klass
+ relation = klass.respond_to?(:for_store) ? klass.for_store(current_store) : klass
+
+ children = klass.try(:translatable_children)
+ children ? relation.includes(children => :translations) : relation
+ end
+
+ # Per-parent scope check: reading a product's translations needs
+ # `read_products`, a category's `read_categories`, etc.
+ def scoped_resource_name
+ parent_lookup&.segment&.pluralize&.to_sym
+ end
+
+ def ensure_translatable!
+ raise ActiveRecord::RecordNotFound unless Spree.translatable_resources.include?(@parent.class)
+ end
+
+ ParentLookup = Struct.new(:klass, :value, :segment)
+
+ # Maps route segment ('product', 'category', …) to model class name.
+ # Class names (not objects) survive dev-mode reloads. Aliases
+ # 'category' because routes expose taxons as categories (5.5 rename)
+ # while the model element is still 'taxon'.
+ def parent_route_map
+ @parent_route_map ||= Spree.translatable_resources.each_with_object({}) do |klass, m|
+ m[klass.model_name.element.to_s] = klass.name
+ end.merge('category' => 'Spree::Taxon')
+ end
+
+ def parent_lookup
+ return @parent_lookup if defined?(@parent_lookup)
+
+ match = parent_route_map.find { |segment, _| params[:"#{segment}_id"].present? }
+ @parent_lookup =
+ if match
+ segment, klass_name = match
+ ParentLookup.new(klass_name.constantize, params[:"#{segment}_id"], segment)
+ end
+ end
+
+ # Full read shape: matrix + discovery fields + nested children +
+ # the locale envelope.
+ def serialize_translations(record)
+ Spree.api.admin_resource_translations_serializer.new(
+ record, params: serializer_params.merge(fields: true, envelope: true)
+ ).to_h
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/store/locales_controller.rb b/spree/api/app/controllers/spree/api/v3/store/locales_controller.rb
index a1e76f6880..1618c8dfdc 100644
--- a/spree/api/app/controllers/spree/api/v3/store/locales_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/locales_controller.rb
@@ -7,20 +7,14 @@ module Spree
# GET /api/v3/store/locales
def index
- locales = current_store.supported_locales_list
+ locales = current_store.supported_locales
return unless cache_collection(locales)
render json: {
- data: locales.map { |code| Spree.api.locale_serializer.new(OpenStruct.new(code: code, name: locale_name(code))).to_h }
+ data: locales.map { |locale| Spree.api.locale_serializer.new(locale).to_h }
}
end
-
- private
-
- def locale_name(code)
- I18n.t('spree.i18n.this_file_language', locale: code, default: code)
- end
end
end
end
diff --git a/spree/api/app/serializers/concerns/spree/api/v3/admin/translatable.rb b/spree/api/app/serializers/concerns/spree/api/v3/admin/translatable.rb
new file mode 100644
index 0000000000..f283480e68
--- /dev/null
+++ b/spree/api/app/serializers/concerns/spree/api/v3/admin/translatable.rb
@@ -0,0 +1,38 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Adds the opt-in per-locale translation matrix to an admin serializer
+ # for a model that includes +Spree::TranslatableResource+. Include it in
+ # every translatable resource's admin serializer (product, option type,
+ # category, …) so the +?expand=translations+ surface stays consistent
+ # and defined in one place.
+ #
+ # @example
+ # class ProductSerializer < V3::ProductSerializer
+ # include Spree::Api::V3::Admin::Translatable
+ # end
+ module Translatable
+ extend ActiveSupport::Concern
+
+ included do
+ # locale code => { field => value, translated_field_count } — mirrors
+ # the hand-written LocaleTranslations shape, inlined so the generated
+ # types need no import from the hand-written barrel.
+ typelize translations: 'Record<string, Record<string, string | number | null>>'
+
+ # Full per-locale translation matrix { locale => { field => value } }.
+ # Opt-in via ?expand=translations — the matrix (non-default locales ×
+ # translatable fields × translation-table joins) is wasteful on list
+ # views, so it is never rendered by default. params[:expand] is part
+ # of the HTTP cache key, so expanded/non-expanded responses cache
+ # separately. Writes go through the dedicated /translations endpoint.
+ attribute :translations, if: proc { expand?('translations') } do |record|
+ Spree::Translations.matrix_for(record)
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb
index 40bd61fe87..4d46421f0b 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/category_serializer.rb
@@ -5,6 +5,8 @@ module Spree
# Admin API Category Serializer
# Full category data including admin-only fields
class CategorySerializer < V3::CategorySerializer
+ include Spree::Api::V3::Admin::Translatable
+
typelize pretty_name: :string, lft: :number, rgt: :number, sort_order: :string,
metadata: 'Record<string, unknown>'
diff --git a/spree/api/app/serializers/spree/api/v3/admin/option_type_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/option_type_serializer.rb
index bf236bc250..776cabf57a 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/option_type_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/option_type_serializer.rb
@@ -3,6 +3,8 @@ module Spree
module V3
module Admin
class OptionTypeSerializer < V3::OptionTypeSerializer
+ include Spree::Api::V3::Admin::Translatable
+
typelize metadata: 'Record<string, unknown>', filterable: :boolean
attributes :metadata, :filterable,
diff --git a/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb
index ec0f932d48..298f78eaa2 100644
--- a/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/admin/product_serializer.rb
@@ -6,6 +6,7 @@ module Spree
# Full product data including admin-only fields
# Extends the store serializer with additional attributes
class ProductSerializer < V3::ProductSerializer
+ include Spree::Api::V3::Admin::Translatable
typelize status: :string,
tax_category_id: [:string, nullable: true],
diff --git a/spree/api/app/serializers/spree/api/v3/admin/resource_translations_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/resource_translations_serializer.rb
new file mode 100644
index 0000000000..ac11de75be
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/resource_translations_serializer.rb
@@ -0,0 +1,76 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Serializes a translatable record's translation payload — the locale ×
+ # field matrix, optionally with self-describing discovery +fields+, the
+ # locale envelope, and nested translatable +children+.
+ #
+ # Params select the shape:
+ # - +fields: true+ — include +fields+ (key/type/source) and nested
+ # +children+ (e.g. an option type's option values). The read endpoint
+ # (`GET …/:id/translations`) uses this so an editor fetches the whole
+ # tree in one request.
+ # - +envelope: true+ — include +default_locale+/+supported_locales+ from
+ # the record's own translatable store (so they can't contradict the
+ # matrix). The top-level read node and each batch-write echo carry it;
+ # nested children do not.
+ #
+ # The batch write echo passes +fields: false+ (matrix only); the read
+ # endpoint passes both true at the top level and re-renders children
+ # with +envelope: false+.
+ #
+ # Deliberately does NOT include Typelizer::DSL: the payload is computed
+ # (matrix/fields/children resolve to `unknown`), so the admin-sdk ships
+ # richer hand-written types in `src/types/translations.ts` instead.
+ # Without the DSL, Typelizer never enumerates this serializer.
+ class ResourceTranslationsSerializer
+ include Alba::Resource
+
+ attribute :resource_id, &:prefixed_id
+
+ attribute :resource_type do |record|
+ Spree::Translations.public_resource_type(record.class)
+ end
+
+ attribute :translations do |record|
+ Spree::Translations.matrix_for(record)
+ end
+
+ attribute :fields, if: proc { params[:fields] } do |record|
+ Spree::Translations.fields_for(record)
+ end
+
+ attribute :default_locale, if: proc { params[:envelope] } do |record|
+ locale_store(record).default_locale
+ end
+
+ attribute :supported_locales, if: proc { params[:envelope] } do |record|
+ locale_store(record).supported_locales_list
+ end
+
+ attribute :children, if: proc { |record| params[:fields] && children_for(record).any? } do |record|
+ # Children carry their own fields + matrix, but not the locale
+ # envelope (that's a property of the top-level request, not each row).
+ # Recurse with self.class so a swapped subclass renders children too.
+ child_params = params.merge(envelope: false)
+ children_for(record).map { |child| self.class.new(child, params: child_params).to_h }
+ end
+
+ private
+
+ # The store whose locales the payload reports — the record's own
+ # translatable store, falling back to the current store.
+ def locale_store(record)
+ record.translatable_store || params[:store]
+ end
+
+ def children_for(record)
+ assoc = record.class.try(:translatable_children)
+ assoc.present? ? Array(record.public_send(assoc)) : []
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/locale_serializer.rb b/spree/api/app/serializers/spree/api/v3/locale_serializer.rb
index 43978bfe15..3fcaf442cf 100644
--- a/spree/api/app/serializers/spree/api/v3/locale_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/locale_serializer.rb
@@ -1,13 +1,18 @@
module Spree
module Api
module V3
+ # Serializes a Spree::Locale. The display name, default flag, and RTL
+ # direction all live on the model — this is a thin projection of it.
class LocaleSerializer
include Alba::Resource
include Typelizer::DSL
- typelize code: :string, name: :string
+ typelize code: :string, name: :string, default: :boolean, rtl: :boolean
attributes :code, :name
+
+ attribute(:default, &:default?)
+ attribute(:rtl, &:rtl?)
end
end
end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index 0cbf06e79e..e93e634832 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -103,9 +103,26 @@ Spree::Core::Engine.add_routes do
resources :custom_fields
end
+ # Mounts a read-only nested `translations` matrix on parents in the
+ # Spree.translatable_resources registry. Writes go through the batch
+ # endpoint (POST /translations/batch). One generic controller serves
+ # every translatable model. See docs/plans/5.5-6.0-resource-translations-api.md.
+ concern :translatable do
+ resources :translations, only: [:index], controller: 'translations'
+ end
+
# Definitions are per resource type, not per instance.
resources :custom_field_definitions
+ # Translation discovery: the translatable-resources registry and the
+ # store's supported locales. See docs/plans/5.5-6.0-resource-translations-api.md.
+ resources :translatable_resources, only: [:index]
+ resources :locales, only: [:index]
+
+ # Atomic multi-record translation upsert (e.g. an option type + all its
+ # option values in one save). Flat list of independent registry writes.
+ post 'translations/batch', to: 'translations/batches#create'
+
# Authentication
post 'auth/login', to: 'auth#create'
post 'auth/refresh', to: 'auth#refresh'
@@ -171,7 +188,7 @@ Spree::Core::Engine.add_routes do
end
# Products
- resources :products, concerns: :custom_fieldable do
+ resources :products, concerns: [:custom_fieldable, :translatable] do
member do
post :clone
end
@@ -192,10 +209,10 @@ Spree::Core::Engine.add_routes do
end
# Categories
- resources :categories, only: [:index, :show], concerns: :custom_fieldable
+ resources :categories, only: [:index, :show], concerns: [:custom_fieldable, :translatable]
# Option Types (with nested option_values in payload)
- resources :option_types, concerns: :custom_fieldable
+ resources :option_types, concerns: [:custom_fieldable, :translatable]
# Tax Categories
resources :tax_categories
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index 3168e517c6..25988cbbe9 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -220,6 +220,7 @@ module Spree
admin_coupon_code_serializer: 'Spree::Api::V3::Admin::CouponCodeSerializer',
admin_price_list_serializer: 'Spree::Api::V3::Admin::PriceListSerializer',
admin_price_rule_serializer: 'Spree::Api::V3::Admin::PriceRuleSerializer',
+ admin_resource_translations_serializer: 'Spree::Api::V3::Admin::ResourceTranslationsSerializer',
# platform serializers
platform_metafield_serializer: 'Spree::Api::V2::Platform::MetafieldSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/locales_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/locales_controller_spec.rb
new file mode 100644
index 0000000000..165dccf1fc
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/locales_controller_spec.rb
@@ -0,0 +1,30 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::LocalesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ before do
+ configure_supported_locales(store, %w[en de ar])
+ request.headers.merge!(headers)
+ end
+
+ describe 'GET #index' do
+ it 'lists supported locales with default and rtl flags' do
+ get :index, params: {}, as: :json
+
+ expect(response).to have_http_status(:ok)
+ locales = json_response['data']
+ expect(locales.map { |l| l['code'] }).to match_array(%w[en de ar])
+
+ en = locales.find { |l| l['code'] == 'en' }
+ expect(en['default']).to be(true)
+ expect(en['rtl']).to be(false)
+
+ ar = locales.find { |l| l['code'] == 'ar' }
+ expect(ar['default']).to be(false)
+ expect(ar['rtl']).to be(true)
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
index 551f4e55aa..449f74c575 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/products_controller_spec.rb
@@ -1882,4 +1882,21 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
expect(other_store_product.reload.deleted_at).to be_nil
end
end
+
+ describe 'translations matrix on show' do
+ before do
+ configure_supported_locales(store, %w[en de fr])
+ request.headers.merge!(headers)
+ end
+
+ it 'returns the matrix only when ?expand=translations is requested' do
+ Mobility.with_locale(:de) { product.update!(name: 'Espressomaschine') }
+
+ get :show, params: { id: product.prefixed_id }, as: :json
+ expect(json_response).not_to have_key('translations')
+
+ get :show, params: { id: product.prefixed_id, expand: 'translations' }, as: :json
+ expect(json_response['translations']['de']['name']).to eq('Espressomaschine')
+ end
+ end
end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/translatable_resources_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/translatable_resources_controller_spec.rb
new file mode 100644
index 0000000000..73fce35e1f
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/translatable_resources_controller_spec.rb
@@ -0,0 +1,39 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::TranslatableResourcesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ it 'lists every translatable resource and its fields' do
+ get :index, params: {}, as: :json
+
+ expect(response).to have_http_status(:ok)
+ resources = json_response['data']
+ product = resources.find { |r| r['resource_type'] == 'product' }
+ expect(product).to be_present
+
+ field_keys = product['fields'].map { |f| f['key'] }
+ expect(field_keys).to include('name', 'description', 'slug')
+
+ description_field = product['fields'].find { |f| f['key'] == 'description' }
+ expect(description_field['type']).to eq('html')
+ # slug is a plain string field — only model-declared rich text is 'html'
+ expect(product['fields'].find { |f| f['key'] == 'slug' }['type']).to eq('string')
+ expect(product['fields'].find { |f| f['key'] == 'name' }['type']).to eq('string')
+ end
+
+ it 'flags which resources have a dedicated read route' do
+ get :index, params: {}, as: :json
+
+ resources = json_response['data'].index_by { |r| r['resource_type'] }
+ expect(resources['product']['readable']).to be(true)
+ expect(resources['category']['readable']).to be(true)
+ # Writable via batch + readable inline as children, but no standalone route.
+ expect(resources['option_value']['readable']).to be(false)
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/translations/batches_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/translations/batches_controller_spec.rb
new file mode 100644
index 0000000000..8ccc1848b4
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/translations/batches_controller_spec.rb
@@ -0,0 +1,82 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::Translations::BatchesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:product) { create(:product, name: 'Espresso Machine', store: store) }
+ let!(:option_type) { create(:option_type, name: 'size', presentation: 'Size') }
+ let!(:option_value) { create(:option_value, name: 'small', presentation: 'Small', option_type: option_type) }
+
+ before do
+ configure_supported_locales(store, %w[en de fr])
+ request.headers.merge!(headers)
+ end
+
+ describe 'POST #create' do
+ it 'upserts translations across multiple resource types in one request' do
+ post :create, params: {
+ translations: [
+ { resource_type: 'product', resource_id: product.prefixed_id, values: { de: { name: 'Espressomaschine' } } },
+ { resource_type: 'option_type', resource_id: option_type.prefixed_id, values: { de: { label: 'Größe' } } },
+ { resource_type: 'option_value', resource_id: option_value.prefixed_id, values: { de: { label: 'Klein' } } }
+ ]
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].size).to eq(3)
+
+ Mobility.with_locale(:de) do
+ expect(product.reload.name).to eq('Espressomaschine')
+ expect(option_type.reload.presentation).to eq('Größe')
+ expect(option_value.reload.presentation).to eq('Klein')
+ end
+ end
+
+ it 'is atomic: one invalid entry rolls back the whole batch' do
+ post :create, params: {
+ translations: [
+ { resource_type: 'option_type', resource_id: option_type.prefixed_id, values: { de: { label: 'Größe' } } },
+ # unsupported locale → 422, must roll back the option_type write above
+ { resource_type: 'option_value', resource_id: option_value.prefixed_id, values: { es: { label: 'Pequeño' } } }
+ ]
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ Mobility.with_locale(:de) { expect(option_type.reload.presentation).to eq('Size') }
+ end
+
+ it 'reports the offending entry index for an unknown resource type' do
+ post :create, params: {
+ translations: [
+ { resource_type: 'product', resource_id: product.prefixed_id, values: { de: { name: 'X' } } },
+ { resource_type: 'unicorn', resource_id: 'u_1', values: { de: { name: 'Y' } } }
+ ]
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(json_response['error']['details']['translations']).to have_key('1')
+ end
+
+ it 'returns 404-equivalent 422 for a resource missing in the current store' do
+ post :create, params: {
+ translations: [
+ { resource_type: 'product', resource_id: 'prod_NotReal', values: { de: { name: 'X' } } }
+ ]
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+
+ it 'rejects an empty batch' do
+ post :create, params: { translations: [] }, as: :json
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+
+ it 'rejects a non-array translations param with 422, not a 500' do
+ post :create, params: { translations: { resource_type: 'product' } }, as: :json
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/translations_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/translations_controller_spec.rb
new file mode 100644
index 0000000000..d7b683b28c
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/translations_controller_spec.rb
@@ -0,0 +1,70 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::TranslationsController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:product) { create(:product, name: 'Espresso Machine', store: store) }
+
+ before do
+ configure_supported_locales(store, %w[en de fr])
+ request.headers.merge!(headers)
+ end
+
+ describe 'GET #index' do
+ before { Mobility.with_locale(:de) { product.update!(name: 'Espressomaschine') } }
+
+ it 'returns the translation matrix, fields, and locales for the parent' do
+ get :index, params: { product_id: product.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ data = json_response['data']
+ expect(data['resource_type']).to eq('product')
+ expect(data['resource_id']).to eq(product.prefixed_id)
+ expect(data['default_locale']).to eq('en')
+ expect(data['supported_locales']).to match_array(%w[en de fr])
+ expect(data['translations']['de']['name']).to eq('Espressomaschine')
+
+ name_field = data['fields'].find { |f| f['key'] == 'name' }
+ expect(name_field['source']).to eq('Espresso Machine')
+ expect(name_field['type']).to eq('string')
+ end
+
+ it 'returns 404 for a missing parent' do
+ get :index, params: { product_id: 'prod_NotReal' }, as: :json
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ context 'when the parent has translatable children (option type → values)' do
+ let!(:option_type) { create(:option_type, name: 'size', presentation: 'Size') }
+ let!(:option_value) { create(:option_value, name: 'small', presentation: 'Small', option_type: option_type) }
+
+ it 'nests each option value matrix under the option type translations' do
+ Mobility.with_locale(:de) { option_value.update!(presentation: 'Klein') }
+
+ get :index, params: { option_type_id: option_type.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ data = json_response['data']
+ expect(data['resource_type']).to eq('option_type')
+ expect(data['fields'].first['key']).to eq('label')
+
+ child = data['children'].find { |c| c['resource_id'] == option_value.prefixed_id }
+ expect(child['resource_type']).to eq('option_value')
+ expect(child['translations']['de']['label']).to eq('Klein')
+ end
+ end
+
+ context 'when the parent param resolves to nothing translatable' do
+ it 'has no route for a non-translatable parent' do
+ # tax_categories are not in Spree.translatable_resources and the
+ # :translatable concern is not mounted on them, so no nested
+ # translations route exists — the resource cannot be translated at all.
+ expect {
+ get :index, params: { tax_category_id: 'tax_1' }, as: :json
+ }.to raise_error(ActionController::UrlGenerationError)
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/locales_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/locales_spec.rb
new file mode 100644
index 0000000000..c2fd53a51f
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/locales_spec.rb
@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Locales API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ before { configure_supported_locales(store, %w[en de fr]) }
+
+ path '/api/v3/admin/locales' do
+ get 'List supported locales' do
+ tags 'Settings'
+ produces 'application/json'
+ 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."
+ admin_scope :read, :settings
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'locales found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.pluck('code')).to include('en', 'de', 'fr')
+ expect(data.find { |l| l['code'] == 'en' }['default']).to be(true)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/products/translations_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/products/translations_spec.rb
new file mode 100644
index 0000000000..a2953f49f8
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/products/translations_spec.rb
@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Product Translations API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let!(:product) { create(:product, name: 'Espresso Machine', store: store) }
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ before { configure_supported_locales(store, %w[en de fr]) }
+
+ path '/api/v3/admin/products/{product_id}/translations' do
+ let(:product_id) { product.prefixed_id }
+
+ get 'List product translations' do
+ tags 'Products'
+ produces 'application/json'
+ 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.'
+ admin_scope :read, :products
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :product_id, in: :path, type: :string, required: true
+
+ response '200', 'translations found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ before { Mobility.with_locale(:de) { product.update!(name: 'Espressomaschine') } }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data['resource_type']).to eq('product')
+ expect(data['default_locale']).to eq('en')
+ expect(data['translations']['de']['name']).to eq('Espressomaschine')
+ end
+ end
+ end
+
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/translatable_resources_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/translatable_resources_spec.rb
new file mode 100644
index 0000000000..2837211f77
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/translatable_resources_spec.rb
@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Translatable Resources API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ path '/api/v3/admin/translatable_resources' do
+ get 'List translatable resources' do
+ tags 'Settings'
+ produces 'application/json'
+ 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.'
+ admin_scope :read, :settings
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'translatable resources found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data).to be_an(Array)
+ expect(data.pluck('resource_type')).to include('product')
+ expect(data.find { |r| r['resource_type'] == 'product' }['readable']).to be(true)
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/translations/batch_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/translations/batch_spec.rb
new file mode 100644
index 0000000000..086efdc6b9
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/translations/batch_spec.rb
@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Translations Batch API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+
+ let!(:option_type) { create(:option_type, name: 'size', presentation: 'Size') }
+ let!(:option_value) { create(:option_value, name: 'small', presentation: 'Small', option_type: option_type) }
+
+ before { configure_supported_locales(store, %w[en de fr]) }
+
+ path '/api/v3/admin/translations/batch' do
+ post 'Batch upsert translations' do
+ tags 'Settings'
+ consumes 'application/json'
+ produces 'application/json'
+ 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.'
+ admin_scope_note('`write_<resource>` for every resource type in the batch (for API-key authentication)')
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[translations],
+ properties: {
+ translations: {
+ type: :array,
+ items: {
+ type: :object,
+ required: %w[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 }
+ }
+ }
+ }
+ }
+ }
+ }
+
+ response '200', 'translations upserted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) do
+ {
+ translations: [
+ { resource_type: 'option_type', resource_id: option_type.prefixed_id, values: { de: { label: 'Größe' } } },
+ { resource_type: 'option_value', resource_id: option_value.prefixed_id, values: { de: { label: 'Klein' } } }
+ ]
+ }
+ end
+
+ run_test! do |response|
+ data = JSON.parse(response.body)['data']
+ expect(data.size).to eq(2)
+ Mobility.with_locale(:de) { expect(option_type.reload.presentation).to eq('Größe') }
+ end
+ end
+
+ response '422', 'unsupported locale rolls back the whole batch' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) do
+ { translations: [{ resource_type: 'option_type', resource_id: option_type.prefixed_id, values: { es: { label: 'Talla' } } }] }
+ end
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/support/translation_locales_helper.rb b/spree/api/spec/support/translation_locales_helper.rb
new file mode 100644
index 0000000000..95247eaaef
--- /dev/null
+++ b/spree/api/spec/support/translation_locales_helper.rb
@@ -0,0 +1,41 @@
+# Configures the effective supported locales for a store in specs, accounting
+# for markets being the source of truth when present. Setting only the
+# `supported_locales` column is silently ignored once a store has markets
+# (see Spree::Stores::Markets#supported_locales_list), which makes
+# locale-dependent specs order-flaky.
+module TranslationLocalesHelper
+ # @param store [Spree::Store]
+ # @param locales [Array<String>] e.g. %w[en de fr]; the first is the default
+ def configure_supported_locales(store, locales)
+ default = locales.first
+ csv = locales.join(',')
+
+ # update_column (not update!) bypasses ActiveModel dirty-checking. The
+ # shared @default_store is created in before(:all) (the outer transaction);
+ # each example's savepoint rolls back its writes, but the in-memory object
+ # keeps the new value — so a later update!(supported_locales: same_value)
+ # is a no-op (no dirty attr) and the DB stays at its rolled-back state.
+ # update_column always issues the UPDATE.
+ store.update_column(:default_locale, default)
+ store.update_column(:supported_locales, csv)
+
+ store.markets.reload.each do |market|
+ market.update_column(:supported_locales, csv)
+ market.update_column(:default_locale, default)
+ market.remove_instance_variable(:@supported_locales_list) if market.instance_variable_defined?(:@supported_locales_list)
+ end
+
+ clear_locale_memoization(store)
+ store
+ end
+
+ def clear_locale_memoization(store)
+ %i[@supported_locales_list @has_markets].each do |ivar|
+ store.remove_instance_variable(ivar) if store.instance_variable_defined?(ivar)
+ end
+ end
+end
+
+RSpec.configure do |config|
+ config.include TranslationLocalesHelper
+end
diff --git a/spree/core/app/helpers/spree/base_helper.rb b/spree/core/app/helpers/spree/base_helper.rb
index ea55629dc7..b46ad6935c 100644
--- a/spree/core/app/helpers/spree/base_helper.rb
+++ b/spree/core/app/helpers/spree/base_helper.rb
@@ -118,7 +118,7 @@ module Spree
Spree.t(
country.iso,
scope: 'country_names',
- default: Spree::LocalizedNames.country_name(country.iso, fallback: country.name)
+ default: country.localized_name
)
end
diff --git a/spree/core/app/helpers/spree/currency_helper.rb b/spree/core/app/helpers/spree/currency_helper.rb
index ac1b7d0e5c..22a7ff7e0e 100644
--- a/spree/core/app/helpers/spree/currency_helper.rb
+++ b/spree/core/app/helpers/spree/currency_helper.rb
@@ -36,7 +36,7 @@ module Spree
# @param currency [String] the currency ISO code
# @return [Array] the currency presentation and ISO code
def currency_presentation(currency)
- [Spree::LocalizedNames.currency_label(currency), currency]
+ [Spree::Currency.new(code: currency).label, currency]
end
def currency_money(currency = current_currency)
diff --git a/spree/core/app/helpers/spree/locale_helper.rb b/spree/core/app/helpers/spree/locale_helper.rb
index 033d5fc761..8547520791 100644
--- a/spree/core/app/helpers/spree/locale_helper.rb
+++ b/spree/core/app/helpers/spree/locale_helper.rb
@@ -32,11 +32,7 @@ module Spree
end
def locale_presentation(locale)
- [Spree::LocalizedNames.locale_label(locale), locale.to_s]
- end
-
- def locale_full_name(locale)
- Spree.t('i18n.this_file_language', locale: locale)
+ [Spree::Locale.new(code: locale).label, locale.to_s]
end
def should_render_locale_dropdown?
diff --git a/spree/core/app/helpers/spree/localized_names_helper.rb b/spree/core/app/helpers/spree/localized_names_helper.rb
index 6696c7845a..897dccec3b 100644
--- a/spree/core/app/helpers/spree/localized_names_helper.rb
+++ b/spree/core/app/helpers/spree/localized_names_helper.rb
@@ -7,7 +7,7 @@ module Spree
content_tag(
:span,
- Spree::LocalizedNames.locale_label(code),
+ Spree::Locale.new(code: code).label,
data: {
controller: 'display-name',
display_name_type_value: 'language',
@@ -19,7 +19,7 @@ module Spree
# @param countries [Enumerable<Spree::Country>]
# @return [Array<Array>]
def country_select_options(countries)
- countries.map { |country| [Spree::LocalizedNames.country_option_label(country), country.id] }
+ countries.map { |country| [country.option_label, country.id] }
end
end
end
diff --git a/spree/core/app/models/concerns/spree/presentation_translatable.rb b/spree/core/app/models/concerns/spree/presentation_translatable.rb
new file mode 100644
index 0000000000..3d5d678083
--- /dev/null
+++ b/spree/core/app/models/concerns/spree/presentation_translatable.rb
@@ -0,0 +1,39 @@
+module Spree
+ # Shared by models whose single translatable field is the legacy
+ # +presentation+ column exposed publicly as +label+ (OptionType, OptionValue).
+ # Carries the Mobility setup, the translation-table normalizer, the
+ # locale-aware +label+/+label=+ bridge, and the +label → presentation+
+ # translation-matrix alias in one place so the two models don't restate it.
+ module PresentationTranslatable
+ extend ActiveSupport::Concern
+ include Spree::TranslatableResource
+
+ TRANSLATABLE_FIELDS = %i[presentation].freeze
+
+ included do
+ translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
+
+ self::Translation.class_eval do
+ normalizes :presentation, with: ->(value) { value&.to_s&.squish&.presence }
+ end
+ end
+
+ class_methods do
+ # The translation matrix uses +label+ (the public API name) for read/write
+ # symmetry; the +label+/+label=+ bridge below routes it to +presentation+.
+ def translatable_field_aliases
+ { label: :presentation }
+ end
+ end
+
+ # alias_attribute bypasses Mobility's locale-aware reader/writer, so these
+ # explicit delegations are required to keep +label+ translation-aware.
+ def label(*args, **kwargs)
+ presentation(*args, **kwargs)
+ end
+
+ def label=(value)
+ self.presentation = value
+ end
+ end
+end
diff --git a/spree/core/app/models/concerns/spree/stores/markets.rb b/spree/core/app/models/concerns/spree/stores/markets.rb
index 4ac6037882..3cc02772df 100644
--- a/spree/core/app/models/concerns/spree/stores/markets.rb
+++ b/spree/core/app/models/concerns/spree/stores/markets.rb
@@ -91,7 +91,8 @@ module Spree
end
end
- # Returns supported locales derived from markets, falling back to store attributes
+ # Supported locale codes derived from markets, falling back to store
+ # attributes.
# @return [Array<String>]
def supported_locales_list
@supported_locales_list ||= if has_markets?
@@ -101,6 +102,13 @@ module Spree
end
end
+ # Supported locales as rich Spree::Locale objects (name, default?, rtl?).
+ # The string-code form is +supported_locales_list+.
+ # @return [Array<Spree::Locale>]
+ def supported_locales
+ @supported_locales ||= supported_locales_list.map { |code| Spree::Locale.new(code: code) }
+ end
+
# Returns true if the store has markets, false otherwise
# @return [Boolean]
def has_markets?
diff --git a/spree/core/app/models/concerns/spree/translatable_resource.rb b/spree/core/app/models/concerns/spree/translatable_resource.rb
index d1f135909e..76986cb12a 100644
--- a/spree/core/app/models/concerns/spree/translatable_resource.rb
+++ b/spree/core/app/models/concerns/spree/translatable_resource.rb
@@ -5,11 +5,6 @@ module Spree
included do
extend Mobility
default_scope { i18n }
-
- def get_field_with_locale(locale, field_name, fallback: false)
- # method will return nil if no translation is present due to fallback: false setting
- public_send(field_name, locale: locale, fallback: fallback)
- end
end
class_methods do
@@ -17,6 +12,39 @@ module Spree
const_get(:TRANSLATABLE_FIELDS)
end
+ # Maps a public API field name to the internal Mobility field, for models
+ # whose translatable column has a legacy name (e.g. OptionType exposes
+ # +label+ but stores +presentation+). The public name is what the API
+ # serializer and translation matrix use; the writer alias (+label=+)
+ # already routes to the internal field through Mobility. Override per
+ # model; default is identity.
+ #
+ # @return [Hash{Symbol=>Symbol}] public_name => internal_field
+ def translatable_field_aliases
+ {}
+ end
+
+ # The translatable fields by their PUBLIC API name (read/write symmetry),
+ # substituting any aliased public name for the internal field.
+ #
+ # @return [Array<Symbol>]
+ def public_translatable_fields
+ inverse = translatable_field_aliases.invert
+ translatable_fields.map { |field| inverse[field] || field }
+ end
+
+ # Translatable fields that hold rich text (HTML). Drives generic editor
+ # rendering — the translation matrix tags these as +html+ so the SPA shows
+ # a rich-text editor instead of a plain input. A +text+ column is
+ # type-indistinguishable from a plain string, so the model must declare
+ # which of its fields are rich text (via a +RICH_TEXT_TRANSLATABLE_FIELDS+
+ # constant). Default is none.
+ #
+ # @return [Array<Symbol>] public field names
+ def translatable_rich_text_fields
+ const_defined?(:RICH_TEXT_TRANSLATABLE_FIELDS) ? const_get(:RICH_TEXT_TRANSLATABLE_FIELDS) : []
+ end
+
def translation_table_alias
"#{self::Translation.table_name}_#{Mobility.normalize_locale(Mobility.locale)}"
end
@@ -25,5 +53,67 @@ module Spree
Arel::Table.new(translation_table_alias)
end
end
+
+ def get_field_with_locale(locale, field_name, fallback: false)
+ # method will return nil if no translation is present due to fallback: false setting
+ public_send(field_name, locale: locale, fallback: fallback)
+ end
+
+ # Upserts per-locale, per-field translations.
+ #
+ # Semantics (omit-to-leave-alone, never implicit-delete):
+ # - a locale absent from +values+ is untouched
+ # - a field absent within a present locale is untouched
+ # - a field set to +""+ writes an empty string (read falls back to source
+ # via Mobility +column_fallback+); +nil+ deletes that cell
+ #
+ # Value normalization (HTML sanitization, slug parameterization) is owned by
+ # the model's own writers — this only routes each value to its setter under
+ # the right locale.
+ #
+ # @param values [Hash{String=>Hash{String=>String,nil}}] locale => { field => value }
+ # @raise [ActiveRecord::RecordInvalid] on an unsupported locale or invalid save
+ # @return [self]
+ def upsert_translations(values)
+ return self if values.blank?
+
+ validate_translation_locales!(values.keys)
+ # Accept (and write) the PUBLIC field names so read/write are symmetric
+ # with the serializer. `label=` etc. delegate to the internal Mobility
+ # field under the active locale.
+ allowed = self.class.public_translatable_fields.map(&:to_s)
+
+ transaction do
+ values.each do |locale, fields|
+ Mobility.with_locale(locale) do
+ fields.to_h.slice(*allowed).each { |field, value| public_send("#{field}=", value) }
+ end
+ end
+ save!
+ end
+
+ self
+ end
+
+ # The store whose supported locales gate which translations are allowed and
+ # which locales the matrix exposes. The record's own store when it has one,
+ # else the current store.
+ def translatable_store
+ return self if is_a?(Spree::Store)
+
+ try(:store) || Spree::Current.store
+ end
+
+ private
+
+ # @raise [ActiveRecord::RecordInvalid] if any locale isn't supported by the store
+ def validate_translation_locales!(locales)
+ supported = translatable_store&.supported_locales_list || []
+ unsupported = locales.map(&:to_s) - supported.map(&:to_s)
+ return if unsupported.empty?
+
+ errors.add(:base, :unsupported_locale, message: "Unsupported locale(s): #{unsupported.join(', ')}")
+ raise ActiveRecord::RecordInvalid, self
+ end
end
end
diff --git a/spree/core/app/models/spree/country.rb b/spree/core/app/models/spree/country.rb
index 8f10010cd4..dd782ea998 100644
--- a/spree/core/app/models/spree/country.rb
+++ b/spree/core/app/models/spree/country.rb
@@ -31,7 +31,7 @@ module Spree
pluck(:name, :id, :iso).map do |name, id, iso|
{
id: id,
- name: Spree::LocalizedNames.country_option_label(new(iso: iso, name: name))
+ name: new(iso: iso, name: name).option_label
}
end.as_json
end
@@ -46,6 +46,27 @@ module Spree
@current_market ||= Spree::Current.store&.market_for_country(self)
end
+ # Display name localized to +locale+ via the countries gem (CLDR), falling
+ # back to the stored +name+ (or the ISO when there is no name) for an
+ # unknown ISO or missing translation.
+ # @param locale [Symbol, String]
+ # @return [String]
+ def localized_name(locale: I18n.locale)
+ fallback = name.presence || iso.to_s
+ data = ISO3166::Country[iso.to_s.upcase]
+ return fallback unless data
+
+ base_locale = locale.to_s.downcase.tr('_', '-').split('-').first
+ (data.translation(base_locale) || data.translation(:en)).presence || fallback
+ end
+
+ # Flag emoji + localized name, for select options.
+ # @param locale [Symbol, String]
+ # @return [String]
+ def option_label(locale: I18n.locale)
+ "#{self.class.iso_to_emoji_flag(iso)} #{localized_name(locale: locale)}"
+ end
+
def <=>(other)
name <=> other.name
end
diff --git a/spree/core/app/models/spree/currency.rb b/spree/core/app/models/spree/currency.rb
new file mode 100644
index 0000000000..e38510b079
--- /dev/null
+++ b/spree/core/app/models/spree/currency.rb
@@ -0,0 +1,47 @@
+module Spree
+ # Virtual model for a currency. Wraps a currency +code+ (ISO 4217) and exposes
+ # its display name and select label — the single home for that logic instead
+ # of being restated in helpers. Mirrors +Spree::Locale+.
+ class Currency
+ include ActiveModel::Model
+ include Comparable
+
+ # @!attribute code
+ # @return [String] the currency code, e.g. "USD", "EUR"
+ attr_accessor :code
+
+ # Display name, e.g. "United States Dollar". Falls back to the code for an
+ # unknown currency.
+ # @return [String]
+ def name
+ # `find` returns nil (it does not raise) for unknown codes.
+ ::Money::Currency.find(code.to_s.upcase)&.name || code.to_s.upcase
+ end
+
+ # Select label, e.g. "USD — United States Dollar".
+ # @return [String]
+ def label
+ upper = code.to_s.upcase
+ return upper if name.blank? || name.casecmp?(code.to_s)
+
+ "#{upper} — #{name}"
+ end
+
+ def to_s
+ code.to_s.upcase
+ end
+
+ # Compare/equality by code so a Currency slots into string-keyed collections.
+ def <=>(other)
+ to_s <=> other.to_s
+ end
+
+ def eql?(other)
+ other.is_a?(Spree::Currency) && to_s == other.to_s
+ end
+
+ def hash
+ to_s.hash
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/locale.rb b/spree/core/app/models/spree/locale.rb
new file mode 100644
index 0000000000..62ee6d713d
--- /dev/null
+++ b/spree/core/app/models/spree/locale.rb
@@ -0,0 +1,104 @@
+module Spree
+ # Virtual model for a supported locale. Wraps a locale +code+ and exposes its
+ # display name, layout direction, and whether it is a store's default — the
+ # single home for that logic (RTL list, name resolution) instead of being
+ # restated in serializers, helpers, and the admin RTL module.
+ class Locale
+ include ActiveModel::Model
+ include Comparable
+
+ # ISO 639-1 language codes that use right-to-left scripts.
+ RTL_LANGUAGE_CODES = %w[ar he fa ur yi].freeze
+
+ # @!attribute code
+ # @return [String] the locale code, e.g. "en", "pt-BR"
+ attr_accessor :code
+
+ # Display name, e.g. "English", "Deutsch". Falls back to the code for an
+ # unknown locale.
+ # @return [String]
+ def name
+ code = self.code.to_s
+
+ if I18n.exists?('spree.i18n.this_file_language', locale: code, fallback: false)
+ return normalize_name(Spree.t('i18n.this_file_language', locale: code))
+ end
+
+ if defined?(SpreeI18n::Locale) && (name = SpreeI18n::Locale.local_language_name(code))
+ return normalize_name(name)
+ end
+
+ return 'English' if code == 'en'
+
+ code
+ end
+
+ # Select label, e.g. "EN — English".
+ # @return [String]
+ def label
+ upper = code.to_s.upcase
+ return upper if name.blank? || name.casecmp?(code.to_s)
+
+ "#{upper} — #{name}"
+ end
+
+ # @return [Spree::Store] the current store
+ def store
+ @store ||= Spree::Store.current
+ end
+
+ # @return [Boolean] whether this is the store's default (source) locale
+ def default?
+ store.present? && code.to_s == store.default_locale.to_s
+ end
+
+ # @return [Boolean] whether the locale uses a right-to-left script
+ def rtl?
+ RTL_LANGUAGE_CODES.include?(language_code)
+ end
+
+ # @return [String] "rtl" or "ltr"
+ def direction
+ rtl? ? 'rtl' : 'ltr'
+ end
+
+ # The base ISO 639-1 language code, dropping any region (e.g. "pt-BR" → "pt").
+ # @return [String]
+ def language_code
+ code.to_s.downcase.tr('_', '-').split('-').first
+ end
+
+ def to_s
+ code.to_s
+ end
+
+ # Compare/equality by code so a Locale slots into string-keyed collections
+ # (e.g. `locale == "en"`, `[locale].sort`).
+ def <=>(other)
+ to_s <=> other.to_s
+ end
+
+ def eql?(other)
+ other.is_a?(Spree::Locale) && code.to_s == other.code.to_s
+ end
+
+ def hash
+ code.to_s.hash
+ end
+
+ private
+
+ # Strip a trailing " (CODE)" suffix from Spree I18n locale labels. Uses
+ # plain string ops rather than a regex to avoid polynomial backtracking on
+ # adversarial input (ReDoS).
+ def normalize_name(name)
+ name = name.to_s.rstrip
+ return name unless name.end_with?(')')
+
+ open_paren = name.rindex('(')
+ return name unless open_paren
+
+ name[0...open_paren].rstrip
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/option_type.rb b/spree/core/app/models/spree/option_type.rb
index 7b6f4d73d7..214273e5e2 100644
--- a/spree/core/app/models/spree/option_type.rb
+++ b/spree/core/app/models/spree/option_type.rb
@@ -9,10 +9,16 @@ module Spree
include Spree::UniqueName
include Spree::Metafields
include Spree::Metadata
- include Spree::TranslatableResource
+ # presentation column, exposed publicly as `label` + translated via Mobility.
+ include Spree::PresentationTranslatable
- TRANSLATABLE_FIELDS = %i[presentation].freeze
- translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
+ TRANSLATABLE_FIELDS = Spree::PresentationTranslatable::TRANSLATABLE_FIELDS
+
+ # Option values are translated alongside their type — the translations
+ # endpoint nests their matrices so the editor fetches both in one read.
+ def self.translatable_children
+ :option_values
+ end
self::Translation.class_eval do
normalizes :presentation, with: ->(value) { value&.to_s&.squish&.presence }
@@ -41,16 +47,8 @@ module Spree
has_many :option_type_prototypes, class_name: 'Spree::OptionTypePrototype'
has_many :prototypes, through: :option_type_prototypes, class_name: 'Spree::Prototype'
- # 5.5 API naming bridge (DB column rename in 6.0)
- # NOTE: alias_attribute bypasses Mobility's locale-aware reader/writer,
- # so we define explicit delegating methods instead.
- def label(*args)
- presentation(*args)
- end
-
- def label=(value)
- self.presentation = value
- end
+ # 5.5 API naming bridge (`label` → `presentation`) lives in
+ # Spree::PresentationTranslatable.
#
# Validations
diff --git a/spree/core/app/models/spree/option_value.rb b/spree/core/app/models/spree/option_value.rb
index eecbc77727..019cb7bf96 100644
--- a/spree/core/app/models/spree/option_value.rb
+++ b/spree/core/app/models/spree/option_value.rb
@@ -5,14 +5,10 @@ module Spree
include Spree::ParameterizableName
include Spree::Metafields
include Spree::Metadata
- include Spree::TranslatableResource
+ # presentation column, exposed publicly as `label` + translated via Mobility.
+ include Spree::PresentationTranslatable
- TRANSLATABLE_FIELDS = %i[presentation].freeze
- translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
-
- self::Translation.class_eval do
- normalizes :presentation, with: ->(value) { value&.to_s&.squish&.presence }
- end
+ TRANSLATABLE_FIELDS = Spree::PresentationTranslatable::TRANSLATABLE_FIELDS
#
# Magic methods
@@ -33,16 +29,8 @@ module Spree
has_many :variants, through: :option_value_variants, class_name: 'Spree::Variant'
has_many :products, through: :variants, class_name: 'Spree::Product'
- # 5.5 API naming bridge (DB column rename in 6.0)
- # NOTE: alias_attribute bypasses Mobility's locale-aware reader/writer,
- # so we define explicit delegating methods instead.
- def label(*args)
- presentation(*args)
- end
-
- def label=(value)
- self.presentation = value
- end
+ # 5.5 API naming bridge (`label` → `presentation`) lives in
+ # Spree::PresentationTranslatable.
#
# Validations
diff --git a/spree/core/app/models/spree/policy.rb b/spree/core/app/models/spree/policy.rb
index b42236cffb..545334613c 100644
--- a/spree/core/app/models/spree/policy.rb
+++ b/spree/core/app/models/spree/policy.rb
@@ -21,6 +21,7 @@ module Spree
# Translations
#
TRANSLATABLE_FIELDS = %i[name body].freeze
+ RICH_TEXT_TRANSLATABLE_FIELDS = %i[body].freeze
translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
#
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index d1c07e2c4b..952a7e3431 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -56,6 +56,7 @@ module Spree
}.freeze
TRANSLATABLE_FIELDS = %i[name description slug meta_description meta_title].freeze
+ RICH_TEXT_TRANSLATABLE_FIELDS = %i[description].freeze
translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
self::Translation.class_eval do
diff --git a/spree/core/app/models/spree/taxon.rb b/spree/core/app/models/spree/taxon.rb
index 1d873da20b..5325dab6e1 100644
--- a/spree/core/app/models/spree/taxon.rb
+++ b/spree/core/app/models/spree/taxon.rb
@@ -127,6 +127,7 @@ module Spree
# Translations
#
TRANSLATABLE_FIELDS = %i[name pretty_name description permalink].freeze
+ RICH_TEXT_TRANSLATABLE_FIELDS = %i[description].freeze
translates(*TRANSLATABLE_FIELDS, column_fallback: !Spree.always_use_translations?)
#
diff --git a/spree/core/app/models/spree/translations/batch.rb b/spree/core/app/models/spree/translations/batch.rb
new file mode 100644
index 0000000000..bac8da2f16
--- /dev/null
+++ b/spree/core/app/models/spree/translations/batch.rb
@@ -0,0 +1,104 @@
+module Spree
+ module Translations
+ # Atomically upserts translations across MANY records of (possibly)
+ # different translatable resource types in one operation — the domain
+ # behind +POST /api/v3/admin/translations/batch+.
+ #
+ # The input is a flat list of independent registry writes, each naming its
+ # own +resource_type+ + +resource_id+ (no nested parent-owns-children
+ # payload), so there's no per-model branching. Records are resolved within
+ # the current store, then upserted in a single transaction: any failure
+ # rolls back the whole batch and surfaces the offending entry's index via a
+ # typed {EntryError}.
+ #
+ # @example
+ # Spree::Translations::Batch.new(entries).process! do |record|
+ # authorize!(:update, record)
+ # end
+ class Batch
+ include ActiveModel::Model
+
+ # Raised when the batch payload is empty (or not a list of entries).
+ class EmptyError < StandardError; end
+
+ # Raised when an entry can't be processed — unknown/non-translatable
+ # resource type, a record missing in the current store, or an invalid
+ # save. Carries the entry +index+ so the caller can map the error back to
+ # the offending row.
+ class EntryError < StandardError
+ attr_reader :index
+
+ def initialize(message, index)
+ @index = index
+ super(message)
+ end
+ end
+
+ # @return [Array<Spree.base_class>] records written by the last successful {#process!}
+ attr_reader :records
+
+ # @param entries [Array<Hash>] [{ resource_type:, resource_id:, values: { locale => { field => value } } }]
+ def initialize(entries)
+ @entries = Array(entries)
+ @records = []
+ end
+
+ # Distinct +write_<resource>+ scopes a caller needs to authorize this
+ # batch — one per resource type present. Lets the API layer gate an
+ # API-key request without re-deriving scope names.
+ # @return [Array<String>]
+ def required_scopes
+ @entries.map { |entry| "write_#{entry[:resource_type].to_s.pluralize}" }.uniq
+ end
+
+ # Upserts every entry in one transaction. Yields each resolved record
+ # before it is written so the caller can authorize it; a raised error in
+ # the block (or any entry failure) rolls back the whole batch.
+ #
+ # @yieldparam record [Spree.base_class] the resolved record, pre-write
+ # @raise [EmptyError] when there are no entries
+ # @raise [EntryError] when an entry can't be resolved or saved
+ # @return [Array<Spree.base_class>] the written records
+ def process!
+ raise EmptyError if @entries.empty?
+
+ @records = []
+ ActiveRecord::Base.transaction do
+ @entries.each_with_index do |entry, index|
+ record = resolve_record!(entry, index)
+ yield record if block_given?
+ upsert!(record, entry[:values], index)
+ @records << record
+ end
+ end
+ @records
+ end
+
+ private
+
+ def upsert!(record, values, index)
+ record.upsert_translations(values)
+ rescue ActiveRecord::RecordInvalid => e
+ raise EntryError.new(e.record.errors.full_messages.join(', '), index)
+ end
+
+ def resolve_record!(entry, index)
+ klass = resource_class(entry[:resource_type])
+ raise EntryError.new("Unknown translatable resource type: #{entry[:resource_type]}", index) if klass.nil?
+
+ relation = klass.respond_to?(:for_store) ? klass.for_store(Spree::Store.current) : klass
+ relation.find_by_prefix_id!(entry[:resource_id])
+ rescue ActiveRecord::RecordNotFound
+ raise EntryError.new("Resource not found: #{entry[:resource_id]}", index)
+ end
+
+ # Memoized per instance so a batch of N entries doesn't rebuild the
+ # registry map N times. A Batch is request-scoped, so dev-mode class
+ # reloads are still picked up on the next request.
+ def resource_class(token)
+ @resource_class_map ||= Hash.new { |h, t| h[t] = Spree::Translations.resource_class(t) }
+ @resource_class_map[token]
+ end
+ end
+ end
+end
diff --git a/spree/core/lib/spree/core.rb b/spree/core/lib/spree/core.rb
index e40b140a4d..ffba03a11f 100644
--- a/spree/core/lib/spree/core.rb
+++ b/spree/core/lib/spree/core.rb
@@ -492,8 +492,8 @@ require 'spree/translation_migrations'
require 'spree/core/engine'
require 'spree/i18n'
-require 'spree/localized_names'
require 'spree/localized_number'
+require 'spree/translations'
require 'spree/money'
require 'spree/permitted_attributes'
require 'spree/service_module'
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index 59ca601972..0dab70a661 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -244,6 +244,7 @@ module Spree
Rails.application.config.spree.translatable_resources = [
Spree::OptionType,
+ Spree::OptionValue,
Spree::Product,
Spree::Taxon,
Spree::Taxonomy,
diff --git a/spree/core/lib/spree/localized_names.rb b/spree/core/lib/spree/localized_names.rb
deleted file mode 100644
index aba7106b28..0000000000
--- a/spree/core/lib/spree/localized_names.rb
+++ /dev/null
@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-require 'countries'
-
-module Spree
- # Localized display names for countries, currencies, and locales.
- #
- # Country names come from the +countries+ gem (CLDR translations) in the
- # current +I18n.locale+. Currency and language names use the Money gem and
- # Spree I18n bundles (not locale-aware server-side); the admin Stimulus
- # +display-name+ controller upgrades those labels client-side via
- # +Intl.DisplayNames+ when available — matching the React dashboard.
- module LocalizedNames
- module_function
-
- # @param code [String, Symbol]
- # @param name [String]
- # @return [String] e.g. "EN — English"
- def format_code_name(code, name)
- upper = code.to_s.upcase
- label = name.to_s
- return upper if label.blank? || label.casecmp?(code.to_s)
-
- "#{upper} — #{label}"
- end
-
- # @param iso [String]
- # @param locale [Symbol, String]
- # @param fallback [String, nil]
- # @return [String]
- def country_name(iso, locale: I18n.locale, fallback: nil)
- iso = iso.to_s.upcase
- fallback ||= iso
-
- data = ISO3166::Country[iso]
- return fallback unless data
-
- translation = data.translation(display_locale(locale)) || data.translation(:en)
- translation.presence || fallback
- end
-
- # @param country [Spree::Country]
- # @param locale [Symbol, String]
- # @return [String]
- def country_option_label(country, locale: I18n.locale)
- name = country_name(country.iso, locale: locale, fallback: country.name)
- "#{Spree::Country.iso_to_emoji_flag(country.iso)} #{name}"
- end
-
- # @param code [String]
- # @return [String]
- def currency_name(code)
- code = code.to_s.upcase
- # Fully-qualified: bare `Money` resolves to Spree::Money inside this module.
- # `find` returns nil (it does not raise) for unknown codes.
- ::Money::Currency.find(code)&.name || code
- end
-
- # @param code [String]
- # @return [String]
- def currency_label(code)
- format_code_name(code, currency_name(code))
- end
-
- # @param code [String, Symbol]
- # @return [String]
- def language_name(code)
- code = code.to_s
-
- if I18n.exists?('spree.i18n.this_file_language', locale: code, fallback: false)
- return normalize_language_name(Spree.t('i18n.this_file_language', locale: code))
- end
-
- if defined?(SpreeI18n::Locale) && (name = SpreeI18n::Locale.local_language_name(code))
- return normalize_language_name(name)
- end
-
- return 'English' if code == 'en'
-
- code
- end
-
- # @param code [String, Symbol]
- # @return [String]
- def locale_label(code)
- format_code_name(code, language_name(code))
- end
-
- # @param locale [Symbol, String]
- # @return [String]
- def display_locale(locale)
- locale.to_s.downcase.tr('_', '-').split('-').first
- end
-
- # Strip a trailing " (CODE)" suffix from Spree I18n locale labels.
- # Uses plain string ops rather than a regex to avoid polynomial
- # backtracking on adversarial input (ReDoS).
- # @param name [String]
- # @return [String]
- def normalize_language_name(name)
- name = name.to_s.rstrip
- return name unless name.end_with?(')')
-
- open_paren = name.rindex('(')
- return name unless open_paren
-
- name[0...open_paren].rstrip
- end
- end
-end
diff --git a/spree/core/lib/spree/translations.rb b/spree/core/lib/spree/translations.rb
new file mode 100644
index 0000000000..9ff1d9de28
--- /dev/null
+++ b/spree/core/lib/spree/translations.rb
@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Spree
+ # Builds the admin translation matrix, field-discovery metadata, and the
+ # public translatable-resource registry for records in
+ # +Spree.translatable_resources+. Stateless helper shared by the dedicated
+ # translations endpoint, the +?expand=translations+ serializer attribute, the
+ # batch write controller, and the discovery endpoint.
+ module Translations
+ module_function
+
+ # @return [Hash{String=>Hash}] locale => { field => value, "translated_field_count" => Integer }
+ def matrix_for(record, locales: nil)
+ fields = field_keys(record)
+ locales ||= non_default_locales(record)
+
+ locales.index_with do |locale|
+ translated = field_values(record, locale, fields)
+ translated.merge('translated_field_count' => translated.count { |_k, v| v.present? })
+ end
+ end
+
+ # @return [Array<Hash>] [{ "key" => "name", "type" => "string", "source" => "Espresso Machine" }, ...]
+ def fields_for(record)
+ Mobility.with_locale(default_locale(record)) do
+ field_keys(record).map do |field|
+ { 'key' => field, 'type' => field_type(record.class, field), 'source' => record.public_send(field) }
+ end
+ end
+ end
+
+ # @return [Array<Hash>] registry made public: [{ "resource_type" => "product", "fields" => [{key,type}] }]
+ def registry
+ Spree.translatable_resources.map do |klass|
+ {
+ 'resource_type' => public_resource_type(klass),
+ 'fields' => klass.public_translatable_fields.map { |f| { 'key' => f.to_s, 'type' => field_type(klass, f) } }
+ }
+ end
+ end
+
+ # @return [String] underscored, demodulized model name (e.g. "option_type")
+ def resource_type(klass)
+ klass.name.demodulize.underscore
+ end
+
+ # The PUBLIC resource-type token used in read (document/registry) and
+ # write (batch) payloads. Taxon is exposed as "category" (routes use the
+ # 5.5 rename) while the model element stays "taxon"; this keeps the read
+ # and write contracts consistent.
+ #
+ # @return [String]
+ def public_resource_type(klass)
+ return 'category' if klass <= Spree::Taxon
+
+ resource_type(klass)
+ end
+
+ # Inverse of +public_resource_type+: maps a public token to its
+ # registered translatable class, or nil if not translatable.
+ #
+ # @param token [String, Symbol] e.g. "product", "option_value", "category"
+ # @return [Class, nil]
+ def resource_class(token)
+ # Recomputed per call (not memoized) so a dev-mode class reload of a
+ # registry member doesn't leave a stale class reference behind.
+ map = Spree.translatable_resources.index_by { |klass| public_resource_type(klass) }
+ map[token.to_s]
+ end
+
+ # The editor type for a translatable field: +html+ when the model declares
+ # it as rich text (drives a rich-text editor in the SPA), else +string+.
+ # @param klass [Class] a translatable model
+ # @param field [String, Symbol] public field name
+ # @return [String]
+ def field_type(klass, field)
+ klass.translatable_rich_text_fields.map(&:to_sym).include?(field.to_sym) ? 'html' : 'string'
+ end
+
+ # Public field names, so the matrix read/write keys match the serializer
+ # (e.g. OptionType exposes `label`, not the internal `presentation`).
+ def field_keys(record)
+ record.class.public_translatable_fields.map(&:to_s)
+ end
+ private_class_method :field_keys
+
+ def field_values(record, locale, fields)
+ Mobility.with_locale(locale) do
+ fields.index_with do |field|
+ # fallback: false so an absent translation reads as nil, not the source value
+ record.public_send(field, fallback: false)
+ rescue ArgumentError
+ # fields without a Mobility reader signature still respond to the bare getter
+ record.public_send(field)
+ end
+ end
+ end
+ private_class_method :field_values
+
+ def default_locale(record)
+ record.translatable_store&.default_locale || I18n.default_locale.to_s
+ end
+ private_class_method :default_locale
+
+ def non_default_locales(record)
+ store = record.translatable_store
+ return [] unless store
+
+ (store.supported_locales_list - [store.default_locale]).sort
+ end
+ private_class_method :non_default_locales
+ end
+end
diff --git a/spree/core/spec/lib/spree/localized_names_spec.rb b/spree/core/spec/lib/spree/localized_names_spec.rb
deleted file mode 100644
index b59a48341a..0000000000
--- a/spree/core/spec/lib/spree/localized_names_spec.rb
+++ /dev/null
@@ -1,97 +0,0 @@
-require 'spec_helper'
-
-describe Spree::LocalizedNames do
- describe '.format_code_name' do
- it 'formats code and name' do
- expect(described_class.format_code_name('en', 'English')).to eq('EN — English')
- end
-
- it 'returns uppercased code when name matches code' do
- expect(described_class.format_code_name('en', 'en')).to eq('EN')
- end
- end
-
- describe '.country_name' do
- it 'returns localized country name' do
- expect(described_class.country_name('US', locale: :en)).to include('United States')
- end
-
- it 'falls back to english then provided fallback' do
- expect(described_class.country_name('US', locale: :zz, fallback: 'Fallback')).to include('United States')
- end
-
- it 'returns the fallback for an unknown ISO code' do
- expect(described_class.country_name('ZZ', fallback: 'Nowhere')).to eq('Nowhere')
- end
- end
-
- describe '.country_option_label' do
- let(:country) { build(:country, iso: 'US', name: 'United States') }
-
- it 'prefixes the localized name with the flag emoji' do
- label = described_class.country_option_label(country, locale: :en)
-
- expect(label).to include('🇺🇸')
- expect(label).to include('United States')
- end
- end
-
- describe '.currency_name' do
- it 'returns the currency name for a known code' do
- expect(described_class.currency_name('EUR')).to eq('Euro')
- end
-
- it 'returns the upcased code for an unknown currency' do
- expect(described_class.currency_name('zzz')).to eq('ZZZ')
- end
- end
-
- describe '.currency_label' do
- it 'formats currency code and name' do
- expect(described_class.currency_label('EUR')).to eq('EUR — Euro')
- end
-
- it 'falls back to the bare code for an unknown currency' do
- expect(described_class.currency_label('zzz')).to eq('ZZZ')
- end
- end
-
- describe '.language_name' do
- it 'returns English for the en locale without a translation bundle' do
- expect(described_class.language_name('en')).to eq('English')
- end
-
- it 'returns the raw code when no language name is resolvable' do
- expect(described_class.language_name('klingon')).to eq('klingon')
- end
- end
-
- describe '.normalize_language_name' do
- it 'strips a trailing parenthetical suffix' do
- expect(described_class.normalize_language_name('Deutsch (DE)')).to eq('Deutsch')
- end
-
- it 'leaves a name without a parenthetical untouched' do
- expect(described_class.normalize_language_name('English')).to eq('English')
- end
- end
-
- describe '.locale_label' do
- before do
- I18n.backend.store_translations(:de,
- spree: {
- i18n: {
- this_file_language: 'Deutsch (DE)'
- }
- })
- end
-
- it 'formats locale code and language name' do
- expect(described_class.locale_label(:de)).to eq('DE — Deutsch')
- end
-
- it 'formats english locale' do
- expect(described_class.locale_label(:en)).to eq('EN — English')
- end
- end
-end
diff --git a/spree/core/spec/lib/spree/translations_spec.rb b/spree/core/spec/lib/spree/translations_spec.rb
new file mode 100644
index 0000000000..1419698f7a
--- /dev/null
+++ b/spree/core/spec/lib/spree/translations_spec.rb
@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Translations do
+ let(:store) { @default_store }
+ let!(:product) { create(:product, name: 'Espresso Machine', store: store) }
+
+ before do
+ store.update!(supported_locales: 'en,de,fr')
+ allow(Spree::Current).to receive(:store).and_return(store)
+ Mobility.with_locale(:de) { product.update!(name: 'Espressomaschine', meta_title: 'DE Title') }
+ end
+
+ describe '.matrix_for' do
+ subject { described_class.matrix_for(product) }
+
+ it 'returns a matrix keyed by non-default locale' do
+ expect(subject.keys).to match_array(%w[de fr])
+ end
+
+ it 'fills translated values and a per-locale completeness count' do
+ expect(subject['de']['name']).to eq 'Espressomaschine'
+ expect(subject['de']['meta_title']).to eq 'DE Title'
+ # name + meta_title + the auto-generated localized slug
+ expect(subject['de']['translated_field_count']).to eq 3
+ expect(subject['fr']['name']).to be_nil
+ expect(subject['fr']['translated_field_count']).to eq 0
+ end
+ end
+
+ describe '.fields_for' do
+ subject { described_class.fields_for(product) }
+
+ it 'returns key + type + source for each translatable field' do
+ name_field = subject.find { |f| f['key'] == 'name' }
+ expect(name_field['source']).to eq 'Espresso Machine'
+ expect(name_field['type']).to eq 'string'
+
+ # description is declared rich text; slug is a plain string field
+ expect(subject.find { |f| f['key'] == 'description' }['type']).to eq 'html'
+ expect(subject.find { |f| f['key'] == 'slug' }['type']).to eq 'string'
+ end
+ end
+
+ describe '.registry' do
+ subject { described_class.registry }
+
+ it 'exposes every translatable resource and its fields' do
+ product_entry = subject.find { |r| r['resource_type'] == 'product' }
+ expect(product_entry['fields'].map { |f| f['key'] }).to include('name', 'description', 'slug')
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/concerns/translatable_resource_spec.rb b/spree/core/spec/models/spree/concerns/translatable_resource_spec.rb
new file mode 100644
index 0000000000..cbeb80a210
--- /dev/null
+++ b/spree/core/spec/models/spree/concerns/translatable_resource_spec.rb
@@ -0,0 +1,90 @@
+require 'spec_helper'
+
+# Exercised through Spree::Product, which includes Spree::TranslatableResource.
+RSpec.describe Spree::TranslatableResource, type: :model do
+ let(:store) { @default_store }
+ let!(:product) { create(:product, name: 'Espresso Machine', store: store) }
+
+ before do
+ store.update_column(:supported_locales, 'en,de,fr')
+ allow(Spree::Current).to receive(:store).and_return(store)
+ end
+
+ describe '#upsert_translations' do
+ it 'writes a translation under the given locale, leaving the source untouched' do
+ product.upsert_translations('de' => { 'name' => 'Espressomaschine' })
+
+ Mobility.with_locale(:de) { expect(product.reload.name).to eq 'Espressomaschine' }
+ Mobility.with_locale(:en) { expect(product.reload.name).to eq 'Espresso Machine' }
+ end
+
+ it 'upserts multiple locales and fields in one call' do
+ product.upsert_translations(
+ 'de' => { 'name' => 'Espressomaschine', 'meta_title' => 'DE Title' },
+ 'fr' => { 'name' => 'Machine à espresso' }
+ )
+
+ Mobility.with_locale(:de) do
+ expect(product.reload.name).to eq 'Espressomaschine'
+ expect(product.meta_title).to eq 'DE Title'
+ end
+ Mobility.with_locale(:fr) { expect(product.reload.name).to eq 'Machine à espresso' }
+ end
+
+ it 'only touches fields present in the payload (omit-to-leave-alone)' do
+ product.upsert_translations('de' => { 'name' => 'Alt', 'meta_title' => 'Alt Title' })
+ product.upsert_translations('de' => { 'name' => 'Neu' })
+
+ Mobility.with_locale(:de) do
+ expect(product.reload.name).to eq 'Neu'
+ expect(product.meta_title).to eq 'Alt Title'
+ end
+ end
+
+ it 'ignores fields outside TRANSLATABLE_FIELDS' do
+ product.upsert_translations('de' => { 'name' => 'Espressomaschine', 'status' => 'archived' })
+ expect(product.reload.status).not_to eq 'archived'
+ end
+
+ it 'raises RecordInvalid for an unsupported locale, without writing' do
+ expect {
+ product.upsert_translations('es' => { 'name' => 'Máquina de espresso' })
+ }.to raise_error(ActiveRecord::RecordInvalid, /es/)
+
+ Mobility.with_locale(:es) { expect(product.reload.name).not_to eq 'Máquina de espresso' }
+ end
+ end
+
+ # OptionType exposes the translatable column `presentation` under the public
+ # name `label` — the matrix and upsert use the public name.
+ describe 'public field aliases (OptionType#label → presentation)' do
+ let!(:option_type) { create(:option_type, name: 'size', presentation: 'Size') }
+
+ it 'exposes the public field name' do
+ expect(Spree::OptionType.public_translatable_fields).to eq([:label])
+ end
+
+ it 'upserts via the public name and writes the internal Mobility field' do
+ option_type.upsert_translations('de' => { 'label' => 'Größe' })
+
+ Mobility.with_locale(:de) { expect(option_type.reload.presentation).to eq 'Größe' }
+ Mobility.with_locale(:en) { expect(option_type.reload.presentation).to eq 'Size' }
+ end
+
+ it 'reports untranslated fields as nil in the matrix (fallback honored through the alias)' do
+ matrix = Spree::Translations.matrix_for(option_type, locales: %w[de])
+ expect(matrix.dig('de', 'label')).to be_nil
+ end
+ end
+
+ describe '.translatable_rich_text_fields' do
+ it 'returns the fields a model declares as rich text' do
+ expect(Spree::Product.translatable_rich_text_fields).to eq(%i[description])
+ expect(Spree::Policy.translatable_rich_text_fields).to eq(%i[body])
+ end
+
+ it 'defaults to none when a model declares no rich-text fields' do
+ expect(Spree::OptionType.translatable_rich_text_fields).to eq([])
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/country_spec.rb b/spree/core/spec/models/spree/country_spec.rb
index 39633eaf19..48a07cc5c9 100644
--- a/spree/core/spec/models/spree/country_spec.rb
+++ b/spree/core/spec/models/spree/country_spec.rb
@@ -10,6 +10,25 @@ describe Spree::Country, type: :model do
expect(Spree::Country.new(name: 'Canada', iso: 'CA', iso3: 'CAN', iso_name: 'CANADA')).not_to be_valid
end
+ describe '#localized_name' do
+ it 'returns the localized country name' do
+ expect(described_class.new(iso: 'US', name: 'USA').localized_name(locale: :en)).to include('United States')
+ end
+
+ it 'falls back to the name (then iso) for an unknown ISO' do
+ expect(described_class.new(iso: 'ZZ', name: 'Nowhere').localized_name).to eq('Nowhere')
+ expect(described_class.new(iso: 'ZZ').localized_name).to eq('ZZ')
+ end
+ end
+
+ describe '#option_label' do
+ it 'prefixes the localized name with the flag emoji' do
+ label = described_class.new(iso: 'US', name: 'United States').option_label(locale: :en)
+ expect(label).to include('🇺🇸')
+ expect(label).to include('United States')
+ end
+ end
+
describe '.by_iso' do
let(:dummy_iso) { 'XY' }
diff --git a/spree/core/spec/models/spree/currency_spec.rb b/spree/core/spec/models/spree/currency_spec.rb
new file mode 100644
index 0000000000..2c56922258
--- /dev/null
+++ b/spree/core/spec/models/spree/currency_spec.rb
@@ -0,0 +1,33 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Currency, type: :model do
+ describe '#name' do
+ it 'returns the display name for a known code' do
+ expect(described_class.new(code: 'EUR').name).to eq('Euro')
+ end
+
+ it 'returns the upcased code for an unknown currency' do
+ expect(described_class.new(code: 'zzz').name).to eq('ZZZ')
+ end
+ end
+
+ describe '#label' do
+ it 'formats code and name' do
+ expect(described_class.new(code: 'EUR').label).to eq('EUR — Euro')
+ end
+
+ it 'falls back to the bare code for an unknown currency' do
+ expect(described_class.new(code: 'zzz').label).to eq('ZZZ')
+ end
+ end
+
+ describe 'string-likeness' do
+ it 'stringifies to the upcased code' do
+ expect(described_class.new(code: 'usd').to_s).to eq('USD')
+ end
+
+ it 'is equal to another currency with the same code' do
+ expect(described_class.new(code: 'usd')).to eql(described_class.new(code: 'USD'))
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/locale_spec.rb b/spree/core/spec/models/spree/locale_spec.rb
new file mode 100644
index 0000000000..ef5c9ae987
--- /dev/null
+++ b/spree/core/spec/models/spree/locale_spec.rb
@@ -0,0 +1,76 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Locale, type: :model do
+ describe '#name' do
+ it 'returns the localized display name' do
+ expect(described_class.new(code: 'en').name).to eq('English')
+ end
+
+ it 'falls back to the code for an unknown locale' do
+ expect(described_class.new(code: 'xx').name).to eq('xx')
+ end
+
+ it 'strips a trailing parenthetical from a Spree I18n label' do
+ I18n.backend.store_translations(:de, spree: { i18n: { this_file_language: 'Deutsch (DE)' } })
+ expect(described_class.new(code: 'de').name).to eq('Deutsch')
+ end
+ end
+
+ describe '#label' do
+ it 'formats code and language name' do
+ I18n.backend.store_translations(:de, spree: { i18n: { this_file_language: 'Deutsch (DE)' } })
+ expect(described_class.new(code: 'de').label).to eq('DE — Deutsch')
+ end
+
+ it 'formats the english locale' do
+ expect(described_class.new(code: 'en').label).to eq('EN — English')
+ end
+ end
+
+ # #default? compares the code against the current store's default locale
+ # (Spree::Store.current, i.e. Spree::Current.store).
+ describe '#default?' do
+ let(:store) { build(:store, default_locale: 'en') }
+
+ before { allow(Spree::Current).to receive(:store).and_return(store) }
+
+ it 'is true for the current store default locale' do
+ expect(described_class.new(code: 'en')).to be_default
+ end
+
+ it 'is false for a non-default locale' do
+ expect(described_class.new(code: 'de')).not_to be_default
+ end
+ end
+
+ describe '#rtl? / #direction' do
+ it 'detects right-to-left languages, ignoring region' do
+ expect(described_class.new(code: 'ar')).to be_rtl
+ expect(described_class.new(code: 'he-IL')).to be_rtl
+ expect(described_class.new(code: 'ar').direction).to eq('rtl')
+ end
+
+ it 'treats left-to-right languages as ltr' do
+ expect(described_class.new(code: 'en')).not_to be_rtl
+ expect(described_class.new(code: 'de').direction).to eq('ltr')
+ end
+ end
+
+ describe 'string-likeness' do
+ let(:locale) { described_class.new(code: 'en') }
+
+ it 'stringifies to its code' do
+ expect(locale.to_s).to eq('en')
+ end
+
+ it 'sorts by code' do
+ codes = [described_class.new(code: 'fr'), described_class.new(code: 'de')].sort.map(&:to_s)
+ expect(codes).to eq(%w[de fr])
+ end
+
+ it 'is equal to another locale with the same code (eql?/hash)' do
+ expect(locale).to eql(described_class.new(code: 'en'))
+ expect([locale] - [described_class.new(code: 'en')]).to be_empty
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/translations/batch_spec.rb b/spree/core/spec/models/spree/translations/batch_spec.rb
new file mode 100644
index 0000000000..5098ea1a32
--- /dev/null
+++ b/spree/core/spec/models/spree/translations/batch_spec.rb
@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Translations::Batch do
+ let(:store) { @default_store }
+ let!(:option_type) { create(:option_type, name: 'size', presentation: 'Size') }
+ let!(:option_value) { create(:option_value, name: 'small', presentation: 'Small', option_type: option_type) }
+
+ before do
+ store.update!(supported_locales: 'en,de,fr')
+ allow(Spree::Current).to receive(:store).and_return(store)
+ end
+
+ def entry(type, record, values)
+ { resource_type: type, resource_id: record.prefixed_id, values: values }
+ end
+
+ describe '#process!' do
+ it 'upserts every entry and returns the written records' do
+ batch = described_class.new([
+ entry('option_type', option_type, 'de' => { 'label' => 'Größe' }),
+ entry('option_value', option_value, 'de' => { 'label' => 'Klein' })
+ ])
+
+ records = batch.process!
+
+ expect(records).to contain_exactly(option_type, option_value)
+ Mobility.with_locale(:de) do
+ expect(option_type.reload.presentation).to eq('Größe')
+ expect(option_value.reload.presentation).to eq('Klein')
+ end
+ end
+
+ it 'is atomic: an invalid entry rolls back earlier writes' do
+ batch = described_class.new([
+ entry('option_type', option_type, 'de' => { 'label' => 'Größe' }),
+ # unsupported locale → raises, must roll back the option_type write
+ entry('option_value', option_value, 'es' => { 'label' => 'Pequeño' })
+ ])
+
+ expect { batch.process! }.to raise_error(described_class::EntryError) { |e| expect(e.index).to eq(1) }
+ # The de write rolled back — no German translation persisted.
+ Mobility.with_locale(:de) { expect(option_type.reload.presentation(fallback: false)).to be_nil }
+ expect(option_type.presentation).to eq('Size')
+ end
+
+ it 'raises EntryError with the index for an unknown resource type' do
+ batch = described_class.new([{ resource_type: 'unicorn', resource_id: 'u_1', values: {} }])
+
+ expect { batch.process! }.to raise_error(described_class::EntryError) { |e| expect(e.index).to eq(0) }
+ end
+
+ it 'raises EntryError for a record missing in the current store' do
+ batch = described_class.new([{ resource_type: 'option_type', resource_id: 'opt_NotReal', values: {} }])
+
+ expect { batch.process! }.to raise_error(described_class::EntryError)
+ end
+
+ it 'raises EmptyError when there are no entries' do
+ expect { described_class.new([]).process! }.to raise_error(described_class::EmptyError)
+ end
+
+ it 'yields each resolved record before writing so the caller can authorize' do
+ batch = described_class.new([entry('option_type', option_type, 'de' => { 'label' => 'Größe' })])
+
+ expect { |b| batch.process!(&b) }.to yield_with_args(option_type)
+ end
+ end
+
+ describe '#required_scopes' do
+ it 'returns one write_<resource> scope per distinct resource type' do
+ batch = described_class.new([
+ entry('option_type', option_type, {}),
+ entry('option_value', option_value, {}),
+ entry('option_type', option_type, {})
+ ])
+
+ expect(batch.required_scopes).to contain_exactly('write_option_types', 'write_option_values')
+ end
+ end
+end