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 product video with posters, and rename Asset to Media (#14457)

Damian Legawiec676aa0dee62a
diff --git a/.changeset/product-media-video.md b/.changeset/product-media-video.md
new file mode 100644
index 0000000000..50555ed7ae
--- /dev/null
+++ b/.changeset/product-media-video.md
@@ -0,0 +1,18 @@
+---
+'@spree/admin-sdk': minor
+'@spree/dashboard': minor
+---
+
+Product galleries can hold video.
+
+A media item now says what it is through `media_type`. `video` is a file you upload and serve yourself; `external_video` is a YouTube or Vimeo link. Both sit in the same gallery as images and reorder alongside them.
+
+Spree reads the link when it is saved and rejects anything it cannot embed, so the media object comes back carrying `video_provider`, `video_embed_url`, `video_url` and `poster_url` — a storefront embeds a video without parsing links itself. A video's sized URLs resolve to its poster, so a gallery written for images still renders the right still.
+
+`MediaCreateParams` and `MediaUpdateParams` accept `media_type`, `external_video_url`, `poster_signed_id` and the focal point. The `type` parameter, which named an internal Ruby class, is gone — `media_type` replaces it.
+
+A video carries a **poster** — the still shown before it plays. Upload one with `poster_signed_id`, or leave it off and a YouTube link falls back to the provider's own image. Spree does not extract a frame from an uploaded file, so hosted video and Vimeo links want a poster.
+
+In the dashboard, video files upload through the same drop zone as images, an "Add video link" button takes a YouTube or Vimeo URL, and the media editor plays the video back and takes a poster the merchant uploads. The editor also gains a focal-point picker: click the spot on an image that must stay in frame when a storefront crops it.
+
+Choosing which variants a media item represents happens in one place — the media editor on the product. The unmounted variant-side gallery picker has been removed; it was a second way to edit the same thing.
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 6658a4a979..c6caa71ea4 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -92,16 +92,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjcwZjk4MjEzLTdmNzYtNGIyOC1hNzZmLTFlNmZmNjEwOTQzZCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTkzODgwfQ.SLZkw90Pdye0kOZj3BPXhlrKZ8x_BLlThWXwliBB364
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjVjMTA3MDU4LTVhYjctNDc4ZC05ODQzLWZjYWUxMGQzYTJlYSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg3MDY1NjcwfQ.GnZKiThJWn1GN0nnLe7pu8SG1ig6m-uDGRW0spuDLGs
user:
id: adm_UkLWZg9DAJ
- first_name: Florencio
- last_name: Gutkowski
- full_name: Florencio Gutkowski
+ first_name: Brock
+ last_name: Sawayn
+ full_name: Brock Sawayn
selected_locale:
- created_at: '2026-08-17T19:06:20.978Z'
- updated_at: '2026-08-17T19:06:20.978Z'
+ created_at: '2026-08-18T15:02:50.781Z'
+ updated_at: '2026-08-18T15:02:50.781Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -204,16 +204,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRhZWI0MDE3LThjZDQtNDhhNy1hZjg4LWRkZDViZGIxMTMyNSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTkzODgxfQ.UKpvy4TuFsSqNdxlyLRF1sEQ0AVmRhzkS0naBv6771k
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImE0Yzg0ZDZjLTlmOTEtNDU1MS05ZmI4LTZkZDI2M2Y1Y2NhNiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg3MDY1NjcwfQ.PkRli4LQTYo2KNIbOj8Xx-M1686ZMb8cnCQY-JFqUFc
user:
id: adm_UkLWZg9DAJ
- first_name: Judith
- last_name: Sauer
- full_name: Judith Sauer
+ first_name: Cira
+ last_name: West
+ full_name: Cira West
selected_locale:
- created_at: '2026-08-17T19:06:21.057Z'
- updated_at: '2026-08-17T19:06:21.057Z'
+ created_at: '2026-08-18T15:02:50.897Z'
+ updated_at: '2026-08-18T15:02:50.897Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -315,13 +315,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Charley
- last_name: Hane
- full_name: Charley Hane
+ first_name: Tillie
+ last_name: Yundt
+ full_name: Tillie Yundt
selected_locale:
- created_at: '2026-08-17T19:06:28.026Z'
- updated_at: '2026-08-17T19:06:28.026Z'
+ created_at: '2026-08-18T15:03:03.141Z'
+ updated_at: '2026-08-18T15:03:03.141Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -438,13 +438,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Alba
- last_name: Stamm
- full_name: Alba Stamm
+ first_name: Regine
+ last_name: Ward
+ full_name: Regine Ward
selected_locale: de
- created_at: '2026-08-17T19:06:28.071Z'
- updated_at: '2026-08-17T19:06:28.083Z'
+ created_at: '2026-08-18T15:03:03.220Z'
+ updated_at: '2026-08-18T15:03:03.237Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -638,16 +638,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjdlYmJlZWUyLWUxMDctNGMxMC04MWNkLTI1NDMxMjU3YjNiMSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTk3MTk1fQ.cpLm-PNnKIiG2SYpCEo4I1q0K18Cpn3RiF5l1IFh1e0
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjIzNjg5NzU4LWEzMjQtNDdiNC1iZGQwLWVlNTc2ZTE5ZGIyNiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg3MDY4OTkzfQ.GzGBgXAHM-RBqWez76CKJ6o7EKQn9OCz1DN_Y4LzQZk
user:
id: adm_UkLWZg9DAJ
- first_name: Shenika
- last_name: Williamson
- full_name: Shenika Williamson
+ first_name: Floretta
+ last_name: Kerluke
+ full_name: Floretta Kerluke
selected_locale:
- created_at: '2026-08-17T19:06:35.883Z'
- updated_at: '2026-08-17T19:06:35.898Z'
+ created_at: '2026-08-18T15:03:13.140Z'
+ updated_at: '2026-08-18T15:03:13.154Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -716,7 +716,7 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6Ijk5OGY5NjExLWU4ZjctNDI4Ny04NzRjLTA4NWM3ZTc0YTRjZSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTkzOTAxfQ.9OdzyVS2tjkL4uS2POYV8SryqkgZ0M9eOH-IVKzputU
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRlYzE1ZWQ1LTllYTMtNGExOS05MThkLWIyMjFlMjhhN2VlYSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg3MDY1Njk4fQ.5U4klhl8Edjf3RIgCRKmN0grMgJ-AMv_pfLqE6zgc3A
user:
id: adm_UkLWZg9DAJ
@@ -724,8 +724,8 @@ paths:
last_name: Owner
full_name: Olivia Owner
selected_locale:
- created_at: '2026-08-17T19:06:41.659Z'
- updated_at: '2026-08-17T19:06:41.659Z'
+ created_at: '2026-08-18T15:03:18.747Z'
+ updated_at: '2026-08-18T15:03:18.747Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -2202,8 +2202,8 @@ paths:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-17T19:06:20.504Z'
- updated_at: '2026-08-17T19:06:20.504Z'
+ created_at: '2026-08-18T15:02:49.910Z'
+ updated_at: '2026-08-18T15:02:49.910Z'
meta:
page: 1
limit: 25
@@ -2287,8 +2287,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
- created_at: '2026-08-17T19:06:20.564Z'
- updated_at: '2026-08-17T19:06:20.564Z'
+ created_at: '2026-08-18T15:02:50.052Z'
+ updated_at: '2026-08-18T15:02:50.052Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -2375,8 +2375,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-17T19:06:20.609Z'
- updated_at: '2026-08-17T19:06:20.609Z'
+ created_at: '2026-08-18T15:02:50.194Z'
+ updated_at: '2026-08-18T15:02:50.194Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
@@ -2437,8 +2437,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
- created_at: '2026-08-17T19:06:20.732Z'
- updated_at: '2026-08-17T19:06:20.750Z'
+ created_at: '2026-08-18T15:02:50.277Z'
+ updated_at: '2026-08-18T15:02:50.306Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -2558,34 +2558,34 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-17T19:06:20.811Z'
- updated_at: '2026-08-17T19:06:20.811Z'
+ created_at: '2026-08-18T15:02:50.436Z'
+ updated_at: '2026-08-18T15:02:50.436Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_TbxxZGScuNsxcokt1UiTEX5h
+ plaintext_token: pk_TTacpizicefmkXA2ZZeQynNu
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_1DqNWYSBA
+ token_prefix: sk_jDqsmHJWz
scopes:
- write_all
- created_at: '2026-08-17T19:06:20.812Z'
- updated_at: '2026-08-17T19:06:20.812Z'
+ created_at: '2026-08-18T15:02:50.440Z'
+ updated_at: '2026-08-18T15:02:50.440Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: placeat
+ name: possimus
key_type: secret
- token_prefix: sk_gqU6AqY3G
+ token_prefix: sk_W8P5RNb8z
scopes:
- write_all
- created_at: '2026-08-17T19:06:20.813Z'
- updated_at: '2026-08-17T19:06:20.813Z'
+ created_at: '2026-08-18T15:02:50.442Z'
+ updated_at: '2026-08-18T15:02:50.442Z'
revoked_at:
last_used_at:
channel_id:
@@ -2652,16 +2652,16 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_Jys9T5zkr
+ token_prefix: sk_tjAJzUU1d
scopes:
- read_orders
- created_at: '2026-08-17T19:06:20.849Z'
- updated_at: '2026-08-17T19:06:20.849Z'
+ created_at: '2026-08-18T15:02:50.520Z'
+ updated_at: '2026-08-18T15:02:50.520Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: sk_Jys9T5zkrBXMkucSTfpfPE5e
- created_by_email: [email protected]
+ plaintext_token: sk_tjAJzUU1dSExATocDWSe1b23
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -2750,12 +2750,12 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-17T19:06:20.877Z'
- updated_at: '2026-08-17T19:06:20.877Z'
+ created_at: '2026-08-18T15:02:50.587Z'
+ updated_at: '2026-08-18T15:02:50.587Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_JGeMHhkFu9wHxCdaJmQwsqmp
+ plaintext_token: pk_oTYANgSdqXsF9qkqK87E9jsc
created_by_email:
patch:
summary: Update an API key
@@ -2809,11 +2809,11 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration (renamed)
key_type: secret
- token_prefix: sk_kmY9G4gxo
+ token_prefix: sk_grevBAH5p
scopes:
- write_all
- created_at: '2026-08-17T19:06:20.902Z'
- updated_at: '2026-08-17T19:06:20.917Z'
+ created_at: '2026-08-18T15:02:50.632Z'
+ updated_at: '2026-08-18T15:02:50.665Z'
revoked_at:
last_used_at:
channel_id:
@@ -2910,13 +2910,13 @@ paths:
application/json:
example:
id: key_EfhxLZ9ck8
- name: fugiat
+ name: debitis
key_type: secret
- token_prefix: sk_rMfpDBhMb
+ token_prefix: sk_97BW9YerZ
scopes:
- write_all
- created_at: '2026-08-17T19:06:20.948Z'
- updated_at: '2026-08-17T19:06:20.948Z'
+ created_at: '2026-08-18T15:02:50.722Z'
+ updated_at: '2026-08-18T15:02:50.722Z'
revoked_at:
last_used_at:
channel_id:
@@ -2974,12 +2974,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_jZ7qYn4fH
+ token_prefix: sk_LADTqti1G
scopes:
- write_all
- created_at: '2026-08-17T19:06:20.957Z'
- updated_at: '2026-08-17T19:06:20.970Z'
- revoked_at: '2026-08-17T19:06:20.970Z'
+ created_at: '2026-08-18T15:02:50.733Z'
+ updated_at: '2026-08-18T15:02:50.749Z'
+ revoked_at: '2026-08-18T15:02:50.749Z'
last_used_at:
channel_id:
plaintext_token:
@@ -3056,8 +3056,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-17T19:06:21.133Z'
- updated_at: '2026-08-17T19:06:21.133Z'
+ created_at: '2026-08-18T15:02:51.004Z'
+ updated_at: '2026-08-18T15:02:51.004Z'
meta:
page: 1
limit: 25
@@ -3131,8 +3131,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-17T19:06:21.195Z'
- updated_at: '2026-08-17T19:06:21.203Z'
+ created_at: '2026-08-18T15:02:51.145Z'
+ updated_at: '2026-08-18T15:02:51.172Z'
schema:
"$ref": "#/components/schemas/Category"
'422':
@@ -3238,8 +3238,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-17T19:06:21.246Z'
- updated_at: '2026-08-17T19:06:21.246Z'
+ created_at: '2026-08-18T15:02:51.258Z'
+ updated_at: '2026-08-18T15:02:51.258Z'
schema:
"$ref": "#/components/schemas/Category"
'404':
@@ -3309,8 +3309,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-17T19:06:21.321Z'
- updated_at: '2026-08-17T19:06:21.345Z'
+ created_at: '2026-08-18T15:02:51.373Z'
+ updated_at: '2026-08-18T15:02:51.431Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -3425,8 +3425,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-17T19:06:21.394Z'
- updated_at: '2026-08-17T19:06:21.419Z'
+ created_at: '2026-08-18T15:02:51.531Z'
+ updated_at: '2026-08-18T15:02:51.561Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -3538,8 +3538,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 11934
- slug: product-11934
+ name: Product 17996
+ slug: product-17996
meta_title:
meta_description:
meta_keywords:
@@ -3551,15 +3551,17 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Ratione excepturi temporibus rem officiis. Occaecati
- qui aut mollitia impedit tempora excepturi quia eos. Sapiente vero
- enim asperiores ex harum recusandae dolores quaerat. Corrupti in
- eum quaerat recusandae sequi beatae eos occaecati.
- description_html: Ratione excepturi temporibus rem officiis. Occaecati
- qui aut mollitia impedit tempora excepturi quia eos. Sapiente vero
- enim asperiores ex harum recusandae dolores quaerat. Corrupti in
- eum quaerat recusandae sequi beatae eos occaecati.
+ description: Dignissimos delectus maiores itaque tenetur nesciunt.
+ Vel repellat adipisci veniam reprehenderit nemo dolorem. Pariatur
+ repellendus qui totam libero. A fugiat natus omnis repudiandae repellendus.
+ Voluptas aut magnam ipsam facere veniam quibusdam. Rerum ipsam veritatis
+ quisquam officiis eveniet. Esse rem amet sit nisi iusto velit. Natus
+ excepturi nobis tenetur consequatur tempore.
+ description_html: |-
+ Dignissimos delectus maiores itaque tenetur nesciunt. Vel repellat adipisci veniam reprehenderit nemo dolorem. Pariatur repellendus qui totam libero. A fugiat natus omnis repudiandae repellendus. Voluptas aut magnam ipsam facere veniam quibusdam.
+ Rerum ipsam veritatis quisquam officiis eveniet. Esse rem amet sit nisi iusto velit. Natus excepturi nobis tenetur consequatur tempore.
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -3573,15 +3575,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:21.559Z'
- updated_at: '2026-08-17T19:06:21.559Z'
+ created_at: '2026-08-18T15:02:51.831Z'
+ updated_at: '2026-08-18T15:02:51.831Z'
original_price:
seller_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:21.534Z'
- updated_at: '2026-08-17T19:06:21.574Z'
+ created_at: '2026-08-18T15:02:51.798Z'
+ updated_at: '2026-08-18T15:02:51.876Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
@@ -3753,8 +3755,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-17T19:06:20.147Z'
- updated_at: '2026-08-17T19:06:20.147Z'
+ created_at: '2026-08-18T15:02:49.305Z'
+ updated_at: '2026-08-18T15:02:49.305Z'
stock_location_ids: []
- id: ch_gbHJdmfrXB
name: Wholesale
@@ -3766,8 +3768,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-17T19:06:21.778Z'
- updated_at: '2026-08-17T19:06:21.778Z'
+ created_at: '2026-08-18T15:02:52.253Z'
+ updated_at: '2026-08-18T15:02:52.253Z'
stock_location_ids: []
meta:
page: 1
@@ -3853,8 +3855,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-17T19:06:21.837Z'
- updated_at: '2026-08-17T19:06:21.837Z'
+ created_at: '2026-08-18T15:02:52.360Z'
+ updated_at: '2026-08-18T15:02:52.360Z'
stock_location_ids: []
requestBody:
content:
@@ -3953,8 +3955,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-17T19:06:21.850Z'
- updated_at: '2026-08-17T19:06:21.850Z'
+ created_at: '2026-08-18T15:02:52.401Z'
+ updated_at: '2026-08-18T15:02:52.401Z'
stock_location_ids: []
patch:
summary: Update a channel
@@ -4009,8 +4011,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access: login_required
preferred_guest_checkout: false
- created_at: '2026-08-17T19:06:21.894Z'
- updated_at: '2026-08-17T19:06:21.924Z'
+ created_at: '2026-08-18T15:02:52.476Z'
+ updated_at: '2026-08-18T15:02:52.524Z'
stock_location_ids: []
requestBody:
content:
@@ -4293,8 +4295,8 @@ paths:
- id: orule_UkLWZg9DAJ
position: 1
active: true
- created_at: '2026-08-17T19:06:20.152Z'
- updated_at: '2026-08-17T19:06:20.152Z'
+ created_at: '2026-08-18T15:02:49.311Z'
+ updated_at: '2026-08-18T15:02:49.311Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4305,8 +4307,8 @@ paths:
- id: orule_gbHJdmfrXB
position: 2
active: true
- created_at: '2026-08-17T19:06:20.156Z'
- updated_at: '2026-08-17T19:06:20.156Z'
+ created_at: '2026-08-18T15:02:49.345Z'
+ updated_at: '2026-08-18T15:02:49.345Z'
type: minimize_splits
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4317,8 +4319,8 @@ paths:
- id: orule_EfhxLZ9ck8
position: 3
active: true
- created_at: '2026-08-17T19:06:20.160Z'
- updated_at: '2026-08-17T19:06:20.160Z'
+ created_at: '2026-08-18T15:02:49.349Z'
+ updated_at: '2026-08-18T15:02:49.349Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4383,8 +4385,8 @@ paths:
id: orule_VqXmZF31wY
position: 3
active: true
- created_at: '2026-08-17T19:06:29.381Z'
- updated_at: '2026-08-17T19:06:29.381Z'
+ created_at: '2026-08-18T15:03:05.187Z'
+ updated_at: '2026-08-18T15:03:05.187Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4479,8 +4481,8 @@ paths:
id: orule_UkLWZg9DAJ
position: 2
active: false
- created_at: '2026-08-17T19:06:20.152Z'
- updated_at: '2026-08-17T19:06:29.442Z'
+ created_at: '2026-08-18T15:02:49.311Z'
+ updated_at: '2026-08-18T15:03:05.300Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4668,8 +4670,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-17T19:06:24.379Z'
- updated_at: '2026-08-17T19:06:24.379Z'
+ created_at: '2026-08-18T15:02:57.136Z'
+ updated_at: '2026-08-18T15:02:57.136Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -4680,8 +4682,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_custom_order_notes
- created_at: '2026-08-17T19:06:24.380Z'
- updated_at: '2026-08-17T19:06:24.380Z'
+ created_at: '2026-08-18T15:02:57.138Z'
+ updated_at: '2026-08-18T15:02:57.138Z'
meta:
page: 1
limit: 25
@@ -4750,8 +4752,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_origin
- created_at: '2026-08-17T19:06:24.418Z'
- updated_at: '2026-08-17T19:06:24.418Z'
+ created_at: '2026-08-18T15:02:57.231Z'
+ updated_at: '2026-08-18T15:02:57.231Z'
requestBody:
content:
application/json:
@@ -4859,8 +4861,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-17T19:06:24.424Z'
- updated_at: '2026-08-17T19:06:24.424Z'
+ created_at: '2026-08-18T15:02:57.240Z'
+ updated_at: '2026-08-18T15:02:57.240Z'
patch:
summary: Update a custom field definition
tags:
@@ -4920,8 +4922,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-17T19:06:24.448Z'
- updated_at: '2026-08-17T19:06:24.469Z'
+ created_at: '2026-08-18T15:02:57.297Z'
+ updated_at: '2026-08-18T15:02:57.327Z'
requestBody:
content:
application/json:
@@ -5067,14 +5069,14 @@ paths:
name: VIPs
description: Top spenders
customers_count: 0
- created_at: '2026-08-17T19:06:24.507Z'
- updated_at: '2026-08-17T19:06:24.507Z'
+ created_at: '2026-08-18T15:02:57.390Z'
+ updated_at: '2026-08-18T15:02:57.390Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
- created_at: '2026-08-17T19:06:24.507Z'
- updated_at: '2026-08-17T19:06:24.507Z'
+ created_at: '2026-08-18T15:02:57.391Z'
+ updated_at: '2026-08-18T15:02:57.391Z'
meta:
page: 1
limit: 25
@@ -5163,8 +5165,8 @@ paths:
name: Wholesale 2
description: B2B accounts
customers_count: 1
- created_at: '2026-08-17T19:06:24.576Z'
- updated_at: '2026-08-17T19:06:24.576Z'
+ created_at: '2026-08-18T15:02:57.517Z'
+ updated_at: '2026-08-18T15:02:57.517Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -5273,22 +5275,22 @@ paths:
name: VIPs
description: Top spenders
customers_count: 1
- created_at: '2026-08-17T19:06:24.649Z'
- updated_at: '2026-08-17T19:06:24.649Z'
+ created_at: '2026-08-18T15:02:57.632Z'
+ updated_at: '2026-08-18T15:02:57.632Z'
customers:
- id: cust_UkLWZg9DAJ
- first_name: Trudy
- last_name: Yost
+ first_name: Crystal
+ last_name: Mueller
phone:
accepts_email_marketing: false
- full_name: Trudy Yost
+ full_name: Crystal Mueller
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-17T19:06:24.652Z'
- updated_at: '2026-08-17T19:06:24.652Z'
+ created_at: '2026-08-18T15:02:57.638Z'
+ updated_at: '2026-08-18T15:02:57.638Z'
tags: []
internal_note:
internal_note_html:
@@ -5368,8 +5370,8 @@ paths:
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
- created_at: '2026-08-17T19:06:24.719Z'
- updated_at: '2026-08-17T19:06:24.738Z'
+ created_at: '2026-08-18T15:02:57.815Z'
+ updated_at: '2026-08-18T15:02:57.845Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -5530,8 +5532,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-08-17T19:06:24.804Z'
- updated_at: '2026-08-17T19:06:24.804Z'
+ created_at: '2026-08-18T15:02:57.929Z'
+ updated_at: '2026-08-18T15:02:57.929Z'
customer_id: cust_UkLWZg9DAJ
meta:
page: 1
@@ -5626,8 +5628,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-08-17T19:06:24.862Z'
- updated_at: '2026-08-17T19:06:24.862Z'
+ created_at: '2026-08-18T15:02:58.092Z'
+ updated_at: '2026-08-18T15:02:58.092Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -5743,8 +5745,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-08-17T19:06:24.878Z'
- updated_at: '2026-08-17T19:06:24.898Z'
+ created_at: '2026-08-18T15:02:58.112Z'
+ updated_at: '2026-08-18T15:02:58.134Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -5883,8 +5885,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-17T19:06:24.981Z'
- updated_at: '2026-08-17T19:06:24.981Z'
+ created_at: '2026-08-18T15:02:58.255Z'
+ updated_at: '2026-08-18T15:02:58.255Z'
meta:
page: 1
limit: 25
@@ -5974,8 +5976,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-17T19:06:25.020Z'
- updated_at: '2026-08-17T19:06:25.020Z'
+ created_at: '2026-08-18T15:02:58.310Z'
+ updated_at: '2026-08-18T15:02:58.310Z'
delete:
summary: Delete a customer credit card
tags:
@@ -6100,8 +6102,8 @@ paths:
currency: USD
memo:
metadata: {}
- created_at: '2026-08-17T19:06:25.095Z'
- updated_at: '2026-08-17T19:06:25.095Z'
+ created_at: '2026-08-18T15:02:58.494Z'
+ updated_at: '2026-08-18T15:02:58.494Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -6180,8 +6182,8 @@ paths:
currency: USD
memo: Goodwill
metadata: {}
- created_at: '2026-08-17T19:06:25.156Z'
- updated_at: '2026-08-17T19:06:25.156Z'
+ created_at: '2026-08-18T15:02:58.628Z'
+ updated_at: '2026-08-18T15:02:58.628Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_gbHJdmfrXB
category_id: sccat_UkLWZg9DAJ
@@ -6276,8 +6278,8 @@ paths:
currency: USD
memo: Updated
metadata: {}
- created_at: '2026-08-17T19:06:25.183Z'
- updated_at: '2026-08-17T19:06:25.202Z'
+ created_at: '2026-08-18T15:02:58.667Z'
+ updated_at: '2026-08-18T15:02:58.701Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -6436,8 +6438,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-17T19:06:25.246Z'
- updated_at: '2026-08-17T19:06:25.246Z'
+ created_at: '2026-08-18T15:02:58.834Z'
+ updated_at: '2026-08-18T15:02:58.834Z'
tags: []
internal_note:
internal_note_html:
@@ -6520,8 +6522,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-17T19:06:25.297Z'
- updated_at: '2026-08-17T19:06:25.297Z'
+ created_at: '2026-08-18T15:02:58.901Z'
+ updated_at: '2026-08-18T15:02:58.901Z'
tags: []
internal_note:
internal_note_html:
@@ -6636,8 +6638,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-17T19:06:25.310Z'
- updated_at: '2026-08-17T19:06:25.310Z'
+ created_at: '2026-08-18T15:02:58.917Z'
+ updated_at: '2026-08-18T15:02:58.917Z'
tags: []
internal_note:
internal_note_html:
@@ -6710,8 +6712,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-17T19:06:25.339Z'
- updated_at: '2026-08-17T19:06:25.359Z'
+ created_at: '2026-08-18T15:02:58.992Z'
+ updated_at: '2026-08-18T15:02:59.024Z'
tags: []
internal_note:
internal_note_html:
@@ -7159,8 +7161,8 @@ paths:
- id: exp_UkLWZg9DAJ
number: EF1001
format: csv
- created_at: '2026-08-17T19:06:26.001Z'
- updated_at: '2026-08-17T19:06:26.001Z'
+ created_at: '2026-08-18T15:03:00.059Z'
+ updated_at: '2026-08-18T15:03:00.059Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -7233,8 +7235,8 @@ paths:
id: exp_gbHJdmfrXB
number: EF1002
format: csv
- created_at: '2026-08-17T19:06:26.038Z'
- updated_at: '2026-08-17T19:06:26.038Z'
+ created_at: '2026-08-18T15:03:00.136Z'
+ updated_at: '2026-08-18T15:03:00.136Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -7333,8 +7335,8 @@ paths:
id: exp_UkLWZg9DAJ
number: EF1001
format: csv
- created_at: '2026-08-17T19:06:26.058Z'
- updated_at: '2026-08-17T19:06:26.058Z'
+ created_at: '2026-08-18T15:03:00.154Z'
+ updated_at: '2026-08-18T15:03:00.154Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -7550,8 +7552,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:29.567Z'
- updated_at: '2026-08-17T19:06:29.577Z'
+ created_at: '2026-08-18T15:03:05.618Z'
+ updated_at: '2026-08-18T15:03:05.651Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7644,7 +7646,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-17T19:06:29.823Z'
+ fulfilled_at: '2026-08-18T15:03:06.050Z'
tracking_status:
estimated_delivery_at:
delivered_at:
@@ -7656,8 +7658,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-17T19:06:29.793Z'
- updated_at: '2026-08-17T19:06:29.823Z'
+ created_at: '2026-08-18T15:03:06.009Z'
+ updated_at: '2026-08-18T15:03:06.051Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7832,8 +7834,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:30.119Z'
- updated_at: '2026-08-17T19:06:30.129Z'
+ created_at: '2026-08-18T15:03:06.588Z'
+ updated_at: '2026-08-18T15:03:06.602Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7930,8 +7932,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:30.290Z'
- updated_at: '2026-08-17T19:06:30.355Z'
+ created_at: '2026-08-18T15:03:06.832Z'
+ updated_at: '2026-08-18T15:03:06.919Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8030,7 +8032,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-17T19:06:30.516Z'
+ fulfilled_at: '2026-08-18T15:03:07.140Z'
tracking_status:
estimated_delivery_at:
delivered_at:
@@ -8042,8 +8044,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:30.435Z'
- updated_at: '2026-08-17T19:06:30.516Z'
+ created_at: '2026-08-18T15:03:07.046Z'
+ updated_at: '2026-08-18T15:03:07.141Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8146,8 +8148,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:30.596Z'
- updated_at: '2026-08-17T19:06:30.669Z'
+ created_at: '2026-08-18T15:03:07.253Z'
+ updated_at: '2026-08-18T15:03:07.350Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents:
@@ -8246,10 +8248,10 @@ paths:
display_tax_total: "$0.00"
status: delivered
fulfillment_type: shipping
- fulfilled_at: '2026-08-17T19:06:30.961Z'
+ fulfilled_at: '2026-08-18T15:03:07.703Z'
tracking_status:
estimated_delivery_at:
- delivered_at: '2026-08-17T19:06:30.986Z'
+ delivered_at: '2026-08-18T15:03:07.726Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -8258,8 +8260,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:30.906Z'
- updated_at: '2026-08-17T19:06:30.986Z'
+ created_at: '2026-08-18T15:03:07.623Z'
+ updated_at: '2026-08-18T15:03:07.727Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8378,8 +8380,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:31.333Z'
- updated_at: '2026-08-17T19:06:31.405Z'
+ created_at: '2026-08-18T15:03:08.036Z'
+ updated_at: '2026-08-18T15:03:08.131Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8476,8 +8478,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-17T19:06:31.481Z'
- updated_at: '2026-08-17T19:06:31.552Z'
+ created_at: '2026-08-18T15:03:08.220Z'
+ updated_at: '2026-08-18T15:03:08.307Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8585,8 +8587,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-17T19:06:31.719Z'
- updated_at: '2026-08-17T19:06:31.764Z'
+ created_at: '2026-08-18T15:03:08.631Z'
+ updated_at: '2026-08-18T15:03:08.718Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
documents: []
@@ -8687,8 +8689,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-17T19:06:26.151Z'
- updated_at: '2026-08-17T19:06:26.151Z'
+ created_at: '2026-08-18T15:03:00.283Z'
+ updated_at: '2026-08-18T15:03:00.283Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -8772,8 +8774,8 @@ paths:
codes_count: 5
currency: USD
prefix: NEWCAMP
- created_at: '2026-08-17T19:06:26.205Z'
- updated_at: '2026-08-17T19:06:26.205Z'
+ created_at: '2026-08-18T15:03:00.383Z'
+ updated_at: '2026-08-18T15:03:00.383Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: adm_UkLWZg9DAJ
@@ -8877,8 +8879,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-17T19:06:26.246Z'
- updated_at: '2026-08-17T19:06:26.246Z'
+ created_at: '2026-08-18T15:03:00.464Z'
+ updated_at: '2026-08-18T15:03:00.464Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -8984,7 +8986,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: D13B3427A450DFDA
+ code: 3C84022E70135ABE
status: active
currency: USD
amount: '50.0'
@@ -8998,12 +9000,12 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-17T19:06:26.301Z'
- updated_at: '2026-08-17T19:06:26.301Z'
+ created_at: '2026-08-18T15:03:00.644Z'
+ updated_at: '2026-08-18T15:03:00.644Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
- code: D86FD37D187784FE
+ code: 2725F36E96D85832
status: active
currency: USD
amount: '25.0'
@@ -9017,8 +9019,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-17T19:06:26.302Z'
- updated_at: '2026-08-17T19:06:26.302Z'
+ created_at: '2026-08-18T15:03:00.645Z'
+ updated_at: '2026-08-18T15:03:00.645Z'
customer_id:
created_by_id:
meta:
@@ -9106,7 +9108,7 @@ paths:
application/json:
example:
id: gc_EfhxLZ9ck8
- code: 3A820DE789193B45
+ code: 00F772A62CFD6315
status: active
currency: USD
amount: '25.0'
@@ -9120,8 +9122,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-17T19:06:26.377Z'
- updated_at: '2026-08-17T19:06:26.377Z'
+ created_at: '2026-08-18T15:03:00.739Z'
+ updated_at: '2026-08-18T15:03:00.739Z'
customer_id:
created_by_id: adm_UkLWZg9DAJ
schema:
@@ -9230,7 +9232,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 8909E4469F381290
+ code: D45B0C7358753E54
status: active
currency: USD
amount: '50.0'
@@ -9244,8 +9246,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-17T19:06:26.424Z'
- updated_at: '2026-08-17T19:06:26.424Z'
+ created_at: '2026-08-18T15:03:00.811Z'
+ updated_at: '2026-08-18T15:03:00.811Z'
customer_id:
created_by_id:
schema:
@@ -9308,7 +9310,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 537D6F19560BDFAA
+ code: 5FE0FCB2CFD9C3AF
status: active
currency: USD
amount: '75.0'
@@ -9322,8 +9324,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-17T19:06:26.481Z'
- updated_at: '2026-08-17T19:06:26.500Z'
+ created_at: '2026-08-18T15:03:00.976Z'
+ updated_at: '2026-08-18T15:03:01.011Z'
customer_id:
created_by_id:
schema:
@@ -9428,8 +9430,8 @@ paths:
- id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
- created_at: '2026-08-17T19:06:26.573Z'
- updated_at: '2026-08-17T19:06:26.580Z'
+ created_at: '2026-08-18T15:03:01.136Z'
+ updated_at: '2026-08-18T15:03:01.153Z'
type: products
status: pending
owner_type: store
@@ -9616,8 +9618,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
- created_at: '2026-08-17T19:06:26.630Z'
- updated_at: '2026-08-17T19:06:26.676Z'
+ created_at: '2026-08-18T15:03:01.247Z'
+ updated_at: '2026-08-18T15:03:01.334Z'
type: products
status: mapping
owner_type: store
@@ -10075,8 +10077,8 @@ paths:
id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
- created_at: '2026-08-17T19:06:26.860Z'
- updated_at: '2026-08-17T19:06:26.868Z'
+ created_at: '2026-08-18T15:03:01.557Z'
+ updated_at: '2026-08-18T15:03:01.566Z'
type: products
status: pending
owner_type: store
@@ -10321,8 +10323,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
- created_at: '2026-08-17T19:06:27.043Z'
- updated_at: '2026-08-17T19:06:27.118Z'
+ created_at: '2026-08-18T15:03:01.788Z'
+ updated_at: '2026-08-18T15:03:01.920Z'
type: products
status: completed_mapping
owner_type: store
@@ -10678,8 +10680,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 1
- created_at: '2026-08-17T19:06:27.162Z'
- updated_at: '2026-08-17T19:06:27.190Z'
+ created_at: '2026-08-18T15:03:01.971Z'
+ updated_at: '2026-08-18T15:03:01.994Z'
type: products
status: processing
owner_type: store
@@ -10861,8 +10863,8 @@ paths:
row_number: 2
status: failed
validation_errors: boom
- created_at: '2026-08-17T19:06:27.226Z'
- updated_at: '2026-08-17T19:06:27.226Z'
+ created_at: '2026-08-18T15:03:02.026Z'
+ updated_at: '2026-08-18T15:03:02.026Z'
import_id: imp_UkLWZg9DAJ
item_type:
item_id:
@@ -10965,8 +10967,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
- id: mkt_gbHJdmfrXB
name: EU
currency: USD
@@ -10978,8 +10980,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:27.645Z'
- updated_at: '2026-08-17T19:06:27.645Z'
+ created_at: '2026-08-18T15:03:02.545Z'
+ updated_at: '2026-08-18T15:03:02.545Z'
meta:
page: 1
limit: 25
@@ -11073,8 +11075,8 @@ paths:
- en
- fr
tax_provider:
- created_at: '2026-08-17T19:06:27.715Z'
- updated_at: '2026-08-17T19:06:27.715Z'
+ created_at: '2026-08-18T15:03:02.697Z'
+ updated_at: '2026-08-18T15:03:02.697Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -11211,8 +11213,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:27.783Z'
- updated_at: '2026-08-17T19:06:27.783Z'
+ created_at: '2026-08-18T15:03:02.800Z'
+ updated_at: '2026-08-18T15:03:02.800Z'
schema:
"$ref": "#/components/schemas/Market"
'404':
@@ -11292,8 +11294,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:27.855Z'
- updated_at: '2026-08-17T19:06:27.873Z'
+ created_at: '2026-08-18T15:03:02.892Z'
+ updated_at: '2026-08-18T15:03:02.912Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -11473,8 +11475,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-17T19:06:28.105Z'
- updated_at: '2026-08-17T19:06:28.105Z'
+ created_at: '2026-08-18T15:03:03.313Z'
+ updated_at: '2026-08-18T15:03:03.313Z'
meta:
page: 1
limit: 25
@@ -11568,8 +11570,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-17T19:06:28.166Z'
- updated_at: '2026-08-17T19:06:28.166Z'
+ created_at: '2026-08-18T15:03:03.423Z'
+ updated_at: '2026-08-18T15:03:03.423Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -11693,8 +11695,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-17T19:06:28.210Z'
- updated_at: '2026-08-17T19:06:28.210Z'
+ created_at: '2026-08-18T15:03:03.464Z'
+ updated_at: '2026-08-18T15:03:03.464Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
@@ -11767,8 +11769,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-17T19:06:28.267Z'
- updated_at: '2026-08-17T19:06:28.284Z'
+ created_at: '2026-08-18T15:03:03.547Z'
+ updated_at: '2026-08-18T15:03:03.565Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -11932,8 +11934,8 @@ paths:
country_code:
state_code:
data: {}
- created_at: '2026-08-17T19:06:28.491Z'
- updated_at: '2026-08-17T19:06:28.491Z'
+ created_at: '2026-08-18T15:03:03.927Z'
+ updated_at: '2026-08-18T15:03:03.927Z'
meta:
page: 1
limit: 25
@@ -12007,8 +12009,8 @@ paths:
amount: "-2.0"
display_amount: "-$2.00"
metadata: {}
- created_at: '2026-08-17T19:06:28.629Z'
- updated_at: '2026-08-17T19:06:28.629Z'
+ created_at: '2026-08-18T15:03:04.161Z'
+ updated_at: '2026-08-18T15:03:04.161Z'
meta:
page: 1
limit: 25
@@ -12088,8 +12090,8 @@ paths:
amount: "-3.0"
display_amount: "-$3.00"
metadata: {}
- created_at: '2026-08-17T19:06:28.790Z'
- updated_at: '2026-08-17T19:06:28.790Z'
+ created_at: '2026-08-18T15:03:04.432Z'
+ updated_at: '2026-08-18T15:03:04.432Z'
'422':
description: invalid discount
content:
@@ -12186,8 +12188,8 @@ paths:
amount: '4.0'
display_amount: "$4.00"
metadata: {}
- created_at: '2026-08-17T19:06:29.079Z'
- updated_at: '2026-08-17T19:06:29.079Z'
+ created_at: '2026-08-18T15:03:04.945Z'
+ updated_at: '2026-08-18T15:03:04.945Z'
'422':
description: invalid fee
content:
@@ -12285,7 +12287,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 3275F9D856E952AC
+ code: 53FCA981BB04B727
status: active
currency: USD
amount: '10.0'
@@ -12299,8 +12301,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-17T19:06:31.871Z'
- updated_at: '2026-08-17T19:06:31.905Z'
+ created_at: '2026-08-18T15:03:08.870Z'
+ updated_at: '2026-08-18T15:03:08.908Z'
customer_id:
created_by_id:
requestBody:
@@ -12442,8 +12444,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 357810
- slug: product-357810
+ name: Product 353827
+ slug: product-353827
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -12475,12 +12477,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:32.105Z'
- updated_at: '2026-08-17T19:06:32.105Z'
+ created_at: '2026-08-18T15:03:09.138Z'
+ updated_at: '2026-08-18T15:03:09.138Z'
digital_links: []
metadata: {}
- created_at: '2026-08-17T19:06:32.137Z'
- updated_at: '2026-08-17T19:06:32.137Z'
+ created_at: '2026-08-18T15:03:09.170Z'
+ updated_at: '2026-08-18T15:03:09.170Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -12553,8 +12555,8 @@ paths:
preorder_ships_at:
quantity: 3
currency: USD
- name: Product 377135
- slug: product-377135
+ name: Product 379737
+ slug: product-379737
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -12586,12 +12588,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:32.306Z'
- updated_at: '2026-08-17T19:06:32.306Z'
+ created_at: '2026-08-18T15:03:09.367Z'
+ updated_at: '2026-08-18T15:03:09.367Z'
digital_links: []
metadata: {}
- created_at: '2026-08-17T19:06:32.329Z'
- updated_at: '2026-08-17T19:06:32.329Z'
+ created_at: '2026-08-18T15:03:09.397Z'
+ updated_at: '2026-08-18T15:03:09.397Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -12686,8 +12688,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 387053
- slug: product-387053
+ name: Product 387755
+ slug: product-387755
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -12719,12 +12721,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:32.414Z'
- updated_at: '2026-08-17T19:06:32.414Z'
+ created_at: '2026-08-18T15:03:09.514Z'
+ updated_at: '2026-08-18T15:03:09.514Z'
digital_links: []
metadata: {}
- created_at: '2026-08-17T19:06:32.444Z'
- updated_at: '2026-08-17T19:06:32.444Z'
+ created_at: '2026-08-18T15:03:09.552Z'
+ updated_at: '2026-08-18T15:03:09.552Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -12792,8 +12794,8 @@ paths:
preorder_ships_at:
quantity: 5
currency: USD
- name: Product 398817
- slug: product-398817
+ name: Product 392820
+ slug: product-392820
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -12825,12 +12827,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:32.524Z'
- updated_at: '2026-08-17T19:06:32.524Z'
+ created_at: '2026-08-18T15:03:09.634Z'
+ updated_at: '2026-08-18T15:03:09.634Z'
digital_links: []
metadata: {}
- created_at: '2026-08-17T19:06:32.550Z'
- updated_at: '2026-08-17T19:06:32.577Z'
+ created_at: '2026-08-18T15:03:09.664Z'
+ updated_at: '2026-08-18T15:03:09.699Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -12952,7 +12954,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -12999,8 +13001,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13011,8 +13013,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-17T19:06:34.178Z'
- updated_at: '2026-08-17T19:06:34.241Z'
+ created_at: '2026-08-18T15:03:11.478Z'
+ updated_at: '2026-08-18T15:03:11.554Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -13194,7 +13196,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -13241,8 +13243,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13253,8 +13255,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-17T19:06:34.450Z'
- updated_at: '2026-08-17T19:06:34.450Z'
+ created_at: '2026-08-18T15:03:11.776Z'
+ updated_at: '2026-08-18T15:03:11.776Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -13460,8 +13462,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13472,8 +13474,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-17T19:06:34.606Z'
- updated_at: '2026-08-17T19:06:34.612Z'
+ created_at: '2026-08-18T15:03:11.938Z'
+ updated_at: '2026-08-18T15:03:11.944Z'
preferred_stock_location_id: sloc_UkLWZg9DAJ
company_location_id:
company_id:
@@ -13665,7 +13667,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -13712,8 +13714,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13724,8 +13726,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-17T19:06:34.644Z'
- updated_at: '2026-08-17T19:06:34.644Z'
+ created_at: '2026-08-18T15:03:11.974Z'
+ updated_at: '2026-08-18T15:03:11.974Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -13852,8 +13854,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13864,8 +13866,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-17T19:06:34.740Z'
- updated_at: '2026-08-17T19:06:34.776Z'
+ created_at: '2026-08-18T15:03:12.061Z'
+ updated_at: '2026-08-18T15:03:12.090Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14057,7 +14059,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14065,7 +14067,7 @@ paths:
coupon_code:
fulfillment_status: unfulfilled
payment_status: paid
- completed_at: '2026-08-17T19:06:34.926Z'
+ completed_at: '2026-08-18T15:03:12.245Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14104,8 +14106,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14116,8 +14118,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-17T19:06:34.870Z'
- updated_at: '2026-08-17T19:06:34.966Z'
+ created_at: '2026-08-18T15:03:12.181Z'
+ updated_at: '2026-08-18T15:03:12.268Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14209,7 +14211,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14217,7 +14219,7 @@ paths:
coupon_code:
fulfillment_status: canceled
payment_status: none
- completed_at: '2026-08-17T19:06:35.322Z'
+ completed_at: '2026-08-18T15:03:12.517Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14256,8 +14258,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: canceled
last_ip_address:
considered_risky: false
@@ -14266,10 +14268,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-17T19:06:35.353Z'
+ canceled_at: '2026-08-18T15:03:12.554Z'
approved_at:
- created_at: '2026-08-17T19:06:35.259Z'
- updated_at: '2026-08-17T19:06:35.375Z'
+ created_at: '2026-08-18T15:03:12.448Z'
+ updated_at: '2026-08-18T15:03:12.595Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14345,7 +14347,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14353,7 +14355,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-17T19:06:35.491Z'
+ completed_at: '2026-08-18T15:03:12.721Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14392,8 +14394,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14403,9 +14405,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-08-17T19:06:35.522Z'
- created_at: '2026-08-17T19:06:35.428Z'
- updated_at: '2026-08-17T19:06:35.491Z'
+ approved_at: '2026-08-18T15:03:12.756Z'
+ created_at: '2026-08-18T15:03:12.653Z'
+ updated_at: '2026-08-18T15:03:12.720Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14472,7 +14474,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14480,7 +14482,7 @@ paths:
coupon_code:
fulfillment_status: unfulfilled
payment_status: none
- completed_at: '2026-08-17T19:06:35.612Z'
+ completed_at: '2026-08-18T15:03:12.858Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14519,8 +14521,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14529,10 +14531,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-17T19:06:35.655Z'
+ canceled_at: '2026-08-18T15:03:12.885Z'
approved_at:
- created_at: '2026-08-17T19:06:35.556Z'
- updated_at: '2026-08-17T19:06:35.717Z'
+ created_at: '2026-08-18T15:03:12.795Z'
+ updated_at: '2026-08-18T15:03:12.934Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14599,7 +14601,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14607,7 +14609,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-17T19:06:35.817Z'
+ completed_at: '2026-08-18T15:03:13.058Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14646,8 +14648,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-17T19:06:20.138Z'
- updated_at: '2026-08-17T19:06:20.138Z'
+ created_at: '2026-08-18T15:02:49.299Z'
+ updated_at: '2026-08-18T15:02:49.299Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14658,8 +14660,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-17T19:06:35.756Z'
- updated_at: '2026-08-17T19:06:35.817Z'
+ created_at: '2026-08-18T15:03:12.988Z'
+ updated_at: '2026-08-18T15:03:13.058Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14742,8 +14744,8 @@ paths:
resolved_capture_method: checkout
storefront_visible: true
position: 1
- created_at: '2026-08-17T19:06:35.939Z'
- updated_at: '2026-08-17T19:06:35.939Z'
+ created_at: '2026-08-18T15:03:13.225Z'
+ updated_at: '2026-08-18T15:03:13.225Z'
preferences: {}
preference_schema: []
meta:
@@ -14891,8 +14893,8 @@ paths:
resolved_capture_method: checkout
storefront_visible: true
position: 1
- created_at: '2026-08-17T19:06:35.999Z'
- updated_at: '2026-08-17T19:06:35.999Z'
+ created_at: '2026-08-18T15:03:13.326Z'
+ updated_at: '2026-08-18T15:03:13.326Z'
preferences: {}
preference_schema: []
"/api/v3/admin/orders/{order_id}/payments":
@@ -14963,7 +14965,7 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-ed4cc2f223b2
+ response_code: BGS-2577ad42d2a0
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -14982,14 +14984,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-17T19:06:32.838Z'
- updated_at: '2026-08-17T19:06:32.840Z'
+ created_at: '2026-08-18T15:03:09.975Z'
+ updated_at: '2026-08-18T15:03:09.978Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-17T19:06:32.839Z'
- updated_at: '2026-08-17T19:06:32.839Z'
+ created_at: '2026-08-18T15:03:09.976Z'
+ updated_at: '2026-08-18T15:03:09.976Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -15070,8 +15072,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-17T19:06:33.214Z'
- updated_at: '2026-08-17T19:06:33.214Z'
+ created_at: '2026-08-18T15:03:10.300Z'
+ updated_at: '2026-08-18T15:03:10.300Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -15164,7 +15166,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-cf6cc59f7d97
+ response_code: BGS-41033db354a8
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -15183,14 +15185,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-17T19:06:33.348Z'
- updated_at: '2026-08-17T19:06:33.351Z'
+ created_at: '2026-08-18T15:03:10.432Z'
+ updated_at: '2026-08-18T15:03:10.435Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-17T19:06:33.349Z'
- updated_at: '2026-08-17T19:06:33.349Z'
+ created_at: '2026-08-18T15:03:10.433Z'
+ updated_at: '2026-08-18T15:03:10.433Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -15253,7 +15255,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-89f5c32ca6fb
+ response_code: BGS-7b1c64057648
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -15272,14 +15274,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-17T19:06:33.492Z'
- updated_at: '2026-08-17T19:06:33.496Z'
+ created_at: '2026-08-18T15:03:10.605Z'
+ updated_at: '2026-08-18T15:03:10.608Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-17T19:06:33.495Z'
- updated_at: '2026-08-17T19:06:33.527Z'
+ created_at: '2026-08-18T15:03:10.607Z'
+ updated_at: '2026-08-18T15:03:10.653Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -15351,7 +15353,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-2c0f257de1b9
+ response_code: void-BGS-13ff3c59a2c0
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -15370,14 +15372,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-17T19:06:33.819Z'
- updated_at: '2026-08-17T19:06:33.822Z'
+ created_at: '2026-08-18T15:03:10.961Z'
+ updated_at: '2026-08-18T15:03:10.965Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-17T19:06:33.821Z'
- updated_at: '2026-08-17T19:06:33.847Z'
+ created_at: '2026-08-18T15:03:10.963Z'
+ updated_at: '2026-08-18T15:03:10.992Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
@@ -15465,8 +15467,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-17T19:06:36.053Z'
- updated_at: '2026-08-17T19:06:36.053Z'
+ created_at: '2026-08-18T15:03:13.414Z'
+ updated_at: '2026-08-18T15:03:13.414Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -15480,8 +15482,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-17T19:06:36.054Z'
- updated_at: '2026-08-17T19:06:36.054Z'
+ created_at: '2026-08-18T15:03:13.417Z'
+ updated_at: '2026-08-18T15:03:13.417Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -15595,8 +15597,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-17T19:06:36.279Z'
- updated_at: '2026-08-17T19:06:36.281Z'
+ created_at: '2026-08-18T15:03:13.732Z'
+ updated_at: '2026-08-18T15:03:13.734Z'
currently_active: false
products_count: 1
prices_count: 2
@@ -15759,8 +15761,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-17T19:06:36.322Z'
- updated_at: '2026-08-17T19:06:36.322Z'
+ created_at: '2026-08-18T15:03:13.780Z'
+ updated_at: '2026-08-18T15:03:13.780Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -15835,8 +15837,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-17T19:06:36.625Z'
- updated_at: '2026-08-17T19:06:36.645Z'
+ created_at: '2026-08-18T15:03:14.075Z'
+ updated_at: '2026-08-18T15:03:14.091Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -16024,8 +16026,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-17T19:06:36.683Z'
- updated_at: '2026-08-17T19:06:36.702Z'
+ created_at: '2026-08-18T15:03:14.129Z'
+ updated_at: '2026-08-18T15:03:14.145Z'
currently_active: true
products_count: 0
prices_count: 0
@@ -16088,8 +16090,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-17T19:06:36.713Z'
- updated_at: '2026-08-17T19:06:36.731Z'
+ created_at: '2026-08-18T15:03:14.157Z'
+ updated_at: '2026-08-18T15:03:14.174Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -16203,8 +16205,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:36.777Z'
- updated_at: '2026-08-17T19:06:36.777Z'
+ created_at: '2026-08-18T15:03:14.215Z'
+ updated_at: '2026-08-18T15:03:14.215Z'
- id: price_gbHJdmfrXB
amount: '19.99'
amount_in_cents: 1999
@@ -16215,8 +16217,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-17T19:06:36.806Z'
- updated_at: '2026-08-17T19:06:36.806Z'
+ created_at: '2026-08-18T15:03:14.238Z'
+ updated_at: '2026-08-18T15:03:14.238Z'
- id: price_EfhxLZ9ck8
amount: '5.0'
amount_in_cents: 500
@@ -16227,8 +16229,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-17T19:06:36.811Z'
- updated_at: '2026-08-17T19:06:36.811Z'
+ created_at: '2026-08-18T15:03:14.242Z'
+ updated_at: '2026-08-18T15:03:14.242Z'
meta:
page: 1
limit: 25
@@ -16310,8 +16312,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_EfhxLZ9ck8
- created_at: '2026-08-17T19:06:36.941Z'
- updated_at: '2026-08-17T19:06:36.941Z'
+ created_at: '2026-08-18T15:03:14.366Z'
+ updated_at: '2026-08-18T15:03:14.366Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -16398,8 +16400,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-17T19:06:37.021Z'
- updated_at: '2026-08-17T19:06:37.021Z'
+ created_at: '2026-08-18T15:03:14.448Z'
+ updated_at: '2026-08-18T15:03:14.448Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
@@ -16464,8 +16466,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-17T19:06:37.194Z'
- updated_at: '2026-08-17T19:06:37.217Z'
+ created_at: '2026-08-18T15:03:14.621Z'
+ updated_at: '2026-08-18T15:03:14.639Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -16777,8 +16779,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-17T19:06:38.013Z'
- updated_at: '2026-08-17T19:06:38.013Z'
+ created_at: '2026-08-18T15:03:15.396Z'
+ updated_at: '2026-08-18T15:03:15.396Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -16848,8 +16850,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-08-17T19:06:38.098Z'
- updated_at: '2026-08-17T19:06:38.098Z'
+ created_at: '2026-08-18T15:03:15.480Z'
+ updated_at: '2026-08-18T15:03:15.480Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -16948,8 +16950,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-17T19:06:38.202Z'
- updated_at: '2026-08-17T19:06:38.202Z'
+ created_at: '2026-08-18T15:03:15.585Z'
+ updated_at: '2026-08-18T15:03:15.585Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -17013,8 +17015,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-08-17T19:06:38.263Z'
- updated_at: '2026-08-17T19:06:38.280Z'
+ created_at: '2026-08-18T15:03:15.642Z'
+ updated_at: '2026-08-18T15:03:15.659Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -17133,11 +17135,11 @@ paths:
- key: description
type: html
source: |-
- Dolorem debitis similique ipsa quidem iusto. Debitis soluta occaecati eligendi tempore alias ex enim illum. Quibusdam nam quasi quaerat perspiciatis quis. Impedit voluptatem voluptates odio labore suscipit asperiores laudantium.
- Magnam vero ex harum odit nihil enim. Nisi quae reiciendis aut quo perferendis. Corporis vel illo assumenda omnis. Impedit qui recusandae repellendus consequatur optio. Quaerat ea qui dolorum aspernatur animi excepturi.
- Nisi eligendi voluptate natus itaque nemo omnis fuga minima. Odio eaque reprehenderit debitis aliquam est in. Perspiciatis repellendus suscipit dignissimos labore quisquam nisi. Eligendi doloremque consequuntur fugit velit ipsam cupiditate dicta quasi. Deserunt perspiciatis eum ipsum nulla ab incidunt quam.
- Inventore facilis iure itaque hic sequi accusantium placeat. Soluta minus sunt inventore ea expedita quos magnam sapiente. Repellendus natus architecto voluptatum reiciendis.
- Tempora mollitia nemo sit maiores dolore facere libero. Eligendi eos explicabo recusandae non praesentium sint enim. Aspernatur ad corporis nulla voluptas consectetur. Sapiente consequuntur dolorem itaque praesentium.
+ Alias perspiciatis incidunt veniam ex sapiente adipisci perferendis voluptas. Placeat maxime officiis tenetur accusantium. Fugit quo a voluptatibus veniam possimus similique explicabo.
+ Cumque itaque necessitatibus cum placeat neque ipsa suscipit quae. Optio minus vel delectus praesentium placeat. Sequi possimus rerum eligendi quidem labore natus.
+ Repellat sed saepe animi velit. Maiores doloremque excepturi voluptates voluptatibus. Repellat hic eum iste quaerat.
+ Autem est debitis nisi iusto ducimus. At incidunt vero voluptatibus corporis odit. Blanditiis dolorem facilis pariatur corrupti. Nostrum mollitia ad labore enim. Qui accusamus culpa inventore enim unde dignissimos ipsa nobis.
+ Ducimus non reprehenderit sit alias. Cumque laboriosam cum fugiat cupiditate. Molestias occaecati sunt earum aperiam culpa. Veritatis commodi eum vitae molestiae magnam libero culpa architecto.
- key: slug
type: string
source: espresso-machine
@@ -17248,8 +17250,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 803992
- slug: product-803992
+ name: Product 808179
+ slug: product-808179
meta_title:
meta_description:
meta_keywords:
@@ -17261,13 +17263,20 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Quasi perspiciatis accusantium enim amet fugiat alias
- dolore. Tenetur a magnam doloremque quibusdam. Consequatur dignissimos
- ex ad deserunt assumenda laborum nulla cupiditate.
- description_html: Quasi perspiciatis accusantium enim amet fugiat
- alias dolore. Tenetur a magnam doloremque quibusdam. Consequatur
- dignissimos ex ad deserunt assumenda laborum nulla cupiditate.
+ description: Occaecati mollitia fuga repellendus eaque ut. Aperiam
+ dicta explicabo nostrum repudiandae praesentium laboriosam magnam.
+ Eum pariatur sapiente est quis earum. Tempore qui occaecati optio
+ quos doloribus non est provident. Dolores sequi eveniet tempore
+ nesciunt molestias cum nam ipsa. Assumenda eligendi expedita ipsum
+ velit. Officia aut deleniti dolorem ipsum odit rem cum. Maiores
+ itaque facere necessitatibus perspiciatis labore possimus. Magnam
+ dolor dignissimos laboriosam ullam. Ex a minus doloremque dignissimos
+ illo.
+ description_html: |-
+ Occaecati mollitia fuga repellendus eaque ut. Aperiam dicta explicabo nostrum repudiandae praesentium laboriosam magnam. Eum pariatur sapiente est quis earum. Tempore qui occaecati optio quos doloribus non est provident. Dolores sequi eveniet tempore nesciunt molestias cum nam ipsa.
+ Assumenda eligendi expedita ipsum velit. Officia aut deleniti dolorem ipsum odit rem cum. Maiores itaque facere necessitatibus perspiciatis labore possimus. Magnam dolor dignissimos laboriosam ullam. Ex a minus doloremque dignissimos illo.
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -17281,15 +17290,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:38.479Z'
- updated_at: '2026-08-17T19:06:38.479Z'
+ created_at: '2026-08-18T15:03:15.844Z'
+ updated_at: '2026-08-18T15:03:15.844Z'
original_price:
seller_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:38.465Z'
- updated_at: '2026-08-17T19:06:38.488Z'
+ created_at: '2026-08-18T15:03:15.833Z'
+ updated_at: '2026-08-18T15:03:15.851Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
@@ -17421,6 +17430,7 @@ paths:
description:
description_html:
default_variant_id: variant_gbHJdmfrXB
+ buy_box_variant_id: variant_gbHJdmfrXB
thumbnail_url:
tags: []
price:
@@ -17429,8 +17439,8 @@ paths:
status: draft
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:38.639Z'
- updated_at: '2026-08-17T19:06:38.646Z'
+ created_at: '2026-08-18T15:03:15.998Z'
+ updated_at: '2026-08-18T15:03:16.005Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
@@ -17638,8 +17648,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 8475
- slug: product-8475
+ name: Product 845966
+ slug: product-845966
meta_title:
meta_description:
meta_keywords:
@@ -17651,15 +17661,19 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Impedit dolorum dolor voluptatum praesentium dignissimos
- repellendus expedita. Deleniti deserunt maiores odio corporis cumque
- officia. Repudiandae quaerat suscipit error ullam nostrum enim.
- Aliquam quam commodi deserunt perferendis expedita.
- description_html: Impedit dolorum dolor voluptatum praesentium dignissimos
- repellendus expedita. Deleniti deserunt maiores odio corporis cumque
- officia. Repudiandae quaerat suscipit error ullam nostrum enim.
- Aliquam quam commodi deserunt perferendis expedita.
+ description: Accusantium omnis assumenda beatae necessitatibus porro.
+ Nemo ad consequuntur fugit sint. Numquam assumenda dicta rem dignissimos
+ recusandae sapiente. Modi consequuntur dicta possimus quas. Aperiam
+ eligendi suscipit tempora consectetur quae accusantium. Rem consequatur
+ ipsa adipisci velit tenetur voluptatibus numquam. Id inventore dignissimos
+ perferendis qui nam consectetur. Porro nostrum id temporibus placeat.
+ Labore asperiores nihil ut temporibus maxime perspiciatis accusamus
+ illo.
+ description_html: |-
+ Accusantium omnis assumenda beatae necessitatibus porro. Nemo ad consequuntur fugit sint. Numquam assumenda dicta rem dignissimos recusandae sapiente. Modi consequuntur dicta possimus quas. Aperiam eligendi suscipit tempora consectetur quae accusantium.
+ Rem consequatur ipsa adipisci velit tenetur voluptatibus numquam. Id inventore dignissimos perferendis qui nam consectetur. Porro nostrum id temporibus placeat. Labore asperiores nihil ut temporibus maxime perspiciatis accusamus illo.
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -17673,15 +17687,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:38.767Z'
- updated_at: '2026-08-17T19:06:38.767Z'
+ created_at: '2026-08-18T15:03:16.114Z'
+ updated_at: '2026-08-18T15:03:16.114Z'
original_price:
seller_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:38.756Z'
- updated_at: '2026-08-17T19:06:38.774Z'
+ created_at: '2026-08-18T15:03:16.103Z'
+ updated_at: '2026-08-18T15:03:16.120Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
@@ -17754,7 +17768,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-865210
+ slug: product-867635
meta_title:
meta_description:
meta_keywords:
@@ -17766,25 +17780,14 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Temporibus qui numquam rerum iusto repellendus ex recusandae.
- Atque maiores nihil dolore temporibus quas. At voluptatum minus
- veritatis architecto distinctio. Ut cum illo illum accusamus. Temporibus
- at consequuntur unde molestiae architecto quis officia sunt. Pariatur
- illo sequi quo quibusdam occaecati provident at modi. Vel unde porro
- optio recusandae. Laudantium fugit pariatur ipsam deleniti expedita
- sunt aliquam. Fugit iste asperiores a ipsa. Nemo similique facere
- dignissimos eius totam error. Voluptates unde voluptatibus fuga
- qui doloremque consequuntur dolorum. Fugiat est veritatis sapiente
- eius vel. Vitae nihil earum sequi rem aperiam incidunt necessitatibus.
- Sint error rem ratione odit. Eveniet doloribus mollitia possimus
- vero dolorem. Officia vitae in laboriosam cum vel nemo. Nihil distinctio
- velit recusandae esse ab est voluptates.
- description_html: |-
- Temporibus qui numquam rerum iusto repellendus ex recusandae. Atque maiores nihil dolore temporibus quas. At voluptatum minus veritatis architecto distinctio. Ut cum illo illum accusamus.
- Temporibus at consequuntur unde molestiae architecto quis officia sunt. Pariatur illo sequi quo quibusdam occaecati provident at modi. Vel unde porro optio recusandae. Laudantium fugit pariatur ipsam deleniti expedita sunt aliquam. Fugit iste asperiores a ipsa.
- Nemo similique facere dignissimos eius totam error. Voluptates unde voluptatibus fuga qui doloremque consequuntur dolorum. Fugiat est veritatis sapiente eius vel. Vitae nihil earum sequi rem aperiam incidunt necessitatibus.
- Sint error rem ratione odit. Eveniet doloribus mollitia possimus vero dolorem. Officia vitae in laboriosam cum vel nemo. Nihil distinctio velit recusandae esse ab est voluptates.
+ description: Veritatis quod officiis nesciunt rerum porro culpa. Accusantium
+ omnis esse soluta optio debitis commodi eaque. Nemo consectetur
+ amet itaque laboriosam provident earum.
+ description_html: Veritatis quod officiis nesciunt rerum porro culpa.
+ Accusantium omnis esse soluta optio debitis commodi eaque. Nemo
+ consectetur amet itaque laboriosam provident earum.
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -17798,15 +17801,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:38.912Z'
- updated_at: '2026-08-17T19:06:38.912Z'
+ created_at: '2026-08-18T15:03:16.268Z'
+ updated_at: '2026-08-18T15:03:16.268Z'
original_price:
seller_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:38.900Z'
- updated_at: '2026-08-17T19:06:38.949Z'
+ created_at: '2026-08-18T15:03:16.247Z'
+ updated_at: '2026-08-18T15:03:16.306Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
@@ -18752,15 +18755,15 @@ paths:
- id: coupon_UkLWZg9DAJ
code: AAA111
state: unused
- created_at: '2026-08-17T19:06:24.343Z'
- updated_at: '2026-08-17T19:06:24.343Z'
+ created_at: '2026-08-18T15:02:57.048Z'
+ updated_at: '2026-08-18T15:02:57.048Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
- id: coupon_gbHJdmfrXB
code: BBB222
state: unused
- created_at: '2026-08-17T19:06:24.344Z'
- updated_at: '2026-08-17T19:06:24.344Z'
+ created_at: '2026-08-18T15:02:57.049Z'
+ updated_at: '2026-08-18T15:02:57.049Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
meta:
@@ -18822,8 +18825,8 @@ paths:
example:
data:
- id: pact_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:40.242Z'
- updated_at: '2026-08-17T19:06:40.242Z'
+ created_at: '2026-08-18T15:03:17.536Z'
+ updated_at: '2026-08-18T15:03:17.536Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -18887,8 +18890,8 @@ paths:
application/json:
example:
id: pact_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:40.289Z'
- updated_at: '2026-08-17T19:06:40.289Z'
+ created_at: '2026-08-18T15:03:17.577Z'
+ updated_at: '2026-08-18T15:03:17.577Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -19016,8 +19019,8 @@ paths:
example:
data:
- id: prorule_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:40.360Z'
- updated_at: '2026-08-17T19:06:40.360Z'
+ created_at: '2026-08-18T15:03:17.636Z'
+ updated_at: '2026-08-18T15:03:17.636Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -19087,8 +19090,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:40.408Z'
- updated_at: '2026-08-17T19:06:40.408Z'
+ created_at: '2026-08-18T15:03:17.675Z'
+ updated_at: '2026-08-18T15:03:17.675Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -19179,8 +19182,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:40.443Z'
- updated_at: '2026-08-17T19:06:40.467Z'
+ created_at: '2026-08-18T15:03:17.706Z'
+ updated_at: '2026-08-18T15:03:17.726Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -19288,7 +19291,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-17T19:06:40.508Z'
+ starts_at: '2026-08-18T15:03:17.764Z'
expires_at:
usage_limit:
match_policy: all
@@ -19299,8 +19302,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-17T19:06:40.508Z'
- updated_at: '2026-08-17T19:06:40.508Z'
+ created_at: '2026-08-18T15:03:17.764Z'
+ updated_at: '2026-08-18T15:03:17.764Z'
action_ids: []
rule_ids: []
meta:
@@ -19407,7 +19410,7 @@ paths:
name: Black Friday
description:
code: blackfriday-os
- starts_at: '2026-08-17T19:06:40.657Z'
+ starts_at: '2026-08-18T15:03:17.906Z'
expires_at:
usage_limit:
match_policy: all
@@ -19418,8 +19421,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-17T19:06:40.657Z'
- updated_at: '2026-08-17T19:06:40.678Z'
+ created_at: '2026-08-18T15:03:17.906Z'
+ updated_at: '2026-08-18T15:03:17.928Z'
action_ids:
- pact_UkLWZg9DAJ
- pact_gbHJdmfrXB
@@ -19585,7 +19588,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-17T19:06:40.716Z'
+ starts_at: '2026-08-18T15:03:17.962Z'
expires_at:
usage_limit:
match_policy: all
@@ -19596,8 +19599,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-17T19:06:40.716Z'
- updated_at: '2026-08-17T19:06:40.716Z'
+ created_at: '2026-08-18T15:03:17.962Z'
+ updated_at: '2026-08-18T15:03:17.962Z'
action_ids: []
rule_ids: []
patch:
@@ -19694,7 +19697,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-17T19:06:40.824Z'
+ starts_at: '2026-08-18T15:03:18.065Z'
expires_at:
usage_limit:
match_policy: all
@@ -19705,8 +19708,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-17T19:06:40.824Z'
- updated_at: '2026-08-17T19:06:40.851Z'
+ created_at: '2026-08-18T15:03:18.065Z'
+ updated_at: '2026-08-18T15:03:18.083Z'
action_ids: []
rule_ids: []
requestBody:
@@ -20178,15 +20181,15 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-2a6eaa36b3e8
+ transaction_id: BGS-fe4d008c75c3
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
originator_id:
originator_type:
metadata: {}
- created_at: '2026-08-17T19:06:34.131Z'
- updated_at: '2026-08-17T19:06:34.131Z'
+ created_at: '2026-08-18T15:03:11.435Z'
+ updated_at: '2026-08-18T15:03:11.435Z'
requestBody:
content:
application/json:
@@ -20330,8 +20333,8 @@ paths:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-17T19:06:41.982Z'
- updated_at: '2026-08-17T19:06:41.982Z'
+ created_at: '2026-08-18T15:03:19.159Z'
+ updated_at: '2026-08-18T15:03:19.159Z'
non_expiring: false
meta:
page: 1
@@ -20425,8 +20428,8 @@ paths:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-17T19:06:42.032Z'
- updated_at: '2026-08-17T19:06:42.032Z'
+ created_at: '2026-08-18T15:03:19.190Z'
+ updated_at: '2026-08-18T15:03:19.190Z'
non_expiring: false
schema:
"$ref": "#/components/schemas/StoreCreditCategory"
@@ -20520,8 +20523,8 @@ paths:
preferred_order_number_prefix: R
preferred_order_number_suffix: ''
preferred_order_number_sequence_start: 1001
- created_at: '2026-08-17T19:06:20.124Z'
- updated_at: '2026-08-17T19:06:42.097Z'
+ created_at: '2026-08-18T15:02:49.283Z'
+ updated_at: '2026-08-18T15:03:19.246Z'
order_number_sequence_started: false
url: http://www.example.com:3000
api_url: http://www.example.com:3000
@@ -20836,8 +20839,8 @@ paths:
preferred_order_number_prefix: R
preferred_order_number_suffix: ''
preferred_order_number_sequence_start: 1001
- created_at: '2026-08-17T19:06:20.124Z'
- updated_at: '2026-08-17T19:06:42.177Z'
+ created_at: '2026-08-18T15:02:49.283Z'
+ updated_at: '2026-08-18T15:03:19.330Z'
order_number_sequence_started: false
url: http://www.example.com:3000
api_url: http://www.example.com:3000
@@ -21234,12 +21237,12 @@ paths:
example:
data:
- id: tax_UkLWZg9DAJ
- name: TaxRate - 748351
+ name: TaxRate - 180930
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-17T19:06:42.296Z'
- updated_at: '2026-08-17T19:06:42.296Z'
+ created_at: '2026-08-18T15:03:19.439Z'
+ updated_at: '2026-08-18T15:03:19.439Z'
deleted_at:
amount: '0.19'
amount_percentage: 19.0
@@ -21321,8 +21324,8 @@ paths:
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-17T19:06:42.364Z'
- updated_at: '2026-08-17T19:06:42.364Z'
+ created_at: '2026-08-18T15:03:19.500Z'
+ updated_at: '2026-08-18T15:03:19.500Z'
deleted_at:
amount: '0.19'
amount_percentage: 19.0
@@ -21413,12 +21416,12 @@ paths:
application/json:
example:
id: tax_UkLWZg9DAJ
- name: TaxRate - 106399
+ name: TaxRate - 85421
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-17T19:06:42.405Z'
- updated_at: '2026-08-17T19:06:42.405Z'
+ created_at: '2026-08-18T15:03:19.541Z'
+ updated_at: '2026-08-18T15:03:19.541Z'
deleted_at:
amount: '0.19'
amount_percentage: 19.0
@@ -21455,12 +21458,12 @@ paths:
application/json:
example:
id: tax_UkLWZg9DAJ
- name: TaxRate - 424013
+ name: TaxRate - 477527
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-17T19:06:42.432Z'
- updated_at: '2026-08-17T19:06:42.448Z'
+ created_at: '2026-08-18T15:03:19.568Z'
+ updated_at: '2026-08-18T15:03:19.583Z'
deleted_at:
amount: '0.07'
amount_percentage: 7.0
@@ -21773,13 +21776,13 @@ paths:
example:
data:
- id: adm_UkLWZg9DAJ
- first_name: Tamra
- last_name: Howe
- full_name: Tamra Howe
+ first_name: Krysten
+ last_name: Heaney
+ full_name: Krysten Heaney
selected_locale:
- created_at: '2026-08-17T19:06:20.230Z'
- updated_at: '2026-08-17T19:06:20.230Z'
+ created_at: '2026-08-18T15:02:49.435Z'
+ updated_at: '2026-08-18T15:02:49.435Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -21845,13 +21848,13 @@ paths:
application/json:
example:
id: adm_UkLWZg9DAJ
- first_name: Frankie
- last_name: Schumm
- full_name: Frankie Schumm
+ first_name: Deetta
+ last_name: Cummings
+ full_name: Deetta Cummings
selected_locale:
- created_at: '2026-08-17T19:06:20.418Z'
- updated_at: '2026-08-17T19:06:20.418Z'
+ created_at: '2026-08-18T15:02:49.774Z'
+ updated_at: '2026-08-18T15:02:49.774Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -21912,13 +21915,13 @@ paths:
application/json:
example:
id: adm_UkLWZg9DAJ
first_name: Renamed
- last_name: White
- full_name: Renamed White
+ last_name: Stokes
+ full_name: Renamed Stokes
selected_locale:
- created_at: '2026-08-17T19:06:20.444Z'
- updated_at: '2026-08-17T19:06:20.460Z'
+ created_at: '2026-08-18T15:02:49.841Z'
+ updated_at: '2026-08-18T15:02:49.861Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -22034,15 +22037,15 @@ paths:
example:
data:
- id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-08-17T19:06:27.411Z'
- updated_at: '2026-08-17T19:06:27.411Z'
- expires_at: '2026-08-31T19:06:27.407Z'
+ created_at: '2026-08-18T15:03:02.233Z'
+ updated_at: '2026-08-18T15:03:02.233Z'
+ expires_at: '2026-09-01T15:03:02.232Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=TcFdvTFfjaYD5dE6NYqGgURg"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=KumdpyZzeUzD9yWAG5XPpYc1"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -22106,13 +22109,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-08-17T19:06:27.504Z'
- updated_at: '2026-08-17T19:06:27.504Z'
- expires_at: '2026-08-31T19:06:27.499Z'
+ created_at: '2026-08-18T15:03:02.279Z'
+ updated_at: '2026-08-18T15:03:02.279Z'
+ expires_at: '2026-09-01T15:03:02.275Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=BTxgLZFGyCGHxrpijqf17zqA"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=xFRNbPutgNzJeYHmnsHJxBFT"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -22225,15 +22228,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-08-17T19:06:27.580Z'
- updated_at: '2026-08-17T19:06:27.580Z'
- expires_at: '2026-08-31T19:06:27.578Z'
+ created_at: '2026-08-18T15:03:02.366Z'
+ updated_at: '2026-08-18T15:03:02.366Z'
+ expires_at: '2026-09-01T15:03:02.364Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=k9VXfLmzsikWLYpPGhBnBHFF"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=6TXjv2VtQkUJ6Kdp1FJVWnSR"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -22620,8 +22623,8 @@ paths:
- id: role_UkLWZg9DAJ
name: admin
description:
- created_at: '2026-08-17T19:06:40.956Z'
- updated_at: '2026-08-17T19:06:40.956Z'
+ created_at: '2026-08-18T15:03:18.179Z'
+ updated_at: '2026-08-18T15:03:18.179Z'
permissions:
- read_orders
- write_orders
@@ -22727,8 +22730,8 @@ paths:
id: role_gbHJdmfrXB
name: order_manager
description: Handles daily orders
- created_at: '2026-08-17T19:06:40.997Z'
- updated_at: '2026-08-17T19:06:40.997Z'
+ created_at: '2026-08-18T15:03:18.210Z'
+ updated_at: '2026-08-18T15:03:18.210Z'
permissions:
- write_orders
- read_customers
@@ -22822,8 +22825,8 @@ paths:
id: role_gbHJdmfrXB
name: support
description:
- created_at: '2026-08-17T19:06:41.033Z'
- updated_at: '2026-08-17T19:06:41.048Z'
+ created_at: '2026-08-18T15:03:18.242Z'
+ updated_at: '2026-08-18T15:03:18.255Z'
permissions:
- read_orders
- read_customers
@@ -23019,8 +23022,8 @@ paths:
kind: warehouse
pickup_enabled: false
pickup_stock_policy: local
- created_at: '2026-08-17T19:06:41.740Z'
- updated_at: '2026-08-17T19:06:41.740Z'
+ created_at: '2026-08-18T15:03:18.857Z'
+ updated_at: '2026-08-18T15:03:18.857Z'
meta:
page: 1
limit: 25
@@ -23134,8 +23137,8 @@ paths:
kind: store
pickup_enabled: true
pickup_stock_policy: local
- created_at: '2026-08-17T19:06:41.800Z'
- updated_at: '2026-08-17T19:06:41.800Z'
+ created_at: '2026-08-18T15:03:18.993Z'
+ updated_at: '2026-08-18T15:03:18.993Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -23312,8 +23315,8 @@ paths:
kind: warehouse
pickup_enabled: false
pickup_stock_policy: local
- created_at: '2026-08-17T19:06:41.838Z'
- updated_at: '2026-08-17T19:06:41.838Z'
+ created_at: '2026-08-18T15:03:19.039Z'
+ updated_at: '2026-08-18T15:03:19.039Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'404':
@@ -23402,8 +23405,8 @@ paths:
kind: warehouse
pickup_enabled: true
pickup_stock_policy: local
- created_at: '2026-08-17T19:06:41.890Z'
- updated_at: '2026-08-17T19:06:41.904Z'
+ created_at: '2026-08-18T15:03:19.088Z'
+ updated_at: '2026-08-18T15:03:19.105Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -23650,17 +23653,15 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-17T19:06:42.592Z'
- updated_at: '2026-08-17T19:06:42.602Z'
+ created_at: '2026-08-18T15:03:19.699Z'
+ updated_at: '2026-08-18T15:03:19.709Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 105198
- seller_name:
+ product_name: Product 1055726
delivery_profile_id: fp_UkLWZg9DAJ
- own_delivery_profile_id:
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
sku: SKU-125
@@ -23673,10 +23674,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 38.2
- height: 28.41
- width: 102.7
- depth: 38.48
+ weight: 69.92
+ height: 105.48
+ width: 98.12
+ depth: 194.45
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -23700,8 +23701,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:42.620Z'
- updated_at: '2026-08-17T19:06:42.620Z'
+ created_at: '2026-08-18T15:03:19.725Z'
+ updated_at: '2026-08-18T15:03:19.725Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -23714,17 +23715,15 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-17T19:06:42.618Z'
- updated_at: '2026-08-17T19:06:42.627Z'
+ created_at: '2026-08-18T15:03:19.722Z'
+ updated_at: '2026-08-18T15:03:19.731Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 105198
- seller_name:
+ product_name: Product 1055726
delivery_profile_id: fp_UkLWZg9DAJ
- own_delivery_profile_id:
meta:
page: 1
limit: 25
@@ -23839,8 +23838,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:42.753Z'
- updated_at: '2026-08-17T19:06:42.753Z'
+ created_at: '2026-08-18T15:03:19.850Z'
+ updated_at: '2026-08-18T15:03:19.850Z'
metadata: {}
position: 3
cost_price:
@@ -23853,17 +23852,15 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-17T19:06:42.757Z'
- updated_at: '2026-08-17T19:06:42.759Z'
+ created_at: '2026-08-18T15:03:19.855Z'
+ updated_at: '2026-08-18T15:03:19.856Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1066488
- seller_name:
+ product_name: Product 1061626
delivery_profile_id: fp_UkLWZg9DAJ
- own_delivery_profile_id:
'422':
description: validation error
content:
@@ -24050,10 +24047,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 115.94
- height: 108.69
- width: 30.56
- depth: 58.86
+ weight: 182.3
+ height: 140.54
+ width: 188.36
+ depth: 107.25
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -24077,8 +24074,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:42.927Z'
- updated_at: '2026-08-17T19:06:42.927Z'
+ created_at: '2026-08-18T15:03:19.996Z'
+ updated_at: '2026-08-18T15:03:19.996Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -24091,17 +24088,15 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-17T19:06:42.924Z'
- updated_at: '2026-08-17T19:06:42.936Z'
+ created_at: '2026-08-18T15:03:19.994Z'
+ updated_at: '2026-08-18T15:03:20.004Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1088758
- seller_name:
+ product_name: Product 1088309
delivery_profile_id: fp_UkLWZg9DAJ
- own_delivery_profile_id:
'404':
description: variant not found
content:
@@ -24185,10 +24180,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 22.69
- height: 167.4
- width: 127.29
- depth: 9.72
+ weight: 30.6
+ height: 179.16
+ width: 55.67
+ depth: 151.2
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -24212,8 +24207,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-17T19:06:43.127Z'
- updated_at: '2026-08-17T19:06:43.127Z'
+ created_at: '2026-08-18T15:03:20.161Z'
+ updated_at: '2026-08-18T15:03:20.161Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -24226,17 +24221,15 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-17T19:06:43.125Z'
- updated_at: '2026-08-17T19:06:43.158Z'
+ created_at: '2026-08-18T15:03:20.159Z'
+ updated_at: '2026-08-18T15:03:20.187Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1101027
- seller_name:
+ product_name: Product 1109151
delivery_profile_id: fp_UkLWZg9DAJ
- own_delivery_profile_id:
requestBody:
content:
application/json:
@@ -24481,9 +24474,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-17T19:06:43.360Z'
- updated_at: '2026-08-17T19:06:43.360Z'
- delivered_at: '2026-08-17T19:06:43.359Z'
+ created_at: '2026-08-18T15:03:20.302Z'
+ updated_at: '2026-08-18T15:03:20.302Z'
+ delivered_at: '2026-08-18T15:03:20.302Z'
payload:
event: order.created
data:
@@ -24499,9 +24492,9 @@ paths:
request_errors:
response_body:
success: true
- created_at: '2026-08-17T19:06:43.358Z'
- updated_at: '2026-08-17T19:06:43.358Z'
- delivered_at: '2026-08-17T19:06:43.358Z'
+ created_at: '2026-08-18T15:03:20.301Z'
+ updated_at: '2026-08-18T15:03:20.301Z'
+ delivered_at: '2026-08-18T15:03:20.301Z'
payload:
event: order.created
data:
@@ -24604,9 +24597,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-17T19:06:43.556Z'
- updated_at: '2026-08-17T19:06:43.556Z'
- delivered_at: '2026-08-17T19:06:43.556Z'
+ created_at: '2026-08-18T15:03:20.389Z'
+ updated_at: '2026-08-18T15:03:20.389Z'
+ delivered_at: '2026-08-18T15:03:20.389Z'
payload:
event: order.created
data:
@@ -24695,8 +24688,8 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-17T19:06:43.709Z'
- updated_at: '2026-08-17T19:06:43.709Z'
+ created_at: '2026-08-18T15:03:20.472Z'
+ updated_at: '2026-08-18T15:03:20.472Z'
delivered_at:
payload:
event: order.created
@@ -24799,8 +24792,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-17T19:06:43.755Z'
- updated_at: '2026-08-17T19:06:43.755Z'
+ created_at: '2026-08-18T15:03:20.490Z'
+ updated_at: '2026-08-18T15:03:20.490Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -24895,10 +24888,10 @@ paths:
subscriptions:
- order.placed
disabled_reason:
- created_at: '2026-08-17T19:06:44.027Z'
- updated_at: '2026-08-17T19:06:44.027Z'
+ created_at: '2026-08-18T15:03:20.641Z'
+ updated_at: '2026-08-18T15:03:20.641Z'
disabled_at:
- secret_key: 2feaa6d5e9ab5633bd071cabd401595a56403f6284846efa20f3b897e0311ec6
+ secret_key: 3bb0f59be1eba5c2e99fa50d583f6fc62472aa50661863bbf1fd95f9dace863f
last_delivery_at:
recent_delivery_count: 0
recent_failure_count: 0
@@ -25021,8 +25014,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-17T19:06:44.098Z'
- updated_at: '2026-08-17T19:06:44.098Z'
+ created_at: '2026-08-18T15:03:20.687Z'
+ updated_at: '2026-08-18T15:03:20.687Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -25101,8 +25094,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-17T19:06:44.188Z'
- updated_at: '2026-08-17T19:06:44.203Z'
+ created_at: '2026-08-18T15:03:20.750Z'
+ updated_at: '2026-08-18T15:03:20.764Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -25259,13 +25252,13 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-17T19:06:44.341Z'
- updated_at: '2026-08-17T19:06:44.341Z'
+ created_at: '2026-08-18T15:03:20.848Z'
+ updated_at: '2026-08-18T15:03:20.848Z'
delivered_at:
payload:
- id: 0baaf3dc-c936-4e82-8a7f-12e9bf8d291a
+ id: fd1a30a5-8405-4a36-b37d-f46cc7054338
name: webhook.test
- created_at: '2026-08-17T19:06:44Z'
+ created_at: '2026-08-18T15:03:20Z'
data:
message: This is a test webhook from Spree.
metadata:
@@ -25334,8 +25327,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-17T19:06:44.372Z'
- updated_at: '2026-08-17T19:06:44.389Z'
+ created_at: '2026-08-18T15:03:20.861Z'
+ updated_at: '2026-08-18T15:03:20.876Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -25412,9 +25405,9 @@ paths:
- order.completed
- product.created
disabled_reason: Investigating
- created_at: '2026-08-17T19:06:44.498Z'
- updated_at: '2026-08-17T19:06:44.514Z'
- disabled_at: '2026-08-17T19:06:44.514Z'
+ created_at: '2026-08-18T15:03:20.890Z'
+ updated_at: '2026-08-18T15:03:20.916Z'
+ disabled_at: '2026-08-18T15:03:20.916Z'
secret_key:
last_delivery_at:
recent_delivery_count: 0
@@ -25497,8 +25490,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-17T19:06:22.126Z'
- updated_at: '2026-08-17T19:06:22.126Z'
+ created_at: '2026-08-18T15:02:53.065Z'
+ updated_at: '2026-08-18T15:02:53.065Z'
meta:
page: 1
limit: 25
@@ -25566,8 +25559,8 @@ paths:
automatic: true
rules_match_policy: any
metadata: {}
- created_at: '2026-08-17T19:06:22.191Z'
- updated_at: '2026-08-17T19:06:22.193Z'
+ created_at: '2026-08-18T15:02:53.178Z'
+ updated_at: '2026-08-18T15:02:53.180Z'
schema:
"$ref": "#/components/schemas/Collection"
'422':
@@ -25694,8 +25687,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-17T19:06:22.243Z'
- updated_at: '2026-08-17T19:06:22.243Z'
+ created_at: '2026-08-18T15:02:53.300Z'
+ updated_at: '2026-08-18T15:02:53.300Z'
schema:
"$ref": "#/components/schemas/Collection"
'404':
@@ -25759,8 +25752,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-17T19:06:22.296Z'
- updated_at: '2026-08-17T19:06:22.314Z'
+ created_at: '2026-08-18T15:02:53.443Z'
+ updated_at: '2026-08-18T15:02:53.468Z'
schema:
"$ref": "#/components/schemas/Collection"
requestBody:
@@ -25935,8 +25928,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 68922
- slug: product-68922
+ name: Product 68484
+ slug: product-68484
meta_title:
meta_description:
meta_keywords:
@@ -25948,17 +25941,26 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Esse dolorum corrupti maiores eligendi laboriosam ea
- ullam. Quasi consequatur distinctio facilis qui sint magnam aperiam
- labore. Possimus autem tempore adipisci cupiditate dolore id officia.
- Fuga porro sed ab ea. Libero quidem odio animi inventore id eum
- adipisci dignissimos. Perspiciatis quas laborum consequatur animi
- ullam quae adipisci in. Unde similique vitae ipsa iusto rerum optio
- commodi.
+ description: Ad dolores quos facere illum magni ab inventore ratione.
+ Hic repellat non possimus sint esse reprehenderit aperiam blanditiis.
+ Nihil quam repellendus illum repellat similique numquam possimus.
+ Perspiciatis vitae necessitatibus quisquam doloribus odit quos impedit.
+ Aut tenetur similique laborum autem repudiandae. Unde enim eius
+ illo debitis necessitatibus. Reprehenderit sed odio quasi quaerat
+ perspiciatis. Quo maiores sunt totam repellat. Vero provident qui
+ quo ratione blanditiis animi. Et sapiente quod natus totam eligendi
+ corporis ullam fugiat. Accusantium odit facilis cumque quae reiciendis.
+ Eius iste quae corporis maxime. Ex aliquid laboriosam ipsam quaerat
+ eveniet eligendi autem. Perferendis consectetur repellendus eaque
+ reiciendis quibusdam reprehenderit. Culpa quidem perferendis hic
+ eligendi repudiandae illo. Animi aliquid tenetur perferendis dolore.
description_html: |-
- Esse dolorum corrupti maiores eligendi laboriosam ea ullam. Quasi consequatur distinctio facilis qui sint magnam aperiam labore. Possimus autem tempore adipisci cupiditate dolore id officia. Fuga porro sed ab ea.
- Libero quidem odio animi inventore id eum adipisci dignissimos. Perspiciatis quas laborum consequatur animi ullam quae adipisci in. Unde similique vitae ipsa iusto rerum optio commodi.
+ Ad dolores quos facere illum magni ab inventore ratione. Hic repellat non possimus sint esse reprehenderit aperiam blanditiis. Nihil quam repellendus illum repellat similique numquam possimus.
+ Perspiciatis vitae necessitatibus quisquam doloribus odit quos impedit. Aut tenetur similique laborum autem repudiandae. Unde enim eius illo debitis necessitatibus. Reprehenderit sed odio quasi quaerat perspiciatis. Quo maiores sunt totam repellat.
+ Vero provident qui quo ratione blanditiis animi. Et sapiente quod natus totam eligendi corporis ullam fugiat. Accusantium odit facilis cumque quae reiciendis. Eius iste quae corporis maxime. Ex aliquid laboriosam ipsam quaerat eveniet eligendi autem.
+ Perferendis consectetur repellendus eaque reiciendis quibusdam reprehenderit. Culpa quidem perferendis hic eligendi repudiandae illo. Animi aliquid tenetur perferendis dolore.
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -25972,15 +25974,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:22.425Z'
- updated_at: '2026-08-17T19:06:22.425Z'
+ created_at: '2026-08-18T15:02:53.753Z'
+ updated_at: '2026-08-18T15:02:53.753Z'
original_price:
seller_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:22.412Z'
- updated_at: '2026-08-17T19:06:22.434Z'
+ created_at: '2026-08-18T15:02:53.696Z'
+ updated_at: '2026-08-18T15:02:53.781Z'
delivery_profile_id: fp_UkLWZg9DAJ
seller_name:
product_type_id:
@@ -26227,8 +26229,8 @@ paths:
taxability_reason:
country_code:
state_code:
- created_at: '2026-08-17T19:06:22.879Z'
- updated_at: '2026-08-17T19:06:22.879Z'
+ created_at: '2026-08-18T15:02:54.478Z'
+ updated_at: '2026-08-18T15:02:54.478Z'
rate: '10.0'
tax_rate: '0.0'
amount: '10.0'
@@ -26314,8 +26316,8 @@ paths:
taxability_reason:
country_code:
state_code:
- created_at: '2026-08-17T19:06:23.094Z'
- updated_at: '2026-08-17T19:06:23.094Z'
+ created_at: '2026-08-18T15:02:54.813Z'
+ updated_at: '2026-08-18T15:02:54.813Z'
rate: '10.0'
tax_rate: '0.0'
amount: '10.0'
@@ -26440,8 +26442,8 @@ paths:
include_shipping: false
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:23.240Z'
- updated_at: '2026-08-17T19:06:23.240Z'
+ created_at: '2026-08-18T15:02:55.057Z'
+ updated_at: '2026-08-18T15:02:55.057Z'
value: '10.0'
commission_tax_rate:
amounts: {}
@@ -26556,8 +26558,8 @@ paths:
include_shipping: false
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:23.303Z'
- updated_at: '2026-08-17T19:06:23.303Z'
+ created_at: '2026-08-18T15:02:55.221Z'
+ updated_at: '2026-08-18T15:02:55.221Z'
value: '12.5'
commission_tax_rate:
amounts: {}
@@ -26840,8 +26842,8 @@ paths:
include_shipping: false
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:23.367Z'
- updated_at: '2026-08-17T19:06:23.367Z'
+ created_at: '2026-08-18T15:02:55.302Z'
+ updated_at: '2026-08-18T15:02:55.302Z'
value: '10.0'
commission_tax_rate:
amounts: {}
@@ -26928,8 +26930,8 @@ paths:
include_shipping: false
metadata: {}
deleted_at:
- created_at: '2026-08-17T19:06:23.432Z'
- updated_at: '2026-08-17T19:06:23.451Z'
+ created_at: '2026-08-18T15:02:55.403Z'
+ updated_at: '2026-08-18T15:02:55.427Z'
value: '15.0'
commission_tax_rate:
amounts: {}
@@ -27067,8 +27069,8 @@ paths:
name: Berlin
external_id:
metadata: {}
- created_at: '2026-08-17T19:06:23.489Z'
- updated_at: '2026-08-17T19:06:23.489Z'
+ created_at: '2026-08-18T15:02:55.469Z'
+ updated_at: '2026-08-18T15:02:55.469Z'
company_id: comp_UkLWZg9DAJ
contacts_count: 0
billing_address:
@@ -27147,8 +27149,8 @@ paths:
name: Hamburg warehouse
external_id:
metadata: {}
- created_at: '2026-08-17T19:06:23.532Z'
- updated_at: '2026-08-17T19:06:23.532Z'
+ created_at: '2026-08-18T15:02:55.581Z'
+ updated_at: '2026-08-18T15:02:55.581Z'
company_id: comp_UkLWZg9DAJ
contacts_count: 0
billing_address:
@@ -27174,8 +27176,8 @@ paths:
state_name:
label:
metadata: {}
- created_at: '2026-08-17T19:06:23.532Z'
- updated_at: '2026-08-17T19:06:23.532Z'
+ created_at: '2026-08-18T15:02:55.580Z'
+ updated_at: '2026-08-18T15:02:55.580Z'
customer_id:
shipping_address:
'422':
@@ -27274,8 +27276,8 @@ paths:
name: Berlin
external_id:
metadata: {}
- created_at: '2026-08-17T19:06:23.560Z'
- updated_at: '2026-08-17T19:06:23.560Z'
+ created_at: '2026-08-18T15:02:55.615Z'
+ updated_at: '2026-08-18T15:02:55.615Z'
company_id: comp_UkLWZg9DAJ
contacts_count: 0
billing_address:
@@ -27321,8 +27323,8 @@ paths:
name: Berlin Mitte
external_id:
metadata: {}
- created_at: '2026-08-17T19:06:23.581Z'
- updated_at: '2026-08-17T19:06:23.598Z'
+ created_at: '2026-08-18T15:02:55.648Z'
+ updated_at: '2026-08-18T15:02:55.731Z'
company_id: comp_UkLWZg9DAJ
contacts_count: 0
billing_address:
@@ -27437,8 +27439,8 @@ paths:
issued_at:
expires_at:
verified_at:
- created_at: '2026-08-17T19:06:23.634Z'
- updated_at: '2026-08-17T19:06:23.634Z'
+ created_at: '2026-08-18T15:02:55.802Z'
+ updated_at: '2026-08-18T15:02:55.802Z'
company_id: comp_UkLWZg9DAJ
country_code:
state_code:
@@ -27522,8 +27524,8 @@ paths:
issued_at:
expires_at:
verified_at:
- created_at: '2026-08-17T19:06:23.692Z'
- updated_at: '2026-08-17T19:06:23.694Z'
+ created_at: '2026-08-18T15:02:55.871Z'
+ updated_at: '2026-08-18T15:02:55.876Z'
company_id: comp_UkLWZg9DAJ
country_code: DE
state_code:
@@ -27652,9 +27654,9 @@ paths:
metadata: {}
issued_at:
expires_at:
- verified_at: '2026-08-17T19:06:23.782Z'
- created_at: '2026-08-17T19:06:23.763Z'
- updated_at: '2026-08-17T19:06:23.783Z'
+ verified_at: '2026-08-18T15:02:56.101Z'
+ created_at: '2026-08-18T15:02:56.041Z'
+ updated_at: '2026-08-18T15:02:56.111Z'
company_id: comp_UkLWZg9DAJ
country_code:
state_code:
@@ -27732,9 +27734,9 @@ paths:
metadata: {}
issued_at:
expires_at:
- verified_at: '2026-08-17T19:06:23.791Z'
- created_at: '2026-08-17T19:06:23.791Z'
- updated_at: '2026-08-17T19:06:23.823Z'
+ verified_at: '2026-08-18T15:02:56.160Z'
+ created_at: '2026-08-18T15:02:56.164Z'
+ updated_at: '2026-08-18T15:02:56.222Z'
company_id: comp_UkLWZg9DAJ
country_code:
state_code:
@@ -27852,8 +27854,8 @@ paths:
validation_evidence:
source:
validated_at:
- created_at: '2026-08-17T19:06:23.893Z'
- updated_at: '2026-08-17T19:06:23.893Z'
+ created_at: '2026-08-18T15:02:56.411Z'
+ updated_at: '2026-08-18T15:02:56.411Z'
validatable: false
customer_id:
cart_id:
@@ -27915,8 +27917,8 @@ paths:
validation_evidence:
source:
validated_at:
- created_at: '2026-08-17T19:06:23.948Z'
- updated_at: '2026-08-17T19:06:23.948Z'
+ created_at: '2026-08-18T15:02:56.510Z'
+ updated_at: '2026-08-18T15:02:56.510Z'
validatable: false
customer_id:
cart_id:
@@ -28063,8 +28065,8 @@ paths:
name: Acme Industrial
external_id: ACME-1
metadata: {}
- created_at: '2026-08-17T19:06:24.003Z'
- updated_at: '2026-08-17T19:06:24.003Z'
+ created_at: '2026-08-18T15:02:56.590Z'
+ updated_at: '2026-08-18T15:02:56.590Z'
locations_count: 0
meta:
page: 1
@@ -28126,8 +28128,8 @@ paths:
name: Globex Corporation
external_id: GLBX-42
metadata: {}
- created_at: '2026-08-17T19:06:24.043Z'
- updated_at: '2026-08-17T19:06:24.043Z'
+ created_at: '2026-08-18T15:02:56.688Z'
+ updated_at: '2026-08-18T15:02:56.688Z'
locations_count: 0
'422':
description: invalid request
@@ -28209,8 +28211,8 @@ paths:
data:
- id: cc_UkLWZg9DAJ
role: buyer
- created_at: '2026-08-17T19:06:24.080Z'
- updated_at: '2026-08-17T19:06:24.080Z'
+ created_at: '2026-08-18T15:02:56.774Z'
+ updated_at: '2026-08-18T15:02:56.774Z'
company_location_id: cloc_UkLWZg9DAJ
customer_id: cust_UkLWZg9DAJ
@@ -28266,11 +28268,11 @@ paths:
example:
id: cc_gbHJdmfrXB
role: admin
- created_at: '2026-08-17T19:06:24.161Z'
- updated_at: '2026-08-17T19:06:24.161Z'
+ created_at: '2026-08-18T15:02:56.879Z'
+ updated_at: '2026-08-18T15:02:56.879Z'
company_location_id: cloc_UkLWZg9DAJ
customer_id: cust_gbHJdmfrXB
'422':
description: invalid request
content:
@@ -28345,8 +28347,8 @@ paths:
example:
id: cc_UkLWZg9DAJ
role: buyer
- created_at: '2026-08-17T19:06:24.242Z'
- updated_at: '2026-08-17T19:06:24.242Z'
+ created_at: '2026-08-18T15:02:56.950Z'
+ updated_at: '2026-08-18T15:02:56.950Z'
company_location_id: cloc_UkLWZg9DAJ
customer_id: cust_UkLWZg9DAJ
@@ -28429,8 +28431,8 @@ paths:
name: General
default: true
position: 1
- created_at: '2026-08-17T19:06:20.191Z'
- updated_at: '2026-08-17T19:06:20.191Z'
+ created_at: '2026-08-18T15:02:49.398Z'
+ updated_at: '2026-08-18T15:02:49.398Z'
kind: shipping
digital: false
offers_pickup: false
@@ -28501,11 +28503,11 @@ paths:
application/json:
example:
id: fp_gbHJdmfrXB
- name: Oversized 1786993585.711488
+ name: Oversized 1787065379.512461
default: false
position: 2
- created_at: '2026-08-17T19:06:25.715Z'
- updated_at: '2026-08-17T19:06:25.715Z'
+ created_at: '2026-08-18T15:02:59.524Z'
+ updated_at: '2026-08-18T15:02:59.524Z'
kind: shipping
digital: false
offers_pickup: false
@@ -28609,8 +28611,8 @@ paths:
id: og_EfhxLZ9ck8
name: EU warehouse
position: 2
- created_at: '2026-08-17T19:06:25.766Z'
- updated_at: '2026-08-17T19:06:25.766Z'
+ created_at: '2026-08-18T15:02:59.664Z'
+ updated_at: '2026-08-18T15:02:59.664Z'
delivery_profile_id: fp_gbHJdmfrXB
stock_location_ids:
- sloc_UkLWZg9DAJ
@@ -28685,11 +28687,11 @@ paths:
application/json:
example:
id: fp_gbHJdmfrXB
- name: Bulky 1786993585.7741141
+ name: Bulky 1787065379.673368
default: false
position: 2
- created_at: '2026-08-17T19:06:25.774Z'
- updated_at: '2026-08-17T19:06:25.774Z'
+ created_at: '2026-08-18T15:02:59.674Z'
+ updated_at: '2026-08-18T15:02:59.674Z'
kind: shipping
digital: false
offers_pickup: false
@@ -28820,8 +28822,8 @@ paths:
tracking_url:
markup_flat: '0.0'
markup_percent: '0.0'
- created_at: '2026-08-17T19:06:25.844Z'
- updated_at: '2026-08-17T19:06:25.845Z'
+ created_at: '2026-08-18T15:02:59.802Z'
+ updated_at: '2026-08-18T15:02:59.804Z'
deleted_at:
services: []
rules: []
@@ -28909,8 +28911,8 @@ paths:
tracking_url:
markup_flat: '0.0'
markup_percent: '0.0'
- created_at: '2026-08-17T19:06:25.899Z'
- updated_at: '2026-08-17T19:06:25.900Z'
+ created_at: '2026-08-18T15:02:59.908Z'
+ updated_at: '2026-08-18T15:02:59.910Z'
deleted_at:
services: []
rules: []
@@ -29160,8 +29162,8 @@ paths:
postal_code_to:
country_name: United States
state_name:
- created_at: '2026-08-17T19:06:25.976Z'
- updated_at: '2026-08-17T19:06:25.976Z'
+ created_at: '2026-08-18T15:03:00.010Z'
+ updated_at: '2026-08-18T15:03:00.010Z'
- id: dzm_gbHJdmfrXB
member_type: postal_code
country_code: US
@@ -29171,10 +29173,10 @@ paths:
postal_code_to:
country_name: United States
state_name:
- created_at: '2026-08-17T19:06:25.976Z'
- updated_at: '2026-08-17T19:06:25.976Z'
- created_at: '2026-08-17T19:06:25.975Z'
- updated_at: '2026-08-17T19:06:25.975Z'
+ created_at: '2026-08-18T15:03:00.011Z'
+ updated_at: '2026-08-18T15:03:00.011Z'
+ created_at: '2026-08-18T15:03:00.010Z'
+ updated_at: '2026-08-18T15:03:00.010Z'
delivery_profile_id: fp_UkLWZg9DAJ
delivery_origin_group_id: og_UkLWZg9DAJ
delivery_method_ids: []
@@ -29269,8 +29271,8 @@ paths:
- id: int_UkLWZg9DAJ
name: Carrier
active: false
- created_at: '2026-08-17T19:06:27.246Z'
- updated_at: '2026-08-17T19:06:27.246Z'
+ created_at: '2026-08-18T15:03:02.080Z'
+ updated_at: '2026-08-18T15:03:02.080Z'
type: carrier
group: shipping
preferences:
@@ -29342,8 +29344,8 @@ paths:
id: int_UkLWZg9DAJ
name: Carrier
active: false
- created_at: '2026-08-17T19:06:27.289Z'
- updated_at: '2026-08-17T19:06:27.289Z'
+ created_at: '2026-08-18T15:03:02.129Z'
+ updated_at: '2026-08-18T15:03:02.129Z'
type: carrier
group: shipping
preferences:
@@ -29535,8 +29537,8 @@ paths:
- id: pt_UkLWZg9DAJ
name: T-Shirt
products_count: 0
- created_at: '2026-08-17T19:06:37.608Z'
- updated_at: '2026-08-17T19:06:37.608Z'
+ created_at: '2026-08-18T15:03:15.013Z'
+ updated_at: '2026-08-18T15:03:15.013Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -29611,8 +29613,8 @@ paths:
id: pt_gbHJdmfrXB
name: Hoodie
products_count: 0
- created_at: '2026-08-17T19:06:37.673Z'
- updated_at: '2026-08-17T19:06:37.673Z'
+ created_at: '2026-08-18T15:03:15.099Z'
+ updated_at: '2026-08-18T15:03:15.099Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -29712,8 +29714,8 @@ paths:
id: pt_UkLWZg9DAJ
name: T-Shirt
products_count: 0
- created_at: '2026-08-17T19:06:37.721Z'
- updated_at: '2026-08-17T19:06:37.721Z'
+ created_at: '2026-08-18T15:03:15.196Z'
+ updated_at: '2026-08-18T15:03:15.196Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -29766,8 +29768,8 @@ paths:
id: pt_UkLWZg9DAJ
name: Premium T-Shirt
products_count: 0
- created_at: '2026-08-17T19:06:37.859Z'
- updated_at: '2026-08-17T19:06:37.895Z'
+ created_at: '2026-08-18T15:03:15.279Z'
+ updated_at: '2026-08-18T15:03:15.297Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -29978,8 +29980,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.101Z'
- updated_at: '2026-08-17T19:06:41.101Z'
+ created_at: '2026-08-18T15:03:18.317Z'
+ updated_at: '2026-08-18T15:03:18.317Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -30088,8 +30090,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.154Z'
- updated_at: '2026-08-17T19:06:41.154Z'
+ created_at: '2026-08-18T15:03:18.370Z'
+ updated_at: '2026-08-18T15:03:18.370Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -30226,8 +30228,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.199Z'
- updated_at: '2026-08-17T19:06:41.199Z'
+ created_at: '2026-08-18T15:03:18.404Z'
+ updated_at: '2026-08-18T15:03:18.404Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -30314,8 +30316,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.284Z'
- updated_at: '2026-08-17T19:06:41.302Z'
+ created_at: '2026-08-18T15:03:18.481Z'
+ updated_at: '2026-08-18T15:03:18.501Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -30345,8 +30347,8 @@ paths:
state_name:
label:
metadata: {}
- created_at: '2026-08-17T19:06:41.302Z'
- updated_at: '2026-08-17T19:06:41.302Z'
+ created_at: '2026-08-18T15:03:18.501Z'
+ updated_at: '2026-08-18T15:03:18.501Z'
customer_id:
schema:
"$ref": "#/components/schemas/Seller"
@@ -30612,8 +30614,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.364Z'
- updated_at: '2026-08-17T19:06:41.403Z'
+ created_at: '2026-08-18T15:03:18.564Z'
+ updated_at: '2026-08-18T15:03:18.592Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -30709,8 +30711,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.446Z'
- updated_at: '2026-08-17T19:06:41.482Z'
+ created_at: '2026-08-18T15:03:18.609Z'
+ updated_at: '2026-08-18T15:03:18.628Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -30805,8 +30807,8 @@ paths:
suspension_reason: Counterfeit goods
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.574Z'
- updated_at: '2026-08-17T19:06:41.595Z'
+ created_at: '2026-08-18T15:03:18.664Z'
+ updated_at: '2026-08-18T15:03:18.684Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -30898,8 +30900,8 @@ paths:
rejection_reason: Incomplete paperwork
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-17T19:06:41.607Z'
- updated_at: '2026-08-17T19:06:41.627Z'
+ created_at: '2026-08-18T15:03:18.697Z'
+ updated_at: '2026-08-18T15:03:18.717Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -34199,6 +34201,18 @@ components:
external_video_url:
type: string
nullable: true
+ video_provider:
+ type: string
+ nullable: true
+ video_embed_url:
+ type: string
+ nullable: true
+ video_url:
+ type: string
+ nullable: true
+ poster_url:
+ type: string
+ nullable: true
original_url:
type: string
nullable: true
@@ -34243,6 +34257,10 @@ components:
- focal_point_x
- focal_point_y
- external_video_url
+ - video_provider
+ - video_embed_url
+ - video_url
+ - poster_url
- original_url
- mini_url
- small_url
@@ -35148,6 +35166,9 @@ components:
nullable: true
default_variant_id:
type: string
+ buy_box_variant_id:
+ type: string
+ nullable: true
thumbnail_url:
type: string
nullable: true
@@ -35257,6 +35278,7 @@ components:
- description
- description_html
- default_variant_id
+ - buy_box_variant_id
- thumbnail_url
- tags
- price
@@ -36756,15 +36778,9 @@ components:
nullable: true
product_name:
type: string
- seller_name:
- type: string
- nullable: true
delivery_profile_id:
type: string
nullable: true
- own_delivery_profile_id:
- type: string
- nullable: true
prices:
type: array
items:
@@ -36814,9 +36830,7 @@ components:
- reserved_quantity
- total_on_hand
- product_name
- - seller_name
- delivery_profile_id
- - own_delivery_profile_id
x-typelizer: true
WebhookDelivery:
type: object
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 6534d68732..34f3ca8784 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -87,16 +87,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImM4ZDU0NzNhLTJmNDctNDUwZi1iMDhjLTg2MzBlZGYwOTE0NyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2OTk3MjA0fQ.xGbdxPNNCwLKaJWVAkGfKc3_CgDlKQP04oFw3ymjyrY
- refresh_token: 12QaW2dN4i9KkCQZ7fwrMnYS
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6Ijc2YWUzNjljLTE4ZWItNGU2Zi1hMGQ2LWRmYjI4YjhjMGEwOCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg3MDY5MDAxfQ.ZxaYF5PmiyYbLyg9mlK88vDHhxts1thSlu6TaLSig_k
+ refresh_token: swZQcoAQRVXkquGc65YgzE3R
user:
id: cust_UkLWZg9DAJ
- first_name: Mario
- last_name: McGlynn
+ first_name: Sindy
+ last_name: Green
phone:
accepts_email_marketing: false
- full_name: Mario McGlynn
+ full_name: Sindy Green
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -194,16 +194,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjM5ZjViNmZhLTMzNjctNDA2OS1hODMxLWJiZTg0YWRiZjI5NiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2OTk3MjA0fQ.tzVWCeeAlM9VCNI_tL2FQh_qY188KwC0Yu1AsDFZBNo
- refresh_token: 5msRfdLVotVLu2cctGJwyUWq
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6ImIxYWE3ZTdiLTc0ZTgtNDhjNi05MWRlLWE4Mjg0MDYwMTU5MCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg3MDY5MDAxfQ.-aY0KilcWVsDWs0RGjttuCCR9iyQ4Eq5MP5JLu9zhdY
+ refresh_token: VP7XCP1NsY5NCvmqJtbouh5j
user:
id: cust_UkLWZg9DAJ
- first_name: Elouise
- last_name: Wilkinson
+ first_name: Marjorie
+ last_name: Gislason
phone:
accepts_email_marketing: false
- full_name: Elouise Wilkinson
+ full_name: Marjorie Gislason
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -393,16 +393,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjE4ZmNmNDk5LTBkMTItNDY4OC1iYzQ2LWU1NzcyY2IxMDliYiIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2OTk3MjA4fQ.qAmOhonVqOxFSJKvOFqPGRwyAF7KfMCUg_xVe8EAOKY
- refresh_token: XnQf2Vvz7pKDqN3WQuS9e5zA
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjRlMmZmMGFlLTQ5YzEtNDc0NS05ODc5LTU1NWQyZjExNTBjNSIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg3MDY5MDA0fQ.CHi3J4_CnnNSrfpDSWIZlBNqnM5yIuaSr3bbvtAc8RI
+ refresh_token: jf1yYNAYufGWVxSQtGrCv2gq
user:
id: cust_UkLWZg9DAJ
- first_name: Eleonore
- last_name: Schumm
+ first_name: Pat
+ last_name: Hills
phone:
accepts_email_marketing: false
- full_name: Eleonore Schumm
+ full_name: Pat Hills
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses: []
@@ -879,8 +879,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1387824
- slug: product-1387824
+ name: Product 1387867
+ slug: product-1387867
meta_title:
meta_description:
meta_keywords:
@@ -892,23 +892,22 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Blanditiis maxime adipisci debitis quo totam itaque.
- Doloribus earum odio distinctio temporibus dolores. Provident
- ipsam eum temporibus doloremque reprehenderit quod culpa tempore.
- Tempore cumque magnam ea modi ab. Minus adipisci impedit quaerat
- perspiciatis iure nulla. Cum rerum nihil consequuntur non pariatur
- tenetur. Ullam molestiae asperiores animi iste. Sed eum rerum
- vel veniam quae at. Repellendus excepturi est molestias non aliquam
- a repudiandae dolore. Velit eius fuga recusandae ad aliquam molestiae
- aspernatur nesciunt. Aut doloribus quam praesentium saepe cumque
- quos. Harum asperiores nostrum voluptatem quasi natus totam nisi
- ut. In porro similique amet nam. Eveniet iure non neque magni
- et reiciendis.
+ description: Ipsum et dolor modi consectetur exercitationem molestias.
+ Facere enim unde voluptas ab. Veritatis rem ad debitis amet. Excepturi
+ architecto deleniti eligendi sequi iste cumque. Velit occaecati
+ commodi neque sit. Harum debitis ea perspiciatis deserunt sit
+ necessitatibus. Praesentium cumque soluta molestias aspernatur
+ suscipit sed. Iure consectetur nulla dignissimos enim sunt. Suscipit
+ quas recusandae harum repudiandae assumenda hic. Corrupti iusto
+ sint dicta tempore nesciunt. Repellat quam eius perferendis recusandae.
+ Tenetur nostrum odit deleniti et. Sunt nisi similique cupiditate
+ reiciendis dolores minima.
description_html: |-
- Blanditiis maxime adipisci debitis quo totam itaque. Doloribus earum odio distinctio temporibus dolores. Provident ipsam eum temporibus doloremque reprehenderit quod culpa tempore. Tempore cumque magnam ea modi ab. Minus adipisci impedit quaerat perspiciatis iure nulla.
- Cum rerum nihil consequuntur non pariatur tenetur. Ullam molestiae asperiores animi iste. Sed eum rerum vel veniam quae at. Repellendus excepturi est molestias non aliquam a repudiandae dolore. Velit eius fuga recusandae ad aliquam molestiae aspernatur nesciunt.
- Aut doloribus quam praesentium saepe cumque quos. Harum asperiores nostrum voluptatem quasi natus totam nisi ut. In porro similique amet nam. Eveniet iure non neque magni et reiciendis.
+ Ipsum et dolor modi consectetur exercitationem molestias. Facere enim unde voluptas ab. Veritatis rem ad debitis amet. Excepturi architecto deleniti eligendi sequi iste cumque.
+ Velit occaecati commodi neque sit. Harum debitis ea perspiciatis deserunt sit necessitatibus. Praesentium cumque soluta molestias aspernatur suscipit sed. Iure consectetur nulla dignissimos enim sunt.
+ Suscipit quas recusandae harum repudiandae assumenda hic. Corrupti iusto sint dicta tempore nesciunt. Repellat quam eius perferendis recusandae. Tenetur nostrum odit deleniti et. Sunt nisi similique cupiditate reiciendis dolores minima.
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -1063,8 +1062,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 1834432
- slug: product-1834432
+ name: Product 1833465
+ slug: product-1833465
meta_title:
meta_description:
meta_keywords:
@@ -1079,6 +1078,7 @@ paths:
description: A comfortable cotton t-shirt.
description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -1094,8 +1094,8 @@ paths:
original_price:
seller_id:
- id: prod_gbHJdmfrXB
- name: Product 1847968
- slug: product-1847968
+ name: Product 1847805
+ slug: product-1847805
meta_title:
meta_description:
meta_keywords:
@@ -1107,22 +1107,19 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Fugiat nostrum assumenda commodi saepe itaque ducimus
- fugit. Odit et voluptate eum eos. Voluptatum id iusto sed ipsa.
- Consequuntur laborum ab dolore veritatis eveniet voluptate quis
- maxime. Nesciunt suscipit dignissimos consequuntur ea provident
- praesentium ipsa cumque. Facere rem aperiam corrupti corporis.
- Repellendus id aut ea illum officiis omnis. Commodi ut ex consequuntur
- quos minus. Deleniti soluta illum facilis provident ut. Reiciendis
- aliquam ipsam incidunt molestias natus. Consectetur architecto
- minus provident dignissimos enim. Vitae dolorem voluptatibus et
- nihil laudantium. Culpa dicta doloribus sequi cupiditate numquam
- est dolores neque.
+ description: Ipsam eius aliquid porro fugiat eaque nesciunt officia.
+ Sapiente quo et temporibus voluptatibus. Earum in cupiditate at
+ iure. Laboriosam earum laborum sint assumenda iure eveniet facere
+ est. Iusto distinctio corrupti tempora possimus saepe molestiae.
+ Non beatae eligendi illum voluptates ipsa necessitatibus. Ut laboriosam
+ autem dolorum eum. Excepturi reprehenderit officiis facere voluptates.
+ Impedit optio ut accusamus nemo sit ducimus. Quam inventore similique
+ sit accusamus ducimus magnam.
description_html: |-
- Fugiat nostrum assumenda commodi saepe itaque ducimus fugit. Odit et voluptate eum eos. Voluptatum id iusto sed ipsa. Consequuntur laborum ab dolore veritatis eveniet voluptate quis maxime. Nesciunt suscipit dignissimos consequuntur ea provident praesentium ipsa cumque.
- Facere rem aperiam corrupti corporis. Repellendus id aut ea illum officiis omnis. Commodi ut ex consequuntur quos minus. Deleniti soluta illum facilis provident ut.
- Reiciendis aliquam ipsam incidunt molestias natus. Consectetur architecto minus provident dignissimos enim. Vitae dolorem voluptatibus et nihil laudantium. Culpa dicta doloribus sequi cupiditate numquam est dolores neque.
+ Ipsam eius aliquid porro fugiat eaque nesciunt officia. Sapiente quo et temporibus voluptatibus. Earum in cupiditate at iure. Laboriosam earum laborum sint assumenda iure eveniet facere est. Iusto distinctio corrupti tempora possimus saepe molestiae.
+ Non beatae eligendi illum voluptates ipsa necessitatibus. Ut laboriosam autem dolorum eum. Excepturi reprehenderit officiis facere voluptates. Impedit optio ut accusamus nemo sit ducimus. Quam inventore similique sit accusamus ducimus magnam.
default_variant_id: variant_EfhxLZ9ck8
+ buy_box_variant_id: variant_EfhxLZ9ck8
thumbnail_url:
tags: []
price:
@@ -1226,8 +1223,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 2112842
- slug: product-2112842
+ name: Product 2114704
+ slug: product-2114704
meta_title:
meta_description:
meta_keywords:
@@ -1242,6 +1239,7 @@ paths:
description: A comfortable cotton t-shirt.
description_html: "<p>A <strong>comfortable</strong> cotton t-shirt.</p>"
default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
price:
@@ -1262,7 +1260,7 @@ paths:
amount_in_cents: 999
currency: USD
display_amount: "$9.99"
- recorded_at: '2026-08-02T19:06:57Z'
+ recorded_at: '2026-08-03T15:03:33Z'
schema:
"$ref": "#/components/schemas/Product"
'404':
@@ -1512,7 +1510,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_gbHJdmfrXB
- token: arUk3SyiB7We4zTj4r2gVjXC
+ token: 9dTzwh6HZzDztPTwKTxhtBp4
email:
customer_note:
currency: USD
@@ -1575,8 +1573,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 113605
- slug: product-113605
+ name: Product 1135553
+ slug: product-1135553
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1621,7 +1619,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: CLTDB4CNki7K6ks3KTVkutq8
+ token: FqNcN9K64rzMu2wpYV3QmgfZ
email:
customer_note:
currency: USD
@@ -1684,8 +1682,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1123744
- slug: product-1123744
+ name: Product 1122467
+ slug: product-1122467
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -1803,7 +1801,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: j5vMixNHMRd2tAnYKjtXU1t1
+ token: rtwf31sfbdRoA9AHziKfEksH
email:
customer_note:
currency: USD
@@ -1971,7 +1969,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: a9bBxBZFm19ZrJqSXLaPgtR8
+ token: FjY3xR5oKWuBKqr5L5ffNMPB
email:
customer_note:
currency: USD
@@ -1979,7 +1977,7 @@ paths:
total_quantity: 0
warnings:
- code: line_item_removed
- message: Product 1171899 was removed because it was sold out
+ message: Product 117567 was removed because it was sold out
line_item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
coupon_code:
@@ -2128,7 +2126,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: CcVjyHv7szeRnFLJXrZEJR7M
+ token: gy3xE9RoG7SVRGskCK7x1ygT
email:
customer_note: Leave at door
currency: USD
@@ -2187,8 +2185,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1189284
- slug: product-1189284
+ name: Product 1182541
+ slug: product-1182541
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2407,8 +2405,8 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: HV1SriTk1Dkq6bUw3wWb5tzA
+ token: wRx3dLUQapZ1gJxZ7Xo53eKk
customer_note:
currency: USD
locale: en
@@ -2463,8 +2461,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1209411
- slug: product-1209411
+ name: Product 1207985
+ slug: product-1207985
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2623,7 +2621,7 @@ paths:
cart_id: cart_UkLWZg9DAJ
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -2631,7 +2629,7 @@ paths:
coupon_code:
fulfillment_status: backorder
payment_status: paid
- completed_at: '2026-08-17T19:06:46.255Z'
+ completed_at: '2026-08-18T15:03:22.668Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -2667,8 +2665,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 123368
- slug: product-123368
+ name: Product 1238532
+ slug: product-1238532
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -2733,7 +2731,7 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Emelia Adams
+ name: Kristi Weber
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -2773,7 +2771,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-c4d882934be3
+ response_code: BGS-04156545f852
number: R1001-P1
amount: '20.0'
display_amount: "$20.00"
@@ -2934,7 +2932,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: CHLXmoh6g338T62aV3YAnv8d
+ token: 1q6Y6V1nYv9APQoq8HhqHqG4
email:
customer_note:
currency: USD
@@ -2996,8 +2994,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 149904
- slug: product-149904
+ name: Product 1497910
+ slug: product-1497910
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3126,7 +3124,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: bW4FyucJRJuxPB25146pboBz
+ token: tU1nc8PRqhzsLcWbeMXYtRcP
email:
customer_note:
currency: USD
@@ -3185,8 +3183,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1519696
- slug: product-1519696
+ name: Product 1519608
+ slug: product-1519608
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3304,8 +3302,8 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: TThXsSH9ibH3VvvKFoGRB3CZ
+ token: roHGKq9x27SCL4vfnXySdBJ8
customer_note:
currency: USD
locale: en
@@ -3357,8 +3355,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1532925
- slug: product-1532925
+ name: Product 1538264
+ slug: product-1538264
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3423,7 +3421,7 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Denyse Baumbach
+ name: Ashely Heller
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -3588,7 +3586,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: ABRd7xCxd314dsH3c9TcUa99
+ token: rYbi9P3CkptNZ8iQEVuJ6dYY
email:
customer_note:
currency: USD
@@ -3643,8 +3641,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1553749
- slug: product-1553749
+ name: Product 1559542
+ slug: product-1559542
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3671,7 +3669,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260817190651111733
+ response_code: 1-SC-20260818150327212479
number: cart_UkLWZg9DAJ-P1
amount: '10.0'
display_amount: "$10.00"
@@ -3828,7 +3826,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: xBtsULtfVAnmYT8qxEefJagK
+ token: 4Yc5iH2bLFix7sACjP7Ldfuf
email:
customer_note:
currency: USD
@@ -3887,8 +3885,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1597283
- slug: product-1597283
+ name: Product 1593880
+ slug: product-1593880
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -3915,7 +3913,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260817190651509644
+ response_code: 1-SC-20260818150327590678
number: cart_UkLWZg9DAJ-P1
amount: '10.0'
display_amount: "$10.00"
@@ -4023,7 +4021,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: b3KybEd9YRGCSpeJd2XFvHoS
+ token: Cg66WegyJr5HBsEx2M9gGhJh
email:
customer_note:
currency: USD
@@ -4031,10 +4029,10 @@ paths:
total_quantity: 2
warnings:
- code: delivery_unavailable
- message: Product 1625480 cannot be delivered to the selected address
+ message: Product 162711 cannot be delivered to the selected address
line_item_id: li_UkLWZg9DAJ
- code: delivery_unavailable
- message: Product 1637496 cannot be delivered to the selected address
+ message: Product 1632295 cannot be delivered to the selected address
line_item_id: li_gbHJdmfrXB
coupon_code:
item_total: '29.99'
@@ -4088,8 +4086,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1625480
- slug: product-1625480
+ name: Product 162711
+ slug: product-162711
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4119,8 +4117,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1637496
- slug: product-1637496
+ name: Product 1632295
+ slug: product-1632295
options_text: ''
price: '19.99'
display_price: "$19.99"
@@ -4271,7 +4269,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: 97z3JX8tM3Mjg9j77wPmPXRv
+ token: yZnKTTMYidvy7TaDUe1sFgdE
email:
customer_note:
currency: USD
@@ -4334,8 +4332,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 169919
- slug: product-169919
+ name: Product 1696440
+ slug: product-1696440
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -4453,7 +4451,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: CppPkerbgSnVMFMbrutaRno1
+ token: uZeUGKba8Deo1MrrWaLuUAVD
email:
customer_note:
currency: USD
@@ -4596,9 +4594,9 @@ paths:
id: ps_gbHJdmfrXB
status: pending
currency: USD
- external_id: bogus_a8e6f4d061f9fea18f1e7aa0
+ external_id: bogus_5b2dc43fd84116a810ffe0b3
external_data:
- client_secret: bogus_secret_9ec9d4f49038b17f
+ client_secret: bogus_secret_1b6eeeb29bc5fa88
customer_external_id:
expires_at:
amount: '10.0'
@@ -4697,7 +4695,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_605adfedadf20d2fb6951c87
+ external_id: bogus_65e1ba7d90381e5522c3aa73
external_data:
client_secret: secret_123
customer_external_id:
@@ -4760,7 +4758,7 @@ paths:
id: ps_UkLWZg9DAJ
status: pending
currency: USD
- external_id: bogus_beec26a6085f0bd1ccc1671b
+ external_id: bogus_bfe91694e7da1354c5fb005d
external_data:
client_secret: secret_123
customer_external_id:
@@ -4863,7 +4861,7 @@ paths:
id: ps_UkLWZg9DAJ
status: completed
currency: USD
- external_id: bogus_c3767cd2a51832c24341fbf8
+ external_id: bogus_b9bf67d0e8fe3905aa4d08f8
external_data:
client_secret: secret_123
customer_external_id:
@@ -5071,7 +5069,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: Ee7RdPvD4BqXKKcpDb7eWwDp
+ token: eCCGUudw9nHVj6vANkexThsh
email:
customer_note:
currency: USD
@@ -5126,8 +5124,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2316541
- slug: product-2316541
+ name: Product 2315940
+ slug: product-2315940
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5154,7 +5152,7 @@ paths:
payments:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: 1-SC-20260817190659173846
+ response_code: 1-SC-20260818150335310492
number: cart_UkLWZg9DAJ-P1
amount: '10.0'
display_amount: "$10.00"
@@ -5275,7 +5273,7 @@ paths:
channel_id: ch_UkLWZg9DAJ
preferred_stock_location_id:
number: cart_UkLWZg9DAJ
- token: zXpkVRe2Ht5eDYmSLqsVfDiu
+ token: 6L5gYYqz4tYmTDS5GPRPyC9B
email:
customer_note:
currency: USD
@@ -5334,8 +5332,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 2337495
- slug: product-2337495
+ name: Product 233291
+ slug: product-233291
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5459,7 +5457,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-17T19:06:54.371Z'
+ completed_at: '2026-08-18T15:03:29.937Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -5495,8 +5493,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1731953
- slug: product-1731953
+ name: Product 1739295
+ slug: product-1739295
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -5561,7 +5559,7 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Devin Hand
+ name: Kip Will
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6541,7 +6539,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -6549,7 +6547,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-17T19:06:48.882Z'
+ completed_at: '2026-08-18T15:03:25.170Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -6585,8 +6583,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1395610
- slug: product-1395610
+ name: Product 1397779
+ slug: product-1397779
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6651,7 +6649,7 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Edna Bernhard
+ name: Zita Donnelly
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -6841,7 +6839,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -6849,7 +6847,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-17T19:06:49.124Z'
+ completed_at: '2026-08-18T15:03:25.389Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -6885,8 +6883,8 @@ paths:
preorder_ships_at:
quantity: 1
currency: USD
- name: Product 1418584
- slug: product-1418584
+ name: Product 1412973
+ slug: product-1412973
options_text: ''
price: '10.0'
display_price: "$10.00"
@@ -6951,7 +6949,7 @@ paths:
pickup_point: false
stock_location:
id: sloc_UkLWZg9DAJ
- name: Natalie Upton
+ name: Juliane O'Reilly
address1: 1600 Pennsylvania Ave NW
city: Washington
zipcode: '20500'
@@ -7096,8 +7094,8 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjhiNDlmZmE0LTJhYTUtNDg5MS05OTg5LTcyODY4YzZhMjBjOCIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg2OTk3MjA5fQ.nu3pil0P7ibfh0nTsAcAYTAY7NviA0AOzd4jL129aNE
- refresh_token: W1DFrUS2nrxgjPs6M2GC4YYD
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJjdXN0b21lciIsImp0aSI6IjJjZTgxM2EzLWYzZWUtNGIxOS1hMWJmLWQwMzllNzg5ODEzYyIsImlzcyI6InNwcmVlIiwiYXVkIjoic3RvcmVfYXBpIiwiZXhwIjoxNzg3MDY5MDA1fQ.Ibv2D5PcS1QGCRgvaR6rYg2rMKcZ-JCcfdcJtvMwkEg
+ refresh_token: 4H11fbCTGuMs7pWGPovYwB6k
user:
id: cust_UkLWZg9DAJ
@@ -7114,10 +7112,10 @@ paths:
newsletter_subscriber:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:49.320Z'
- updated_at: '2026-08-17T19:06:49.321Z'
+ created_at: '2026-08-18T15:03:25.577Z'
+ updated_at: '2026-08-18T15:03:25.578Z'
verified: true
- verified_at: '2026-08-17T19:06:49Z'
+ verified_at: '2026-08-18T15:03:25Z'
customer_id: cust_UkLWZg9DAJ
customer_groups: []
schema:
@@ -7220,12 +7218,12 @@ paths:
application/json:
example:
id: cust_UkLWZg9DAJ
- first_name: Toshia
- last_name: Brown
+ first_name: Conrad
+ last_name: Bartell
phone: 555-555-0199
accepts_email_marketing: false
- full_name: Toshia Brown
+ full_name: Conrad Bartell
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
addresses:
@@ -7369,7 +7367,7 @@ paths:
application/json:
example:
id: cust_UkLWZg9DAJ
first_name: Updated
last_name: Name
phone: 555-555-0199
@@ -7568,7 +7566,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: DBC92D192F7B0415
+ code: 4424E04438FF1448
status: active
currency: USD
amount: '10.0'
@@ -7664,7 +7662,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: F7722C113BE7D995
+ code: B56F9F5AC45CDE96
status: active
currency: USD
amount: '10.0'
@@ -7736,8 +7734,8 @@ paths:
example:
id: pss_gbHJdmfrXB
status: pending
- external_id: bogus_seti_c9fbc791d7e1234595d8b9e2
- external_client_secret: bogus_seti_secret_7237c1a86790436a
+ external_id: bogus_seti_03678fb5a715e0e69c2f688a
+ external_client_secret: bogus_seti_secret_0218b618c8e91ae6
external_data: {}
payment_method_id: pm_UkLWZg9DAJ
payment_source_id:
@@ -7836,8 +7834,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: pending
- external_id: seti_test_b7c12f05dc65bd1cc8db4d9f
- external_client_secret: seti_secret_af804d7ec3f49d8617723326
+ external_id: seti_test_bc312094cd08be1004f24067
+ external_client_secret: seti_secret_b8a6d4547a6abc8ccf1fe762
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -7913,8 +7911,8 @@ paths:
example:
id: pss_UkLWZg9DAJ
status: completed
- external_id: seti_test_7778942daebd30d71bf9ba37
- external_client_secret: seti_secret_4f2b7ab24ca66cb26f4a24e7
+ external_id: seti_test_a63ee8376e4132e05157a7b6
+ external_client_secret: seti_secret_3e077e50baf37023568ceae8
external_data:
client_secret: secret_123
payment_method_id: pm_UkLWZg9DAJ
@@ -8858,7 +8856,7 @@ paths:
data:
- id: wl_UkLWZg9DAJ
name: My Wishlist
- token: EjS2snpxcwEASbBX2r5vtX92
+ token: VfDEX7zzGP5m1FFd5pJLUt3C
is_default: false
is_private: true
meta:
@@ -8934,7 +8932,7 @@ paths:
example:
id: wl_gbHJdmfrXB
name: Birthday Ideas
- token: b8kHu4MymLiDrNDj3VkMB25n
+ token: 4eKuMQpSub8RqdSqzR6FjnfC
is_default: false
is_private: true
schema:
@@ -9035,7 +9033,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: My Wishlist
- token: 7qgCr4QTvfctpaVSSBiyQQHf
+ token: nUuXTbb5hAjPiR4aanBvo2S6
is_default: false
is_private: true
schema:
@@ -9097,7 +9095,7 @@ paths:
example:
id: wl_UkLWZg9DAJ
name: Updated Name
- token: 65SmXagY9xZaCqfbSmcBcc3W
+ token: UX7VmsHFuZStBFt2AF1QPXnD
is_default: false
is_private: true
schema:
@@ -9380,11 +9378,11 @@ paths:
application/json:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:53.406Z'
- updated_at: '2026-08-17T19:06:53.407Z'
+ created_at: '2026-08-18T15:03:29.219Z'
+ updated_at: '2026-08-18T15:03:29.220Z'
verified: true
- verified_at: '2026-08-17T19:06:53Z'
+ verified_at: '2026-08-18T15:03:29Z'
customer_id: cust_UkLWZg9DAJ
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9463,10 +9461,10 @@ paths:
example:
id: sub_UkLWZg9DAJ
- created_at: '2026-08-17T19:06:53.440Z'
- updated_at: '2026-08-17T19:06:53.447Z'
+ created_at: '2026-08-18T15:03:29.244Z'
+ updated_at: '2026-08-18T15:03:29.250Z'
verified: true
- verified_at: '2026-08-17T19:06:53Z'
+ verified_at: '2026-08-18T15:03:29Z'
customer_id:
schema:
"$ref": "#/components/schemas/NewsletterSubscriber"
@@ -9636,7 +9634,7 @@ paths:
body_html: ''
- id: pol_OIJLhNcSbf
name: Privacy Policy
- slug: privacy-policy-3d08cad4-ef36-474b-9474-7e4e5bc892e6
+ slug: privacy-policy-afcebbaf-db81-4ec2-a0b7-6b725ce48ebb
body: We respect your privacy.
body_html: We respect your privacy.
- id: pol_uw2YK1rnl0
@@ -11994,6 +11992,37 @@ components:
- country_codes
- supported_locales
x-typelizer: true
+ MediaEvent:
+ type: object
+ properties:
+ id:
+ type: string
+ viewable_id:
+ type: string
+ viewable_type:
+ type: string
+ media_type:
+ type: string
+ position:
+ type: number
+ nullable: true
+ alt:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ required:
+ - id
+ - viewable_id
+ - viewable_type
+ - media_type
+ - position
+ - alt
+ - created_at
+ - updated_at
+ x-typelizer: true
Media:
type: object
properties:
@@ -12022,6 +12051,18 @@ components:
external_video_url:
type: string
nullable: true
+ video_provider:
+ type: string
+ nullable: true
+ video_embed_url:
+ type: string
+ nullable: true
+ video_url:
+ type: string
+ nullable: true
+ poster_url:
+ type: string
+ nullable: true
original_url:
type: string
nullable: true
@@ -12053,6 +12094,10 @@ components:
- focal_point_x
- focal_point_y
- external_video_url
+ - video_provider
+ - video_embed_url
+ - video_url
+ - poster_url
- original_url
- mini_url
- small_url
@@ -12847,6 +12892,9 @@ components:
nullable: true
default_variant_id:
type: string
+ buy_box_variant_id:
+ type: string
+ nullable: true
thumbnail_url:
type: string
nullable: true
@@ -12915,6 +12963,7 @@ components:
- description
- description_html
- default_variant_id
+ - buy_box_variant_id
- thumbnail_url
- tags
- price
diff --git a/docs/developer/core-concepts/media.mdx b/docs/developer/core-concepts/media.mdx
index 9380d3f6aa..2a8637f6ca 100644
--- a/docs/developer/core-concepts/media.mdx
+++ b/docs/developer/core-concepts/media.mdx
@@ -1,7 +1,7 @@
---
title: Media
sidebarTitle: "Media"
-description: Manage product media in Spree — images, videos, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
+description: Manage product media in Spree — images, hosted and external video, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
---
import { Since } from '/snippets/since.mdx';
@@ -114,6 +114,103 @@ The Store API's `media` field on a product returns its gallery — product-level
This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](/developer/upgrades/5.4-to-5.5) to re-home legacy variant-pinned data when convenient.
+### Video <Since version="6.0" />
+
+A product gallery can hold video as well as images. Spree supports both ways merchants usually have it:
+
+| `media_type` | What it is | What it needs |
+|---|---|---|
+| `video` | A video file you upload, served from your own storage | An uploaded file (MP4, WebM, or QuickTime) |
+| `external_video` | A YouTube or Vimeo link | The link, in `external_video_url` |
+
+Spree reads the link once, when it is saved, and rejects anything it cannot embed — so a broken URL is caught at the point a merchant enters it rather than in the storefront. What it derives comes back on the media object:
+
+| Field | Description |
+|---|---|
+| `video_provider` | `youtube` or `vimeo` |
+| `video_embed_url` | Player URL, ready for an `iframe` |
+| `video_url` | The uploaded file itself, for hosted video |
+| `poster_url` | A still frame for the video |
+
+Because the derived fields are on the response, a storefront embeds a video without parsing links itself.
+
+#### Adding an external video
+
+<CodeGroup>
+
+```typescript Admin SDK
+const video = await client.products.media.create('prod_86Rf07xd4z', {
+ media_type: 'external_video',
+ external_video_url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+ alt: 'How it is made',
+})
+
+video.video_embed_url // https://www.youtube.com/embed/dQw4w9WgXcQ
+```
+
+```bash cURL
+curl -X POST 'https://api.mystore.com/api/v3/admin/products/prod_86Rf07xd4z/media' \
+ -H 'X-Spree-API-Key: sk_xxx' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "media_type": "external_video",
+ "external_video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+ "alt": "How it is made"
+ }'
+```
+
+</CodeGroup>
+
+#### Uploading a video file
+
+A hosted video is uploaded the same way an image is, with `media_type` telling Spree what it is. Add `poster_signed_id` to give it a still frame:
+
+```typescript Admin SDK
+const video = await client.products.media.create('prod_86Rf07xd4z', {
+ media_type: 'video',
+ signed_id: signedVideoBlobId,
+ poster_signed_id: signedPosterBlobId,
+ alt: 'Product in use',
+})
+```
+
+A poster can also be added or replaced later, on its own:
+
+```typescript Admin SDK
+await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
+ poster_signed_id: signedPosterBlobId,
+})
+```
+
+<Info>
+Spree serves an uploaded video as you uploaded it — it does not transcode. Keep files web-friendly (H.264 MP4 or WebM) so they play everywhere, and prefer an external video for long footage so the provider handles streaming.
+</Info>
+
+#### Posters
+
+A video has no image of its own, so its sized URLs (`small_url`, `large_url`, and the rest) resolve to its **poster** — the still shown before the video plays. A gallery that only knows how to draw an image still renders the right picture, and can play the video when the shopper asks for it.
+
+Where the poster comes from, in order:
+
+1. **The one the merchant uploaded** — `poster_signed_id` on write, editable in the dashboard's media editor.
+2. **The provider's own still**, for a YouTube link.
+3. **Nothing**, for a Vimeo link or an uploaded file with no poster — the tile falls back to a placeholder.
+
+Spree does not extract a frame from an uploaded video, so give hosted video and Vimeo links a poster if you want them to show a still.
+
+### Focal Point <Since version="6.0" />
+
+`focal_point_x` and `focal_point_y` mark the part of an image that must stay in frame when a storefront crops it to a different shape. Both are fractions between 0 and 1, measured from the top left, so `{ x: 0.5, y: 0.5 }` is dead centre — which is also what a storefront should assume when they are null.
+
+```typescript Admin SDK
+await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
+ focal_point_x: 0.25,
+ focal_point_y: 0.4,
+})
+```
+
+Spree stores the focal point and serves it; the cropping itself is the storefront's decision, since only it knows the shape it needs.
+
### Named Variant Sizes <Since version="5.3" />
When an image is uploaded, Spree automatically generates optimized versions in the background:
@@ -240,6 +337,10 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
| `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |
| `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |
| `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |
+| `video_provider` | string \| null | `youtube` or `vimeo`, derived from the link <Since version="6.0" /> |
+| `video_embed_url` | string \| null | Embeddable player URL, derived from the link <Since version="6.0" /> |
+| `video_url` | string \| null | Uploaded video file URL <Since version="6.0" /> |
+| `poster_url` | string \| null | Still frame for a video <Since version="6.0" /> |
| `original_url` | string \| null | Full-size image URL (inline disposition) |
| `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
| `download_url` | string \| null | Same blob as `original_url` but with `Content-Disposition: attachment`. Admin API only. <Since version="5.5" /> |
@@ -271,6 +372,7 @@ For production deployments, use cloud storage (S3, GCS, Azure) instead of local
- **Always provide alt text** for accessibility and SEO
- **Use named variant sizes** (`mini`, `small`, `medium`, `large`, `xlarge`) for optimal performance
- **Use a CDN** in production for faster delivery
+- **Give every video a poster** so a gallery has something to show before playback
## Related Documentation
diff --git a/docs/plans/5.4-6.0-product-media-system.md b/docs/plans/5.4-6.0-product-media-system.md
index b129996d28..0c83ee5658 100644
--- a/docs/plans/5.4-6.0-product-media-system.md
+++ b/docs/plans/5.4-6.0-product-media-system.md
@@ -1,10 +1,10 @@
# Product Media System
-**Status:** 5.5 data model shipped (PR #14000 — `spree_variant_media`, `media_type`, `focal_point_x/y`, `external_video_url`, column renames); admin UIs in progress; 6.0 cleanup pending
-**Target:** Spree 5.4 (foundation) + Spree 5.5 (data model + admin UIs ✓ data model) + Spree 6.0 (cleanup with master removal)
-**Depends on:** None
+**Status:** 5.4 + 5.5 shipped. 6.0 Phases 1–4 implemented 2026-08-18 — video support (hosted + external), focal point, the `Asset` → `Media` rename, and cleanup.
+**Target:** Spree 5.4 (foundation) + Spree 5.5 (data model + product gallery UI) + Spree 6.0 (video, rename, cleanup)
+**Depends on:** `6.0-remove-master-variant.md` (shipped — master is already gone, so the 6.0 re-homing phase below is inherited rather than owned)
**Author:** Damian + Claude
-**Last updated:** 2026-05-20
+**Last updated:** 2026-08-18
## Summary
@@ -17,25 +17,33 @@ This plan moves to a **product-level media gallery** (the industry standard) whe
1. **Rename `images` → `media`** throughout the Store API. Clean break — no deprecated alias.
2. **Drop `viewable_id`/`viewable_type`** from Store API. Admin API keeps them.
3. **Add `product_id`** to the media serializer.
-4. **Single `Spree::Asset` class** — `Spree::Image` logic merged into `Spree::Asset`. `Spree::Image` kept as thin subclass (sets `media_type: 'image'`). No STI.
+4. **One media class, no STI** — `Spree::Image` logic was merged into the single media class in 5.4. `Spree::Image` survived 5.4/5.5 as a thin subclass for backward compatibility and is removed in 6.0 (see decision 8).
5. **`media_type` defaults to `'image'`** — always present, never null.
6. **No dedicated Store media endpoint** — media is served via `expand=media` on products/variants (industry standard).
7. **VariantMedia join table lands in 5.5** — enables variants to reference product-level assets without duplicating blobs. Direct variant `images` association stays for backward compatibility. The join is internal plumbing, not an API surface: callers manage variant assignment via `PATCH /products/:id/media/:asset_id { variant_ids: [...] }` (the `Spree::Asset#variant_ids=` setter resolves prefixed IDs and enforces same-product). Named `VariantMedia` (table `spree_variant_media`) — matches the industry convention (Shopify, Vendure, BigCommerce all expose a `variant_media` or `productVariantMedia` join concept).
-8. **Rename `Spree::Asset` → `Spree::Media` in 6.0** — aligns model/table/prefix with API naming. Coincides with master removal cleanup.
-9. **Product is the default upload target in 5.5** — `POST /api/v3/admin/products/:id/media` and the legacy admin product form both attach to `Spree::Product` directly. Master-pinned images keep displaying via `gallery_media` until merchants opt into the migration rake (or 6.0 sweeps them up).
+8. **Rename `Spree::Asset` → `Spree::Media` in 6.0** — aligns model/table/prefix with API naming. `Spree::Asset` stays readable one release as a deprecated alias; `Spree::Image` goes.
+9. **Product is the default upload target** — `POST /api/v3/admin/products/:id/media` attaches to `Spree::Product` directly. Variant-pinned images keep displaying via `gallery_media` until merchants run the migration rake.
+10. **Both hosted and external video ship in 6.0** (2026-08-18). `video` means an uploaded file and requires an attachment; `external_video` means a YouTube or Vimeo link and requires a URL. The two are distinct `media_type` values, never one field doing both jobs.
+11. **Spree parses the video URL once, at the API boundary.** The serializer exposes the provider and an embeddable URL so every headless storefront doesn't re-implement YouTube and Vimeo link parsing. Spree stores what the merchant typed and derives the rest.
+12. **Hosted video carries a poster image.** A gallery that only knows how to draw an `<img>` still renders a sensible still, and the storefront chooses when to load the video itself.
+13. **`media_type` is the discriminator, never the STI `type` column.** `inheritance_column` is nil; any write path keying off `type` is a bug.
## Design Details
### Data Model
```
-Spree::Asset (single class, replaces Spree::Image)
- viewable_type: 'Spree::Product' (new) or 'Spree::Variant' (legacy)
+Spree::Media (6.0 rename of Spree::Asset; Spree::Image removed)
+ viewable_type: 'Spree::Product' (default) or 'Spree::Variant' (legacy)
media_type: 'image' | 'video' | 'external_video' (default: 'image')
focal_point_x, focal_point_y (decimal, nullable)
external_video_url (string, nullable)
-Spree::Image < Spree::Asset (thin backward-compat subclass)
+ image → attachment required (image content types), no URL
+ video → attachment required (video content types), no URL,
+ poster image derived for gallery display
+ external_video → external_video_url required, no attachment;
+ provider + embed URL derived at the API boundary
Spree::Product
has_many :media, as: :viewable ← product-level gallery
@@ -66,9 +74,13 @@ Spree::VariantMedia (5.5, table: spree_variant_media)
| `alt` | string \| null | Alt text |
| `focal_point_x` | number \| null | 0.0–1.0 |
| `focal_point_y` | number \| null | 0.0–1.0 |
-| `external_video_url` | string \| null | YouTube/Vimeo URL |
-| `original_url` | string \| null | Full-size image URL |
-| `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
+| `external_video_url` | string \| null | YouTube/Vimeo URL as the merchant entered it |
+| `video_provider` | string \| null | `'youtube'`, `'vimeo'` — derived, 6.0 |
+| `video_embed_url` | string \| null | Embeddable player URL — derived, 6.0 |
+| `video_url` | string \| null | Hosted video file URL — 6.0 |
+| `poster_url` | string \| null | Still frame for a video tile — 6.0 |
+| `original_url` | string \| null | Full-size image URL (null on video) |
+| `mini_url` ... `xlarge_url` | string \| null | Named variant URLs (null on external video) |
**Removed** from Store API: `viewable_id`, `viewable_type`
**Admin API** extends Store with: `viewable_id`, `viewable_type`
@@ -97,79 +109,80 @@ Spree::VariantMedia (5.5, table: spree_variant_media)
- TypeScript types, Zod schemas, OpenAPI spec regenerated
- Docs updated throughout
-### 5.5 — TODO
+### 5.5 — SHIPPED ✓
-5.5 delivers the **data model, API, and both admin UIs** for product-level media as a parallel path. Variant-level media keeps working unchanged. The data-migration rake ships as **opt-in** so existing merchants choose when to re-home master-pinned images. Master removal stays in 6.0.
+5.5 delivered the data model, the API and the product gallery UI. Variant-level media keeps working unchanged. The data-migration rake shipped **opt-in** so existing merchants choose when to re-home variant-pinned images.
-**Why before master removal?** `Asset#viewable` is already polymorphic across `Spree::Variant` and `Spree::Product`. Both polymorphic targets coexist cleanly in 5.5 — old master-pinned assets keep displaying via `gallery_media`'s fallback, new uploads go to Product. 6.0 then re-homes the remaining master-pinned assets as part of master removal Phase 2.
+**Phase 1: VariantMedia join table — shipped**
+- `spree_variant_media` table + `Spree::VariantMedia` model, unique index on `[variant_id, media_id]`, no `position` column (order inherits from the asset's product-level position)
+- `Variant#variant_media`, `Variant#associated_media`, `Variant#gallery_media` preferring the join over direct `images`
+- `VariantMedia.resolve_variant_ids` is the security boundary — variants from another product are dropped
-**Phase 1: VariantMedia join table**
-- Create `spree_variant_media` table + `Spree::VariantMedia` model
-- `Variant#variant_media`, `Variant#associated_media` associations
-- Update `Variant#gallery_media` to prefer `associated_media` (join table) over direct `images`, falling back to `images` when the join is empty
-- Unique index on `[variant_id, media_id]`. No per-variant ordering — gallery order is inherited from the asset's product-level `position` so merchants reorder once on the product gallery and every variant follows.
+**Phase 2: Admin API — Product is the default parent — shipped**
+- `POST /api/v3/admin/products/:product_id/media` defaults to `viewable_type: 'Spree::Product'`; the `variant_id` path still creates variant-pinned assets
+- Variant assignment travels as `variant_ids` on the media endpoint — no dedicated link/unlink routes
+- Product-scoped listings union product-level assets with any still pinned to the default variant, so legacy data keeps rendering
+- Inline `media: [...]` on the product PATCH upserts by `id` and creates from `signed_id`
-**Phase 2: Admin API — Product is the default parent**
-- `POST /api/v3/admin/products/:product_id/media` defaults to `viewable_type: 'Spree::Product'` (was master variant). Existing `?variant_id=...` path keeps creating `viewable_type: 'Spree::Variant'`
-- New endpoints for variant↔product-asset linking:
- - Variant assignment travels on the existing media endpoint as a `variant_ids` array — no dedicated link/unlink routes:
- - `PATCH /api/v3/admin/products/:product_id/media/:asset_id { variant_ids: ["variant_xyz", ...] }`
- - The `Spree::Asset#variant_ids=` setter resolves prefixed IDs to internal IDs scoped to the asset's product (anything else is silently dropped) and uses Rails' `has_many :through` setter under the hood. Empty array clears all links; omitting the field leaves them untouched.
-- `Asset#should_touch_product_variants?` gains a `Spree::Product` branch so reordering product-level media still busts variant cache keys
-- Per the [admin-sdk-unreleased policy](../../memory/feedback-admin-sdk-unreleased.md), this ships as a clean break — no deprecation alias for the master-default behavior
+**Phase 3: Legacy Rails admin — dropped, not shipped**
+The `spree/admin` engine was removed from the monorepo entirely (commit `464df815f2`). There is no legacy admin form to retarget, so this phase no longer exists.
-**Phase 3: Legacy Rails admin — flip product upload to Product-typed**
-- `_form.html.erb`: `viewable: @product, viewable_type: 'Spree::Product'` (was `@product.master`, `'Spree::Variant'`)
-- `products_controller.rb`: rename `assign_master_images` → `assign_session_uploaded_assets`, retarget to `viewable_id: @product.id, viewable_type: 'Spree::Product'`. Session bucket key changes to `'Spree::Product'`
-- `load_variants_data`: variant thumbnail map falls back to `@product.primary_media` when a variant has no `primary_media`
-- Variant edit page (`variants/edit.html.erb`) keeps `viewable_type: 'Spree::Variant'` — variant-level direct uploads work unchanged
-- Skip building a "select from product gallery" picker in legacy admin — that UX is SPA-only
+**Phase 4: Admin SPA UI — partially shipped**
+- Product gallery card: drag-and-drop upload, drag-to-reorder, delete, an edit sheet for alt text and variant assignment. Form-backed — everything except delete rides the parent product save.
+- **Not shipped:** the focal-point picker (delivered by 6.0 below), and the variant "select from product gallery" flow — `VariantMediaPicker` was written but never mounted anywhere. It is **deleted** in 6.0, not finished: assignment is a property of the media row (`variant_ids`), edited from the product gallery, so a second variant-side picker was a duplicate surface for the same data.
-**Phase 4: Admin SPA UI**
-- Product detail page → Media tab: drag-and-drop upload to Product, drag-to-reorder, focal-point picker, alt text editor (consumes existing `use-product-media` hook)
-- Variant detail tab → Media section: "Select from product gallery" multi-select dialog + drag-to-reorder. Each picked asset gets `PATCH /products/:id/media/:asset_id { variant_ids: [...current, this_variant] }`
-- Rebuild `@spree/admin-sdk` (`pnpm build` from root) so the SPA picks up the new endpoints
+**Phase 5: Data migration rake — shipped**
+- `spree:media:migrate_master_images_to_product_media` enqueues `Spree::Media::MigrateProductAssetsJob` per affected product; idempotent, opt-in, `BATCH_SIZE` env
+- `spree:media:backfill_primary_media` backfills `primary_media_id`
-**Phase 5: Data migration rake (opt-in)**
-- `rake spree:migrate_master_images_to_product_media`
-- For each Product: move master-pinned images to `viewable_type: 'Spree::Product'` when master has no line items, copy them when master has line items
-- Recalculate `media_count` counter caches and `primary_media_id`
-- Idempotent — re-runs are no-ops
-- **Not run automatically on upgrade.** Documented as opt-in for merchants who want a clean state. Becomes mandatory in 6.0 (run by master-removal Phase 2)
+### 6.0 — IN PROGRESS
-### 6.0 — TODO
+Master variant is already gone (`6.0-remove-master-variant.md` shipped), so re-homing is no longer this plan's job — the media rake is listed as a prerequisite by `remove_master_variant.rake` and merchants run it as part of that upgrade. What remains here is video, focal point, the rename and the cleanup.
-By 6.0, master variant is being removed (see `6.0-remove-master-variant.md`). Master-removal Phase 2 absorbs the residual image re-homing so no asset is orphaned when its master viewable is deleted.
+**Phase 1: Video support — shipped 2026-08-18**
-**Phase 1: Master image re-homing (owned by master removal)**
-- Master-removal Phase 2 runs the 5.5 rake's logic for any merchant who didn't run it themselves
-- After this step, no asset has `viewable_type: 'Spree::Variant', viewable.is_master: true`
+The 5.5 columns advertised video that nothing could create. `media_type` is read-only on every write path — `permitted_params` in `media_controller.rb` and the inline `media:` list in `products_controller.rb` permit neither `media_type` nor `external_video_url` nor the focal point. Both write paths also route creation through the dead STI `type` column, defaulting to `'Spree::Image'`.
-**Phase 2: Video support (can be deferred)**
-- `media_type='external_video'` URL validation polish
-- Admin UI: "Add video" button for YouTube/Vimeo URLs (5.5 SPA can ship this opportunistically)
+Spree ships **both hosted and external video** (2026-08-18 decision) — merchants arrive with footage in both shapes, so supporting one and not the other pushes half of them to a workaround. What landed:
-**Phase 3: Rename Asset → Media**
-- Rename table `spree_assets` → `spree_media`
-- Rename model `Spree::Asset` → `Spree::Media`
-- Prefix ID already `media_xxx` since 5.4 — no change needed
-- Remove `Spree::Image` subclass
+- `media_type: 'video'` — a file uploaded through Active Storage. Requires an attachment, **not** a URL (the 5.5 validation had this backwards and is fixed).
+- `media_type: 'external_video'` — a YouTube or Vimeo URL. Requires `external_video_url`, has no attachment.
+- Validation is type-directed: image → attached image; video → attached video (`Spree::Config.video_content_types` + `max_video_upload_size`); external_video → a URL Spree recognises.
+- `Spree::ExternalVideo` is the value object that reads a link — provider, video id, embed URL, watch URL, provider thumbnail. It rejects non-video and non-http URLs, and the dashboard mirrors it in `lib/video-url.ts` so a merchant learns a link is unusable while typing.
+- The serializer exposes `video_provider`, `video_embed_url`, `video_url` and `poster_url`. A video's sized URLs (`small_url` …) resolve to its poster, so an image-only gallery still renders.
+- Video carries an optional **poster** attachment (`poster_signed_id` on write, uploadable from the media editor); YouTube falls back to its own thumbnail. Spree does **not** extract a frame from an uploaded file — that needs ffmpeg in the deployment image, and the two comparable self-hosted platforms ship neither video posters nor the dependency (2026-08-18 research). Active Storage's `VideoPreviewer` degrades silently without ffmpeg, so it stays available as an additive step for merchants who install it.
+- Write paths: `media_type`, `external_video_url`, `poster_signed_id` and the focal point are permitted on both the media controller and the inline product `media:` list. Creation keys off `media_type`; the STI `type` param is gone.
+- Dashboard: video files upload through the same drop zone, an "Add video" dialog takes a link, video tiles carry a play badge, and the edit sheet plays the video (iframe for external, `<video>` for hosted).
+
+**Phase 2: Focal point + variant picker (the 5.5 UI remainder)**
+- **Shipped:** focal-point picker — click the image in the media edit sheet to place the point, with a marker and a reset. Writes `focal_point_x/y` through both write paths.
+- **Shipped:** deleted the never-mounted `VariantMediaPicker`, its `use-variant-media` hook and their locale keys. Media is unified on the product, and the media edit sheet already picks which variants use a given item — a variant-side picker would be a second way to edit the same `variant_ids`. The variant-scoped API endpoints and SDK methods stay: direct variant uploads remain a supported path and existing merchant data depends on them.
+
+**Phase 3: Rename Asset → Media — shipped 2026-08-18**
+- `spree_assets` → `spree_media`, `Spree::Asset` → `Spree::Media`
+- `Spree::Asset` is a deprecated constant alias for one release; `Spree::Image` is gone. The `:asset` and `:image` factories stay as aliases of `:media`.
+- `spree:migrate_media_class_names` rewrites the stored class names (custom field resource types, extension polymorphic columns) and is in the 5.6→6.0 manifest, along with the previously unlisted `spree:media:migrate_master_images_to_product_media` — which must run **before** `spree:remove_master_variant`, or deleting a ghost master takes its media with it.
+- `Spree::Api::V3::AssetSerializer` → `MediaEventSerializer` (the lean event payload). Media pins it explicitly, since name-convention resolution would otherwise pick the full customer-facing `MediaSerializer`.
+- Fixed on the way: the 5.5 `AddProductMediaSupport` migration called `Spree::Asset` to backfill, so after the rename it looked for a table that did not exist yet. It uses raw SQL now.
**Phase 4: Cleanup**
-- Remove `Product#variant_images` and `Product#variant_images_without_master` (callers use `Product#media` / `Product#gallery_media`)
-- Remove `viewable_id`/`viewable_type` from Admin API responses
-- Update Duplicator and CSV presenter to operate on product-level media + VariantMedia rows
-- Drop `Product#master_images` alias
+- **Shipped:** removed `Asset.styles` / `default_style` and the `Support::ActiveStorage` module behind them — nothing called `url(style)` anywhere in the monorepo.
+- **Shipped:** dashboard copy reworded for a mixed gallery, in all six locales.
+- **Shipped:** `Variant#secondary_image`, `Product#secondary_image` and `Variant#additional_images` are **deprecated**, removed in 6.1. Nothing in Spree called any of them — no serializer, no API, no dashboard code — and which image to show on hover, or beside the main one, is a storefront presentation choice rather than something core should name. All three shells now read `gallery_media`, which also fixes the bug they shared: reading `images` (and, for `additional_images`, `product.images`, itself a delegate to the default variant) returned nothing for a variant whose gallery comes from linked product-level media.
+- **Still open:** remove `Product#variant_images` — a live fallback while merchants run the migration rake, so it goes when the legacy path does.
## Constraints on Current Work
- **Always use `expand=media`** (not `expand=images`) in new Store API code and SDK examples
-- **Always use `Spree::Asset`** for new code; `Spree::Image` is for backward compat only
-- **Use `gallery_media`** as the unified accessor on Product and Variant — never `master.images`, never `variant_images` directly
-- **Default new product-level uploads to `viewable_type: 'Spree::Product'`** — do not pin to `@product.master` in any new admin code
-- **Variant-level direct uploads stay valid in 5.5** via `viewable_type: 'Spree::Variant'`. Prefer `VariantMedia` rows linking to product-level assets when sharing a blob across variants
+- **Use `Spree::Media`** in new code once the rename lands; `Spree::Asset` reads as a deprecated alias for one release and `Spree::Image` is gone
+- **Use `gallery_media`** as the unified accessor on Product and Variant — never `variant_images` directly
+- **Default new product-level uploads to `viewable_type: 'Spree::Product'`** — never pin new uploads to a variant
+- **Variant-level direct uploads stay valid** via `viewable_type: 'Spree::Variant'`. Prefer `VariantMedia` rows linking to product-level assets when sharing a blob across variants
- **`media_type` is never null** — defaults to `'image'`, always validate inclusion
-- **Do not run the master-image migration rake automatically on upgrade** — it must stay opt-in in 5.5 (becomes mandatory in 6.0 via master removal)
+- **Never branch on the STI `type` column.** `media_type` is the discriminator; `inheritance_column` is nil and `type` is a vestige awaiting removal
+- **A new media attribute must be permitted in two places or it is silently dropped on one write path** — `MediaController#permitted_params` AND the inline `media: [...]` list on `Admin::ProductsController`. The dashboard's product Save hits the second one, so a spec on the media controller proves nothing about it
+- **Never assume a media row has an attachment.** External video has none; any code calling `attachment`, `original_url` or a size variant must handle a video row
+- **Do not run the media migration rake automatically on upgrade** — it stays opt-in, and `remove_master_variant.rake` names it as a prerequisite
## Scope Boundary: Merchandising Media, Not a DAM
@@ -188,9 +201,13 @@ If a future request asks for cross-entity sharing inside Spree (e.g., "this hero
## Open Questions
-- Should we support hosted video uploads (not just external URLs)?
-- Should focal point have a visual picker UI or just numeric fields?
-- Should 3D model support (GLB/USDZ) be a `media_type` value or a separate system?
+- Should 3D model support (GLB/USDZ) be a `media_type` value or a separate system? Deferred — no customer ask yet, and the answer likely mirrors whatever video settles into.
+- Should Spree transcode uploaded video, or serve the original file as uploaded? 6.0 serves the original; transcoding is an infrastructure concern that belongs with a provider, not in core.
+
+**Resolved**
+
+- *Hosted video uploads as well as external URLs?* Yes — both, decided 2026-08-18. See Key Decision 10.
+- *Focal point: visual picker or numeric fields?* A visual picker. Numeric decimals between 0 and 1 are not something a merchant should be asked to reason about.
## References
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 8bea42eeeb..a944533f8e 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -549,20 +549,55 @@ export interface DirectUploadCreateParams {
}
}
+export type MediaType = 'image' | 'video' | 'external_video'
+
export interface MediaCreateParams {
alt?: string
position?: number
- type?: string
+ /** Defaults to `image`. `video` needs a `signed_id`; `external_video` needs an `external_video_url`. */
+ media_type?: MediaType
+ /** YouTube or Vimeo link. Required when `media_type` is `external_video`. */
+ external_video_url?: string
+ /** Fetch an image from this URL. Images only — an external video uses `external_video_url`. */
url?: string
+ /** Direct-upload signed id for the media file itself. */
signed_id?: string
+ /** Direct-upload signed id for a video's poster frame. */
+ poster_signed_id?: string
+ focal_point_x?: number | null
+ focal_point_y?: number | null
// Prefixed or raw variant IDs to link this product-level media to. Variants
// not on the same product are silently dropped server-side.
variant_ids?: Array<string>
}
+/**
+ * One entry in a product's inline `media` list. An entry carrying `id` patches
+ * that media row; one carrying `signed_id` creates from a fresh upload; an
+ * external video creates from its URL alone. Omitting a persisted entry leaves
+ * it untouched — removal goes through the media endpoint's DELETE.
+ */
+export interface ProductMediaInput {
+ id?: string
+ signed_id?: string
+ alt?: string | null
+ position?: number
+ media_type?: MediaType
+ external_video_url?: string | null
+ poster_signed_id?: string
+ focal_point_x?: number | null
+ focal_point_y?: number | null
+ variant_ids?: Array<string>
+}
+
export interface MediaUpdateParams {
alt?: string
position?: number
+ media_type?: MediaType
+ external_video_url?: string
+ poster_signed_id?: string
+ focal_point_x?: number | null
+ focal_point_y?: number | null
// Replaces the full set of variants this media is linked to. Empty array
// clears all links; omit the field entirely to leave links untouched.
variant_ids?: Array<string>
@@ -599,6 +634,8 @@ export interface ProductCreateParams {
/** Every purchasable attribute (sku, prices, stock, weight, dimensions) lives
* on variants. Pass at least one variant to make the product purchasable. */
variants?: ProductVariantInput[]
+ /** Media created alongside the product — see {@link ProductMediaInput}. */
+ media?: ProductMediaInput[]
product_publications?: ProductPublicationInput[]
}
@@ -618,6 +655,8 @@ export interface ProductUpdateParams {
/** Shorthand for a simple (no-options) product — see `ProductCreateParams.prices`. */
prices?: VariantPrice[]
variants?: ProductVariantInput[]
+ /** See {@link ProductMediaInput}. */
+ media?: ProductMediaInput[]
product_publications?: ProductPublicationInput[]
}
diff --git a/packages/admin-sdk/src/types/generated/Media.ts b/packages/admin-sdk/src/types/generated/Media.ts
index 8a8a961afd..e4847faadf 100644
--- a/packages/admin-sdk/src/types/generated/Media.ts
+++ b/packages/admin-sdk/src/types/generated/Media.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 569c2ab4356afb4f012fa1cbcab0cc13
+// Typelizer digest d282335900b50d0904daee5560dd0efe
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -12,6 +12,10 @@ interface Media {
focal_point_x: number | null;
focal_point_y: number | null;
external_video_url: string | null;
+ video_provider: string | null;
+ video_embed_url: string | null;
+ video_url: string | null;
+ poster_url: string | null;
original_url: string | null;
mini_url: string | null;
small_url: string | null;
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index 6c17efa542..239edef054 100644
--- a/packages/cli/src/generated/admin-spec.json
+++ b/packages/cli/src/generated/admin-spec.json
@@ -1 +1 @@
-{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Must match an allowed origin of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies a product under the category (appended to the end).\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}":{"delete":{"summary":"Remove a product from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the category's manual classification.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., category, store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / category / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"category_id":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":{"patch":{"summary":"Buy the shipping label","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Buys the shipping label for a parcel that has not shipped yet — print it, pack the box, then mark the fulfillment fulfilled. Only delivery methods whose provider produces labels accept this.\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":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[state_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/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"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/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/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates a product into the collection (appended to the end).\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}":{"delete":{"summary":"Remove a product from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the collection's manual curation.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/locations":{"get":{"summary":"List company locations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the branches of a business customer. Each branch owns its own addresses and the buyers authorised to purchase for it.\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":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a branch. Addresses are supplied inline and belong to the branch, so editing one later changes the branch's own record rather than an address the buyer also uses.\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":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"location created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"Created inline and owned by the branch.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"}}}},"required":["name"]}}}}}},"/api/v3/admin/company_locations/{id}":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Branches are addressed by their own id once you hold one — the company id is not needed.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"location found","content":{"application/json":{}}}}},"patch":{"summary":"Update a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Address fields sent here edit the branch's existing address in place; send only what changes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"200":{"description":"location updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_address":{"type":"object","properties":{"city":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the branch, its buyers and the addresses it owned.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"204":{"description":"location deleted"}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a business customer. Exemption certificates and tax registrations hang off it.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","nullable":true,"description":"Your own reference for this business, unique within the store."}},"required":["name"]}}}}}},"/api/v3/admin/company_locations/{company_location_id}/contacts":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_location_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company contacts","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customers authorised to purchase for a branch. A customer may act for more than one branch.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"contacts found","content":{"application/json":{}}}}},"post":{"summary":"Create a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Authorises a customer to purchase for a branch. A customer who acts for exactly one branch has\ntheir orders attributed to it automatically; one who acts for several needs the branch set on\nthe order, because guessing would invoice the wrong business.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"contact created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"role":{"type":"string","description":"Free-form label; carries no permissions in 6.0."}},"required":["customer_id"]}}}}}},"/api/v3/admin/company_contacts/{id}":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"contact found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws the customer's authority to purchase for the branch. The customer account itself is untouched.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"204":{"description":"contact deleted"}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"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_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"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_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","number","token","email","customer_note","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string"},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","label","description"],"x-typelizer":true},"CompanyContact":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_location_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true}},"required":["id","role","created_at","updated_at","company_location_id","customer_id","email"],"x-typelizer":true},"CompanyLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"contacts_count":{"type":"number"},"billing_address":{"$ref":"#/components/schemas/Address"},"shipping_address":{"$ref":"#/components/schemas/Address"},"company_contacts":{"type":"array","items":{"$ref":"#/components/schemas/CompanyContact"}}},"required":["id","name","external_id","metadata","created_at","updated_at","company_id","contacts_count","billing_address","shipping_address"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"locations_count":{"type":"number"},"company_locations":{"type":"array","items":{"$ref":"#/components/schemas/CompanyLocation"}}},"required":["id","name","external_id","metadata","created_at","updated_at","locations_count"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","created_at","updated_at","deleted_at","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"tracking_carrier":{"type":"string","nullable":true},"tracking_carrier_name":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"tracking_status":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_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"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"tracking_details":{"type":"object","nullable":true},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","tracking_carrier","tracking_carrier_name","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","tracking_status","estimated_delivery_at","delivered_at","items","metadata","tracking_details","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","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_codes":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"viewable_id":{"type":"string"},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string"}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","created_at","updated_at","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"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},"company_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","number","email","customer_note","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","company_location_id","company_id","tags","internal_note","internal_note_html","approver_id","canceler_id","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","amount","display_amount","status","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","thumbnail_url","tags","price","original_price","seller_id","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"type":"string"},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"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"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","created_at","updated_at"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_item_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_item_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCreditCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"non_expiring":{"type":"boolean"}},"required":["id","name","created_at","updated_at","non_expiring"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"category_id":{"type":"string","nullable":true},"category_name":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id","category_id","category_name"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"type":"string"},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"seller_name":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"own_delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","price","original_price","seller_id","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","hs_code","country_of_origin","customs_description","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name","seller_name","delivery_profile_id","own_delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
+{"info":{"title":"Admin API","contact":{"name":"Spree Commerce","url":"https://spreecommerce.org","email":"[email protected]"},"description":"Spree Admin API v3 - Administrative API for managing products, orders, and store settings.\n\n## Authentication\n\nThe Admin API requires a secret API key passed in the `x-spree-api-key` header.\nSecret API keys can be generated in the Spree admin dashboard.\n\n## Response Format\n\nAll responses are JSON. List endpoints return paginated responses with `data` and `meta` keys.\nSingle resource endpoints return a flat JSON object.\n\n## Resource IDs\n\nEvery resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,\n`variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,\nrequest bodies, and Ransack filters all accept them directly.\n\n## Error Handling\n\nErrors return a consistent format:\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"Validation failed\",\n \"details\": { \"name\": [\"can't be blank\"] }\n }\n}\n```\n","version":"v3"},"paths":{"/api/v3/admin/auth/login":{"post":{"summary":"Login","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Authenticates an admin user and returns a short-lived JWT access token.\nThe rotatable refresh token is set in an HttpOnly cookie — it is not\nincluded in the response body.\n\nThe `provider` field selects the authentication method. When omitted it\ndefaults to `email`, the built-in email/password login.\n\nTo authenticate against a third-party identity provider (Okta, Azure AD,\nGoogle Workspace SSO, a custom JWT issuer, SAML, etc.), send\n`{ \"provider\": \"<your_key>\", ... }` with the fields that provider\nrequires. The endpoint returns the same JWT regardless of which provider\nauthenticated the request. See\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication)\nfor the list of configured providers and their required fields.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"invalid credentials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"title":"EmailPasswordLogin","description":"Built-in email/password authentication (default when `provider` is omitted).","type":"object","properties":{"provider":{"type":"string","enum":["email"],"default":"email"},"email":{"type":"string","format":"email"},"password":{"type":"string"}},"required":["email","password"]},{"title":"ProviderLogin","description":"Provider-dispatched login. The `provider` key selects a configured\nauthentication provider; the remaining fields are forwarded to it.\nRequired fields depend on the provider — see\n[Custom API Authentication](https://spreecommerce.org/docs/developer/how-to/custom-api-authentication).\n","type":"object","properties":{"provider":{"type":"string","description":"Registered provider key (anything other than `email`).","not":{"enum":["email"]}}},"required":["provider"],"additionalProperties":true}]}}}}}},"/api/v3/admin/auth/refresh":{"post":{"summary":"Refresh token","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Exchanges the HttpOnly refresh-token cookie for a new access JWT and a\nrotated refresh token cookie. No request body or Authorization header\nis required — the cookie alone authenticates the call.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"refresh successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"401":{"description":"missing or invalid refresh-token cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/auth/logout":{"post":{"summary":"Logout","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Revokes the refresh-token cookie, effectively logging the admin out.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"logout successful"}}}},"/api/v3/admin/me":{"get":{"summary":"Get current admin user and permissions","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the current admin user profile and a serialized list of permissions (CanCanCan rules). The SPA uses these to drive UI permission checks.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"current admin user and permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update the current admin profile","tags":["Authentication"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Self-service update of the signed-in admin's own profile, such as their admin UI display language (`selected_locale`).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"profile updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"selected_locale":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}}}}}}},"/api/v3/admin/auth/password_resets":{"post":{"summary":"Request password reset","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Requests a password reset email for an admin user. Always returns `202`\nwhether or not the email matches an account, to prevent enumeration.\n\n`redirect_url` is where the emailed link should point (the reset token\nis appended as a `token` query param). It must match one of the store's\nallowed origins — otherwise it is silently ignored and the server-side\ndefault is used. The email is delivered by Spree itself via the\n`admin_user.password_reset_requested` event; this event is never\nforwarded to webhook endpoints.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"reset requested","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"redirect_url":{"type":"string","description":"Must match an allowed origin of the store; ignored otherwise."}},"required":["email"]}}}}}},"/api/v3/admin/auth/password_resets/{id}":{"patch":{"summary":"Reset password","tags":["Authentication"],"security":[{"api_key":[]}],"description":"Consumes a password reset token (the `token` query param from the\nemailed link), sets the new password, and signs the admin in: the\nresponse carries a JWT access token and the rotatable refresh token is\nset in an HttpOnly cookie. The token is single-use — it invalidates as\nsoon as the password changes.\n","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","description":"The reset token from the emailed link","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"password reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponse"}}}},"422":{"description":"invalid or expired token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string"},"password_confirmation":{"type":"string"}},"required":["password","password_confirmation"]}}}}}},"/api/v3/admin/auth/setup":{"get":{"summary":"Check first-run setup availability","tags":["Authentication"],"description":"Reports whether first-run setup is still available — true only while\nthe installation has no admin user. Unauthenticated; the dashboard\nlogin page uses it to offer the setup screen.\n","responses":{"200":{"description":"setup status","content":{"application/json":{}}}}},"post":{"summary":"Complete first-run setup","tags":["Authentication"],"description":"Creates the first admin account and adopts the seeded store, authorized\nby the one-time setup token printed at install time (rotate it with\n`bin/rails spree:setup:token`). Issues a JWT access token and a\nrefresh-token cookie exactly like login. Returns 404 once any admin\nuser exists — the flow is closed permanently after setup.\n","parameters":[],"responses":{"200":{"description":"setup completed","content":{"application/json":{}}},"404":{"description":"setup not available","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["setup_token","email","password","country_code"],"properties":{"setup_token":{"type":"string","description":"One-time token from the install output."},"email":{"type":"string","format":"email"},"password":{"type":"string"},"password_confirmation":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"store_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 country the store sells from. Determines the default market, the warehouse, the delivery zones and the currency."},"locale":{"type":"string","description":"Storefront locale. Defaults to the country's own language."},"currency":{"type":"string","description":"ISO 4217 currency. Defaults to the country's own currency — pass one only when the store prices in something else."}}}}}}}},"/api/v3/admin/auth/setup/countries":{"get":{"summary":"List countries for first-run setup","tags":["Authentication"],"description":"Countries the store can be set up in, each with the currency and\nofficial languages derived from it. Unauthenticated, because the setup\nscreen runs before any credential exists. Returns 404 once any admin\nuser exists.\n","responses":{"200":{"description":"countries","content":{"application/json":{}}}}}},"/api/v3/admin/allowed_origins":{"get":{"summary":"List allowed origins","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the CORS allowlist for the current store. Each entry is a\nbare `scheme://host[:port]` permitted to call the admin API from a\nbrowser. Backs the `Rack::Cors` allowlist and the CSRF boundary of\nthe admin cookie session (see\n`docs/plans/5.5-admin-auth-cookie-refresh.md`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[origin_cont]","in":"query","required":false,"description":"Filter by origin (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origins found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AllowedOrigin"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds an origin to the admin CORS allowlist. The value must be a bare\n`scheme://host[:port]` (no path, query, or fragment) and use `http` or\n`https`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"allowed origin created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}},"required":["origin"]}}}}}},"/api/v3/admin/allowed_origins/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Allowed origin ID","schema":{"type":"string"}}],"get":{"summary":"Get an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single allowed origin by prefixed ID.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"404":{"description":"allowed origin not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing allowed origin.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"allowed origin updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AllowedOrigin"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"origin":{"type":"string"}}}}}}},"delete":{"summary":"Delete an allowed origin","tags":["Allowed Origins"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an origin from the admin CORS allowlist. After deletion the\nadmin SPA running at that origin will no longer be able to call the\nadmin API from a browser.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"allowed origin deleted"}}}},"/api/v3/admin/api_keys":{"get":{"summary":"List API keys","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns publishable and secret API keys for the current store. Secret keys are listed by `token_prefix` only — the plaintext token is delivered exactly once on create.\n\n**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API keys found","content":{"application/json":{}}}}},"post":{"summary":"Create an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a publishable or secret API key. The plaintext token is included in the response **once** for secret keys; publishable keys expose their token on every read since they are intended for client-side use.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"secret key created — plaintext token returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","key_type"],"properties":{"name":{"type":"string"},"key_type":{"type":"string","enum":["publishable","secret"]},"scopes":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/api_keys/{id}":{"get":{"summary":"Show an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key found","content":{"application/json":{}}}}},"patch":{"summary":"Update an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a key. `key_type` and `scopes` are fixed at creation — to change a key's authority, create a new key and revoke the old one.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key renamed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"}}}}}}},"delete":{"summary":"Delete an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"API key deleted"}}}},"/api/v3/admin/api_keys/current":{"get":{"summary":"Describe the current API key","tags":["API Keys"],"security":[{"api_key":[]}],"description":"Returns the secret key that authenticated this request, including its live scopes. Useful to confirm a key's real, current authority. Only secret-key principals have a single key to describe.\n\n**Required scope:** none — any key can describe itself (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"current API key","content":{"application/json":{}}}}}},"/api/v3/admin/api_keys/{id}/revoke":{"patch":{"summary":"Revoke an API key","tags":["API Keys"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks the key revoked. Future requests using its token will fail; the row is preserved for audit.\n\n**Required scope:** `write_api_keys` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API key revoked","content":{"application/json":{}}}}}},"/api/v3/admin/categories":{"get":{"summary":"List categories","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's categories (manual hierarchical taxons; rule-based collections are excluded).\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"categories found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a category. Nests under the parent when parent_id is given, otherwise creates a top-level category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"category created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/categories/{id}":{"get":{"summary":"Get a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single category by ID.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., children, parent, ancestors).","schema":{"type":"string"}}],"responses":{"200":{"description":"category found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}},"404":{"description":"category not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a category.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_id":{"type":"string","description":"Prefixed ID of the parent category"},"description":{"type":"string"},"permalink":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"}}}}}}},"delete":{"summary":"Delete a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a category and its descendants.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"204":{"description":"category deleted"}}}},"/api/v3/admin/categories/{id}/reposition":{"patch":{"summary":"Reposition a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a category to a new parent and/or index within the tree.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"category repositioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Category"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_parent_id":{"type":"string","description":"Prefixed ID of the new parent (omit for top level)"},"new_position":{"type":"integer","description":"0-based index among the new parent's children"}},"required":["new_position"]}}}}}},"/api/v3/admin/categories/{category_id}/products":{"get":{"summary":"List category products","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products classified under the category, ordered by their classification position.\n\n**Required scope:** `read_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies a product under the category (appended to the end).\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/categories/{category_id}/products/{id}":{"delete":{"summary":"Remove a product from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the category's manual classification.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/categories/{category_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a category product","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the category's products.\n\n**Required scope:** `write_categories` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"category_id","in":"path","required":true,"description":"Category ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the category's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/channels":{"get":{"summary":"List channels","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channels configured for the current store.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"channels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new channel on the current store. `code` is normalized to a\nURL-safe slug (`Point of Sale` → `point-of-sale`); when omitted it's\nderived from `name`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"channel created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"code":{"type":"string","description":"Slug — auto-derived from `name` when blank."},"active":{"type":"boolean","default":true},"default":{"type":"boolean","default":false},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}}},"/api/v3/admin/channels/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel found","content":{"application/json":{}}}}},"patch":{"summary":"Update a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"channel updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true,"description":"Routing strategy class name. `null` inherits the store setting."},"preferred_storefront_access":{"type":"string","nullable":true,"enum":["public","prices_hidden","login_required"],"description":"Anonymous-visitor access posture. `null` inherits the store setting."},"preferred_guest_checkout":{"type":"boolean","nullable":true,"description":"Whether guests can check out without an account. `null` inherits the store setting."}}}}}}},"delete":{"summary":"Delete a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"channel deleted"}}}},"/api/v3/admin/channels/{id}/add_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish products on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes the listed products on this channel. Idempotent — re-publishing\nan already-published product updates its publication window. Products from\nsibling stores are silently dropped.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}},"published_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications go live. `null` means immediately."},"unpublished_at":{"type":"string","format":"date-time","nullable":true,"description":"When the publications come down. `null` means never."}}}}}}}},"/api/v3/admin/channels/{id}/remove_products":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Unpublish products from a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes the listed products from this channel.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List order routing rules for a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the channel's routing rules in priority order. The rules engine walks them top-down; see the Order Routing guide.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rules found","content":{"application/json":{}}}}},"post":{"summary":"Create an order routing rule on a channel","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a rule to the channel's routing list. The `type` is the wire shorthand from `GET /order_routing_rules/types` (e.g. `preferred_location`). Omitting `position` appends the rule at the end of the list. Each rule kind can appear at most once per channel — a duplicate `type` is rejected with a validation error.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"rule created","content":{"application/json":{}}},"422":{"description":"unknown rule type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}},"required":["type"]}}}}}},"/api/v3/admin/channels/{channel_id}/order_routing_rules/{id}":{"parameters":[{"name":"channel_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a rule's `active` flag, `position` (the list reorders around it), or `preferences`. The rule kind cannot be changed — delete and re-create instead.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"rule updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object","additionalProperties":true}}}}}}},"delete":{"summary":"Delete an order routing rule","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"rule deleted"}}}},"/api/v3/admin/order_routing_rules/types":{"get":{"summary":"List available order routing rule types","tags":["Channels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels, descriptions and preference schemas — drives the \"Add rule\" picker in the admin dashboard. Plugins extend the list by registering `Spree::OrderRoutingRule` subclasses via `Spree.order_routing.rules`.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/custom_field_definitions":{"get":{"summary":"List custom field definitions","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all defined custom fields. Filter by `?q[resource_type_eq]=Spree::Product` to narrow to one parent type.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definitions returned","content":{"application/json":{}}}}},"post":{"summary":"Create a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"definition created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["key","field_type","resource_type"],"properties":{"namespace":{"type":"string","description":"Defaults to `custom`"},"key":{"type":"string"},"label":{"type":"string","description":"Human-readable name; defaults to titleized `key`"},"field_type":{"type":"string","description":"Custom field type identifier (one of the registered field-type class names)."},"resource_type":{"type":"string","description":"Owner class, e.g. `Spree::Product`"},"storefront_visible":{"type":"boolean","description":"When false, the definition is admin-only and never exposed in the Store API"},"searchable":{"type":"boolean","description":"When true, values are included in storefront product text search"},"sortable":{"type":"boolean","description":"When true, storefront product listings can sort by this field"}}}}}}}},"/api/v3/admin/custom_field_definitions/{id}":{"get":{"summary":"Show a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand. Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., key,label,field_type). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"definition found","content":{"application/json":{}}}}},"patch":{"summary":"Update a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"definition updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a custom field definition","tags":["Custom Fields"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the definition and cascades to all custom field values referencing it.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"definition deleted"}}}},"/api/v3/admin/customer_groups":{"get":{"summary":"List customer groups","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer groups configured for the current store. Groups\nsegment customers for targeted promotions (see the `customer_group`\npromotion rule) and reporting. The list endpoint never embeds the\nmember list — fetch a single group with `?expand=customers` if you\nneed them inline, or query `/admin/customers?customer_group_id_in=…`\nfor paginated membership.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer groups found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer group in the current store. `customer_ids` is\noptional; when present, customers are attached at create time.\nPass prefixed IDs (e.g. `cus_…`) — the server decodes them\nautomatically.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer group created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customer_groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Customer group prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single customer group. Pass `?expand=customers` to embed\nthe full member list inline (recommended only for single-record\nreads — embed cost scales with membership size).\n\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `customers`.","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer group with embedded customers","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"404":{"description":"customer group not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, description, or membership. `customer_ids` is a\nfull-set replacement — the server reconciles the membership to\nmatch the array, adding new IDs and removing ones not present.\nSend `customer_ids: []` to clear all members.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer group updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerGroup"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"customer_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a customer group","tags":["Customer Groups"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the group. Member users are not deleted; their `customer_group_users` rows are dropped.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer group deleted"}}}},"/api/v3/admin/customers/{customer_id}/addresses":{"get":{"summary":"List customer addresses","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved addresses.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., country, state). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., first_name,last_name,address1,city). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"addresses found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new address to the customer's address book. Pass `is_default_billing: true` or `is_default_shipping: true` to set as the default — the previous default loses its flag in the same transaction.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"address created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string","description":"ISO-2 country code (e.g. US)"},"state_code":{"type":"string","description":"State/province abbreviation (e.g. NY)"},"phone":{"type":"string"},"company":{"type":"string"},"label":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}}},"/api/v3/admin/customers/{customer_id}/addresses/{id}":{"patch":{"summary":"Update a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a customer address.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"address updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"city":{"type":"string"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a customer address","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes the address. If it was a default, the customer loses that default (no auto-promotion).\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"address deleted"}}}},"/api/v3/admin/customers/{customer_id}/credit_cards":{"get":{"summary":"List customer credit cards","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customer's saved credit cards. Useful for off-session admin charges via `POST /admin/orders/:id/payments { source_id }`.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit cards found","content":{"application/json":{}}}}}},"/api/v3/admin/customers/{customer_id}/credit_cards/{id}":{"get":{"summary":"Show a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a saved credit card by ID.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., payment_method). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., brand,last4,month,year). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"credit card found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a customer credit card","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a saved credit card.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"credit card deleted"}}}},"/api/v3/admin/customers/{customer_id}/store_credits":{"get":{"summary":"List customer store credits","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns store credits issued to the customer.\n\n**Required scope:** `read_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., category, store, created_by). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., amount,amount_used,memo,currency). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"store credits found","content":{"application/json":{}}}}},"post":{"summary":"Issue a store credit to a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"`created_by` is set automatically from the authenticated admin.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"store credit created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","category_id"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"category_id":{"type":"string","description":"StoreCreditCategory ID"},"memo":{"type":"string"}}}}}}}},"/api/v3/admin/customers/{customer_id}/store_credits/{id}":{"patch":{"summary":"Update a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Update memo / category / amount. The amount can only be changed if `amount_used == 0`.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"store credit updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"category_id":{"type":"string"},"memo":{"type":"string"}}}}}}},"delete":{"summary":"Delete a store credit","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused store credit (amount_used == 0). Returns 422 otherwise.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"store credit deleted"}}}},"/api/v3/admin/customers":{"get":{"summary":"List customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of customers. Supports Ransack search/filters.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[search]","in":"query","required":false,"description":"Email + name full-text-ish search","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., addresses, store_credits). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customers found","content":{"application/json":{}}}}},"post":{"summary":"Create a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a customer. No welcome email is sent automatically.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"customer created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}}},"/api/v3/admin/customers/{id}":{"get":{"summary":"Show a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full customer details including computed order stats (orders_count, total_spent, last_order_completed_at).\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations: addresses, orders, store_credits, default_billing_address, default_shipping_address","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., email,first_name,last_name). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"customer found","content":{"application/json":{}}}}},"patch":{"summary":"Update a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates customer attributes. `tags` replaces the full set.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"phone":{"type":"string"},"accepts_email_marketing":{"type":"boolean"},"internal_note":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}}},"delete":{"summary":"Delete a customer","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a customer. Returns 422 if the customer has any orders.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"customer deleted"}}}},"/api/v3/admin/customers/bulk_add_to_groups":{"post":{"summary":"Bulk-add customers to groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each customer in `ids` to every group in `customer_group_ids`.\nIdempotent — customers already in a group are skipped server-side.\nGroups from sibling stores are silently ignored. Returns counts of\ncustomers and groups that were processed (post store-scoping).\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers added to groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_from_groups":{"post":{"summary":"Bulk-remove customers from groups","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each customer in `ids` from every group in `customer_group_ids`.\nNo-op for non-members. Groups from sibling stores are silently ignored.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customers removed from groups","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"customer_group_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","customer_group_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_add_tags":{"post":{"summary":"Bulk-add tags to customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every customer in `ids`. Tags are\nupserted by name; re-adding an existing tag is a no-op.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/customers/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from customers","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag name in `tags` from every customer in `ids`. No-op\nfor customers that don't carry the tag.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{"schema":{"type":"object","properties":{"customer_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/exports":{"get":{"summary":"List exports","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV exports queued or completed for the current store. Polled by the admin SPA to detect when an export finishes (`done: true`).\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"exports found","content":{"application/json":{}}}}},"post":{"summary":"Create an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV export. The `type` selects the dataset; `search_params` is an\noptional Ransack query (same shape used by the `q[...]` params on list endpoints)\nthat filters which records are exported. Pass `record_selection: \"all\"` to\nclear the filter server-side and export everything in scope.\n\nGeneration is asynchronous. Poll `GET /admin/exports/{id}` until `done` is `true`,\nthen redirect the browser to `download_url` to fetch the file.\n\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"export queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["products","orders","customers","product_translations","gift_cards","coupon_codes","newsletter_subscribers"]},"record_selection":{"type":"string","enum":["filtered","all"],"description":"Set to \"all\" to ignore search_params and export everything in scope."},"search_params":{"type":"object","description":"Ransack query hash. Same predicates accepted by the list endpoint.","additionalProperties":true},"results_url":{"type":"string","description":"Absolute URL of your admin exports view; the export-done email uses it as the download button target. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/exports/{id}":{"get":{"summary":"Show an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns export status. While `done` is `false`, the SPA continues polling.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"export found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the export and purges its attachment.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"export deleted"}}}},"/api/v3/admin/exports/{id}/download":{"get":{"summary":"Download an export","tags":["Exports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the exported CSV with `Content-Disposition: attachment`. Returns 422 with `code: export_not_ready` while `done` is still `false`. The endpoint is JWT/API-key protected, so SPA clients must fetch it (with `Authorization` header) and trigger the browser download via a Blob URL — a top-level navigation cannot carry the JWT.\n\n**Required scope:** the read scope of the exported resource — `read_products` for product exports, `read_customers` for customer exports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments":{"get":{"summary":"List fulfillments","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all shipments for an order.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillments found","content":{"application/json":{}}}}},"post":{"summary":"Create a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually creates a fulfillment on a completed order, bypassing order routing — for example to mirror a shipment handled by an external carrier or 3PL. Moves the requested line item quantities out of their current fulfillments; when `items` is omitted, every not-yet-shipped unit is moved. Pass `status: 'shipped'` to register an already-shipped fulfillment (fires shipped webhooks and freezes cost/carrier). When `delivery_method_id` is omitted, the fulfillment inherits the delivery method and cost of the source fulfillment(s) it fully drains — keeping the order total unchanged; partially drained splits get no carrier when shipped, and pending fulfillments are otherwise (re)priced by the standard rate engine, which selects the lowest-cost available rate. Pass `cost` to set an explicit shipping cost instead (e.g. the 3PL price) — note this changes the order total and payment state, and is guaranteed to persist only with `status: 'shipped'` (pending fulfillments are re-priced by the rate engine).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fulfillment created","content":{"application/json":{}}},"422":{"description":"order not completed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_location_id"],"properties":{"stock_location_id":{"type":"string","description":"Stock location the fulfillment ships from"},"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link — a full URL is served back as tracking_url unchanged instead of being templated into the delivery method tracking URL"},"delivery_method_id":{"type":"string","description":"Delivery method (carrier) to attach as the selected rate. Defaults to the delivery method of the fully drained source fulfillment(s)"},"cost":{"type":"string","description":"Explicit shipping cost. Defaults to the summed cost of the fully drained source fulfillment(s), which keeps the order total unchanged; an explicit cost changes the order total and payment state. Guaranteed to persist only with status: 'shipped' — pending fulfillments are re-priced by the rate engine"},"status":{"type":"string","enum":["shipped"],"description":"Pass 'shipped' to register the fulfillment as already shipped"},"items":{"type":"array","description":"Line item quantities to fulfill. Omit to fulfill every not-yet-shipped unit.","items":{"type":"object","required":["item_id","quantity"],"properties":{"item_id":{"type":"string","description":"Line item ID"},"quantity":{"type":"integer"}}}},"metadata":{"type":"object","additionalProperties":true}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}":{"get":{"summary":"Show a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific shipment.\n\n**Required scope:** `read_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., inventory_units, stock_location, shipping_rates). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,status,tracking,cost). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment found","content":{"application/json":{}}}}},"patch":{"summary":"Update a shipment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a fulfillment (tracking, delivery rate).\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"shipment updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"type":"string","description":"Carrier tracking number, or a full https:// tracking link served back as tracking_url unchanged"},"selected_delivery_rate_id":{"type":"string","description":"Delivery rate ID (dr_...) to select"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/fulfill":{"patch":{"summary":"Fulfill a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Marks a fulfillment as fulfilled.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment fulfilled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/purchase_label":{"patch":{"summary":"Buy the shipping label","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Buys the shipping label for a parcel that has not shipped yet — print it, pack the box, then mark the fulfillment fulfilled. Only delivery methods whose provider produces labels accept this.\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":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/mark_delivered":{"patch":{"summary":"Mark a fulfillment delivered","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the customer received the goods. Only a fulfilled shipment can be marked delivered.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment delivered","content":{"application/json":{}}},"422":{"description":"fulfillment has not shipped","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When the goods arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification. Defaults to true."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/cancel":{"patch":{"summary":"Cancel a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment canceled","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/resume":{"patch":{"summary":"Resume a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Resumes a canceled fulfillment.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment resumed","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{id}/split":{"patch":{"summary":"Split a fulfillment","tags":["Fulfillments"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Transfers items from this shipment to a new shipment at a different stock location.\n\n**Required scope:** `write_fulfillments` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"fulfillment split","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"stock_location_id":{"type":"string","description":"Target stock location ID"}}}}}}}},"/api/v3/admin/gift_card_batches":{"get":{"summary":"List gift card batches","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift card batches issued by the current store. Each batch\ngroups the cards generated together for a campaign or bulk-issuance\n— the cards themselves live under `/admin/gift_cards` and reference\nthe batch via `gift_card_batch_id`.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Records per page","schema":{"type":"integer"}},{"name":"q[prefix_cont]","in":"query","required":false,"description":"Filter by prefix (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batches found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCardBatch"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a batch of gift cards in a single call. The server generates\n`codes_count` cards inline for small batches (configurable via\n`Spree.config.gift_card_batch_web_limit`, default 500) or enqueues\na background job for larger ones. Each card's code is the batch\n`prefix` followed by random hex.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card batch created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["prefix","amount","codes_count"],"properties":{"prefix":{"type":"string","description":"Lowercased and prepended to every generated code."},"amount":{"type":"string","description":"Decimal amount per card, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"codes_count":{"type":"integer","description":"Number of cards to generate. Capped at `gift_card_batch_limit`."},"expires_at":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/gift_card_batches/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card batch prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card batch","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single batch.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card batch found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCardBatch"}}}},"404":{"description":"gift card batch not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/gift_cards":{"get":{"summary":"List gift cards","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the gift cards issued by the current store. Filter by\n`q[code_cont]` for code search, `q[user_id_eq]` for cards issued\nto a specific customer, or `q[state_eq]` for status filtering.\n\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[code_cont]","in":"query","required":false,"description":"Filter by gift card code (contains)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by status (active, redeemed, partially_redeemed, canceled)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift cards found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GiftCard"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a gift card scoped to the current store. The code is\nauto-generated when omitted. `currency` defaults to the store's\nconfigured currency. Pass `user_id` (prefixed ID) to attach the\ncard to a specific customer.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"gift card created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"string","description":"Decimal amount, greater than zero."},"currency":{"type":"string","description":"ISO 4217 currency code. Defaults to the store currency."},"code":{"type":"string","description":"Optional caller-supplied code. Auto-generated when omitted."},"expires_at":{"type":"string","description":"ISO 8601 date.","nullable":true},"user_id":{"type":"string","description":"Optional customer prefixed ID.","nullable":true}}}}}}}},"/api/v3/admin/gift_cards/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Gift card prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single gift card.\n\n**Required scope:** `read_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"gift card found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}},"404":{"description":"gift card not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an active gift card's editable attributes. Redeemed or\npartially-redeemed cards cannot be edited.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"gift card updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GiftCard"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"},"expires_at":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a gift card","tags":["Gift Cards"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an unused gift card. Cards that have been redeemed or\npartially redeemed cannot be deleted and return 422.\n\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"gift card deleted"},"422":{"description":"redeemed gift card cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/imports":{"get":{"summary":"List imports","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns CSV imports queued or completed for the current store.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"imports found","content":{"application/json":{}}}}},"post":{"summary":"Create an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Queues a CSV import. Upload the file first via `POST /api/v3/admin/direct_uploads`\nand pass the returned `signed_id` as `attachment`. On success the import is in the\n`mapping` state and the response carries the mapping payload: `schema_fields`\n(the canonical columns for the type), `csv_headers`, a `sample_row`, and the\nauto-assigned `mappings`.\n\nAdjust mappings if needed, then call `PATCH /admin/imports/{id}/complete_mapping`\nto start processing. Poll `GET /admin/imports/{id}` while `status` is\n`completed_mapping`/`processing`; terminal statuses are `completed` and `failed`.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"import created in mapping state","content":{"application/json":{}}},"422":{"description":"unknown import type","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type","attachment"],"properties":{"type":{"type":"string","enum":["products","customers","product_translations"]},"attachment":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."},"preferred_delimiter":{"type":"string","enum":[",",";","|","\t"],"description":"CSV column separator. Defaults to a comma."},"results_url":{"type":"string","description":"Absolute URL of your admin imports view; the import-done email links back to it with `?import=<id>` appended. Only honored when it matches one of the store's configured allowed origins."}}}}}}}},"/api/v3/admin/imports/template":{"get":{"summary":"Download an import template","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a CSV header row for the given import type, including the custom field columns available for the model.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"200":{"description":"CSV template","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/example":{"get":{"summary":"Download an example import file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Redirects to a populated example CSV for the given import type — the same sample data `rake spree:load_sample_data` uses, pinned to the installed Spree version. Returns 404 for a type that ships no example file.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"type","in":"query","required":true,"description":"Registered import type, e.g. products.","schema":{"type":"string"}}],"responses":{"302":{"description":"Redirect to the example CSV"}}}},"/api/v3/admin/imports/{id}":{"get":{"summary":"Show an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns import status and row counters. The admin dashboard polls this endpoint while `status` is `completed_mapping` or `processing`; `rows_count`, `completed_rows_count` and `failed_rows_count` drive the progress bar. The mapping payload (`csv_headers`, `sample_row`) is only present while `status` is `mapping`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"import found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an import","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the import, its rows and the uploaded file. Returns 422 while the import is being processed.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"import deleted"}}}},"/api/v3/admin/imports/{id}/download":{"get":{"summary":"Download the originally uploaded file","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the CSV exactly as it was uploaded — the audit trail for what was imported. JWT/API-key protected; SPA clients fetch it with the Authorization header and trigger the browser download via a Blob URL.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"CSV file","content":{"application/json":{},"text/csv":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/v3/admin/imports/{id}/complete_mapping":{"patch":{"summary":"Complete mapping and start processing","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the submitted column mappings, then starts row processing. Omit `mappings`\nto accept the auto-assigned ones from the create response. Returns 422 when a\nrequired schema field is left unmapped (`details.missing_required_fields`) or a\nfile column is assigned twice.\n\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"mapping completed, processing queued","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mappings":{"type":"array","description":"Column assignments to apply before starting. `file_column: null` unmaps a field.","items":{"type":"object","required":["schema_field"],"properties":{"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true}}}}}}}}}}},"/api/v3/admin/imports/{id}/retry_failed_rows":{"patch":{"summary":"Retry failed rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-processes the rows that failed. The import re-enters `processing`; poll `GET /admin/imports/{id}` until it completes again. Returns 422 when the import is not `completed` or has no failed rows.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"retry queued","content":{"application/json":{}}}}}},"/api/v3/admin/imports/{import_id}/rows":{"get":{"summary":"List import rows","tags":["Imports"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Paginated rows of an import — the failure report. Filter with `q[status_eq]=failed` to list only rows that could not be imported; each row carries the raw CSV `data` and its `validation_errors`.\n\n**Required scope:** the write scope of the imported resource — `write_products` for product imports, `write_customers` for customer imports, etc. (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"import_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter rows by status: pending, processing, completed, failed.","schema":{"type":"string"}}],"responses":{"200":{"description":"rows found","content":{"application/json":{}}}}}},"/api/v3/admin/markets":{"get":{"summary":"List markets","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the markets configured for the current store. Markets are\nstore-scoped and ordered by `position` (an `acts_as_list` column —\nupdate the order via `PATCH /markets/{id}` with `position`).\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed. Supported: `countries`.","schema":{"type":"string"}}],"responses":{"200":{"description":"markets found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new market for the current store.\n\n- `country_codes` accepts 2-letter ISO country codes (e.g. `[\"DE\", \"FR\"]`);\n the market must contain at least one country. Unknown codes are\n silently dropped.\n- `supported_locales` accepts an array of locale codes; the\n `default_locale` is always implicitly included.\n- Setting `default: true` automatically demotes the previous default\n market in the store.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"market created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string","description":"ISO 4217 currency code."},"default_locale":{"type":"string","description":"IETF locale tag used as the market default."},"supported_locales":{"type":"array","items":{"type":"string"},"description":"Locale codes available in this market. The default is always implicitly included."},"tax_inclusive":{"type":"boolean","default":false,"description":"Display prices with tax included."},"default":{"type":"boolean","default":false,"description":"Setting to true demotes the previous default."},"position":{"type":"integer","description":"Sort order within the store; lower = first."},"country_codes":{"type":"array","items":{"type":"string"},"description":"2-letter ISO country codes assigned to this market. At least one is required."}},"required":["name","currency","default_locale","country_codes"]}}}}}},"/api/v3/admin/markets/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"market found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"404":{"description":"market not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing market. Pass `country_codes` to replace the\nmarket's country list (full-set update), `supported_locales` to\nreplace the supported locales, or `position` to reorder the market\nwithin the store.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"market updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Market"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"default_locale":{"type":"string"},"supported_locales":{"type":"array","items":{"type":"string"}},"tax_inclusive":{"type":"boolean"},"default":{"type":"boolean"},"position":{"type":"integer"},"country_codes":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a market","tags":["Markets"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the market (sets `deleted_at`). The default market and\nthe last remaining market in a store cannot be deleted — both return\n422 with a `validation_error`.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"market deleted"},"422":{"description":"cannot delete default or last market","content":{"application/json":{}}}}}},"/api/v3/admin/option_types":{"get":{"summary":"List option types","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of option types.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new option type. Supports nested option values.\n\nOption values can be provided inline and will be created or updated by name.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"option type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}},"required":["name","label"]}}}}}},"/api/v3/admin/option_types/{id}":{"get":{"summary":"Get an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single option type by ID, including its option values.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., name,label,position). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"option type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"404":{"description":"option type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an option type. Supports updating nested option values.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"200":{"description":"option type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OptionType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"},"filterable":{"type":"boolean"},"option_values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Existing option value ID to update"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete an option type","tags":["Option Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes an option type.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Option type ID","schema":{"type":"string"}}],"responses":{"204":{"description":"option type deleted"}}}},"/api/v3/admin/orders/{order_id}/tax_lines":{"get":{"summary":"List tax lines","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed tax rows on the order. Read-only — written exclusively by the tax provider.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"tax lines found","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{order_id}/discounts":{"get":{"summary":"List discounts","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Typed discount rows (promotion-sourced and manual) on the order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"200":{"description":"discounts found","content":{"application/json":{}}}}},"post":{"summary":"Create manual discount","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual discount. With line_item_id a single row is created; without it the amount is distributed across line items (largest remainder). This is the sanctioned post-placement discount path and works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"discount created","content":{"application/json":{}}},"422":{"description":"invalid discount","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"value":{"type":"number"},"value_type":{"type":"string","enum":["flat","percent"]},"line_item_id":{"type":"string","nullable":true,"description":"Target line item; omit to distribute order-level"}},"required":["label","value"]}}}}}},"/api/v3/admin/orders/{order_id}/fees":{"post":{"summary":"Create fee","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a fee (surcharge, handling, gift wrap, COD, payment fee). Order-level when no target is given. Works on completed orders.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order prefixed ID","schema":{"type":"string"}}],"responses":{"201":{"description":"fee created","content":{"application/json":{}}},"422":{"description":"invalid fee","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"},"amount":{"type":"number"},"kind":{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"],"description":"Defaults to 'surcharge'"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true}},"required":["label","amount"]}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards":{"post":{"summary":"Apply a gift card to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies a gift card by code to the order. Returns the gift card.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"gift card applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string","description":"Gift card code"}}}}}}}},"/api/v3/admin/orders/{order_id}/gift_cards/{id}":{"delete":{"summary":"Remove a gift card from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the gift card from the order.\n\n**Required scope:** `write_gift_cards` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Gift card ID","schema":{"type":"string"}}],"responses":{"204":{"description":"gift card removed"}}}},"/api/v3/admin/orders/{order_id}/items":{"get":{"summary":"List order items","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all line items for an order.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"items found","content":{"application/json":{}}}}},"post":{"summary":"Add an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a new line item to the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"item added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Prefixed variant ID"},"quantity":{"type":"integer","default":1}}}}}}}},"/api/v3/admin/orders/{order_id}/items/{id}":{"get":{"summary":"Show an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns details of a specific line item.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., variant, variant.product). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., quantity,price,total). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"item found","content":{"application/json":{}}}}},"patch":{"summary":"Update an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order item quantity or metadata.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"200":{"description":"item updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer"}}}}}}},"delete":{"summary":"Remove an item","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an item from the order.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Item ID","schema":{"type":"string"}}],"responses":{"204":{"description":"line item removed"}}}},"/api/v3/admin/orders/{order_id}/store_credits":{"post":{"summary":"Apply customer's store credit to an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Applies the order customer's available store credit. When `amount` is omitted, applies up to the order outstanding balance.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"201":{"description":"store credit applied","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string","description":"Optional explicit amount; defaults to order outstanding balance"}}}}}}},"delete":{"summary":"Remove store credit from an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes any applied store credit from the order.\n\n**Required scope:** `write_store_credits` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"order_id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"store credit removed"}}}},"/api/v3/admin/orders":{"get":{"summary":"List orders","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of orders for the current store.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"sort","in":"query","required":false,"description":"Sort field (e.g., created_at, -created_at, completed_at)","schema":{"type":"string"}},{"name":"q[state_eq]","in":"query","required":false,"description":"Filter by state (cart, address, delivery, payment, confirm, complete, canceled)","schema":{"type":"string"}},{"name":"q[email_cont]","in":"query","required":false,"description":"Filter by email (contains)","schema":{"type":"string"}},{"name":"q[number_eq]","in":"query","required":false,"description":"Filter by order number","schema":{"type":"string"}},{"name":"q[completed_at_gt]","in":"query","required":false,"description":"Filter by completed after date","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"orders found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new draft order in one shot. Customer, items, addresses, currency,\nmarket, channel, locale, notes, metadata, and a coupon code can all be\nprovided inline.\n\nSetting `preferred_stock_location_id` pins the order's preferred fulfillment\nlocation — Order Routing's built-in `PreferredLocation` rule consumes it\nwhen picking which stock location ships each shipment.\n\nInvalid coupon codes are non-fatal — the order is created and the failure\nis reported on the service result (not in the API response body for now).\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"order created with preferred_stock_location_id","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_id":{"type":"string","description":"Customer ID. Alias: user_id (legacy)."},"use_customer_default_address":{"type":"boolean","description":"When true with customer_id, copies the customer's saved billing/shipping addresses onto the order."},"currency":{"type":"string"},"market_id":{"type":"string","description":"Market ID"},"channel_id":{"type":"string","description":"Channel ID. Defaults to the store primary channel when omitted."},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Order Routing's built-in PreferredLocation rule reads this and ranks the location first; routing falls back to the next rule when the preferred location can't cover the cart."},"locale":{"type":"string"},"customer_note":{"type":"string","description":"Public, customer-visible note"},"internal_note":{"type":"string","description":"Staff-only note"},"metadata":{"type":"object","description":"Arbitrary key/value metadata"},"shipping_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"shipping_address_id":{"type":"string","description":"Existing customer address ID"},"billing_address":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"billing_address_id":{"type":"string","description":"Existing customer address ID"},"items":{"type":"array","items":{"type":"object","required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}},"coupon_code":{"type":"string","description":"Optional. Applied non-fatally; invalid codes do not block creation."}}}}}}}},"/api/v3/admin/orders/{id}":{"get":{"summary":"Show an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns full order details including admin-only fields.\n\n**Required scope:** `read_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID (e.g., or_xxx)","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., items, fulfillments, payments, customer, discounts, billing_address, shipping_address). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., number,total,status,completed_at). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"order found","content":{"application/json":{}}},"404":{"description":"order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an order. Supports updating email, addresses, special instructions, and line items.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"customer_note":{"type":"string"},"internal_note":{"type":"string"},"channel_id":{"type":"string","description":"Channel ID"},"preferred_stock_location_id":{"type":"string","description":"Stock Location ID to prefer for fulfillment. Re-runs Order Routing's PreferredLocation rule on subsequent shipment rebuilds."},"ship_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"bill_address":{"type":"object","properties":{"firstname":{"type":"string"},"lastname":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"zipcode":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"phone":{"type":"string"}}},"items":{"type":"array","items":{"type":"object","required":["variant_id"],"properties":{"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer"},"metadata":{"type":"object"}}}}}}}}}},"delete":{"summary":"Delete a draft order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a draft order. Completed orders cannot be deleted.\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"204":{"description":"order deleted"}}}},"/api/v3/admin/orders/{id}/complete":{"patch":{"summary":"Complete an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Completes an order in the `confirm` state, marking it as placed.\n\nSet `notify_customer: true` to send the order confirmation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\nSet `notify_customer: true` to send the order cancellation email.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order canceled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order cancellation email after canceling."}}}}}}}},"/api/v3/admin/orders/{id}/approve":{"patch":{"summary":"Approve an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Approves an order (e.g., for fraud review).\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order approved","content":{"application/json":{}}}}}},"/api/v3/admin/orders/{id}/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"},"422":{"description":"deletion refused by a store rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/products/bulk_status_update":{"post":{"summary":"Bulk-update product status","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets `status` on each product in `ids`. Reindexes the affected products\nfor search. Cross-store IDs are silently dropped. Returns counts.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"cross-store products silently dropped","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"status":{"type":"string"}}}}}},"422":{"description":"invalid status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","status"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["draft","active","archived"]}}}}}}}},"/api/v3/admin/products/bulk_add_to_categories":{"post":{"summary":"Bulk-add products to categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every category (category) in `category_ids`.\nCategories from sibling stores are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to categories","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"category_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_categories":{"post":{"summary":"Bulk-remove products from categories","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every category in `category_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from categories","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","category_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_collections":{"post":{"summary":"Bulk-add products to collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Attaches each product in `ids` to every manual collection in `collection_ids`.\nAutomatic (rule-based) and sibling-store collections are silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products added to collections","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"collection_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_collections":{"post":{"summary":"Bulk-remove products from collections","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Detaches each product in `ids` from every collection in `collection_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed from collections","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","collection_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"collection_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_to_channels":{"post":{"summary":"Bulk-add products to channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Publishes each product in `ids` on every channel in `channel_ids`. Idempotent —\nre-publishing on an existing channel is a no-op. Channels from sibling stores\nare silently ignored.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products published on channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_from_channels":{"post":{"summary":"Bulk-remove products from channels","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unpublishes each product in `ids` from every channel in `channel_ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products unpublished from channels","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"channel_count":{"type":"integer"},"removed":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","channel_ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"channel_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_add_tags":{"post":{"summary":"Bulk-add tags to products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds each tag name in `tags` to every product in `ids`. Tags are upserted by name.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags added","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"},"tag_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_remove_tags":{"post":{"summary":"Bulk-remove tags from products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes each tag in `tags` from every product in `ids`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"tags removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids","tags"],"properties":{"ids":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/products/bulk_destroy":{"delete":{"summary":"Bulk-delete products","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes each product in `ids`. Returns the count actually destroyed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products deleted","content":{"application/json":{"schema":{"type":"object","properties":{"product_count":{"type":"integer"}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/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/tax_rates":{"get":{"summary":"List tax rates","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's tax rates. Rates are the entire configuration of\nthe built-in tax provider: each pairs a tax category with a jurisdiction\n(a country, optionally narrowed to one state) and a percentage, and\ndecides whether the tax is already included in the product price\n(VAT-style) or added on top (US-style).\n\nMarkets using an external tax provider ignore these rows — that\nprovider carries its own jurisdiction data.\n\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[included_in_price_true]","in":"query","required":false,"description":"Only rates included in the product price","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a tax rate for the current store. Give either `amount` as a\ndecimal (`0.19`) or `amount_percentage` as a percentage (`19`).\n\nName the jurisdiction with `country_code` (and `state_code` for a\nstate-level rate). Omitting the country makes the rate apply everywhere.\n\nSet `included_in_price` for VAT-style pricing, where the rate is backed\nout of the displayed price rather than added to it.\n\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"tax rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Customer-facing rate name, e.g. \"VAT\""},"amount":{"type":"string","description":"Rate as a decimal, e.g. \"0.19\""},"amount_percentage":{"type":"number","description":"Rate as a percentage, e.g. 19"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string","description":"ISO code, e.g. \"DE\". Omit for every country."},"state_code":{"type":"string","description":"State abbreviation within that country, e.g. \"CA\"."}},"required":["name","tax_category_id"]}}},"required":true}}},"/api/v3/admin/tax_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Tax rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}}},"patch":{"summary":"Update a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"tax rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"amount":{"type":"string"},"amount_percentage":{"type":"number"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"tax_category_id":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a tax rate","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the rate. Tax lines it already produced keep their own rate snapshot.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"tax rate deleted"}}}},"/api/v3/admin/translatable_resources":{"get":{"summary":"List translatable resources","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every translatable resource type and its translatable fields (key + content type), so clients can render translation editors generically.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translatable resources found","content":{"application/json":{}}}}}},"/api/v3/admin/translations/batch":{"post":{"summary":"Batch upsert translations","tags":["Settings"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Atomically upserts translations across many records of (possibly) different translatable resource types in one request — e.g. an option type and all its option values in one save. A flat list of independent registry writes; all entries succeed or none do.\n\n**Required scope:** `write_<resource>` for every resource type in the batch (for API-key authentication) (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"translations upserted","content":{"application/json":{}}},"422":{"description":"unsupported locale rolls back the whole batch","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["translations"],"properties":{"translations":{"type":"array","items":{"type":"object","required":["resource_type","resource_id","values"],"properties":{"resource_type":{"type":"string","description":"Translatable resource type token, e.g. `option_type`"},"resource_id":{"type":"string","description":"Prefixed id of the record"},"values":{"type":"object","description":"Map of locale code to { field: value }","additionalProperties":{"type":"object","additionalProperties":true}}}}}}}}}}}},"/api/v3/admin/admin_users":{"get":{"summary":"List staff","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns admin users with at least one role assignment on the current store.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff found","content":{"application/json":{}}}}}},"/api/v3/admin/admin_users/{id}":{"get":{"summary":"Show a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member found","content":{"application/json":{}}}}},"patch":{"summary":"Update a staff member","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name fields and reassigns roles for the current store. `role_ids` is a complete replacement — roles not in the array are removed for this store.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"staff member updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"role_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Remove a staff member from this store","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"staff removed from store"}}}},"/api/v3/admin/invitations":{"get":{"summary":"List invitations","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns invitations for the current store, including pending and accepted.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitations found","content":{"application/json":{}}}}},"post":{"summary":"Create an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Invites a teammate by email. The invitation is scoped to the current store and carries the chosen role; on accept, a `RoleUser` is created via the invitation's `after_accept` callback.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","role_id"],"properties":{"email":{"type":"string"},"role_id":{"type":"string"}}}}}}}},"/api/v3/admin/invitations/{id}":{"delete":{"summary":"Revoke an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"invitation revoked"}}}},"/api/v3/admin/invitations/{id}/resend":{"patch":{"summary":"Resend an invitation","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Issues a fresh token and dispatches the invitation email again.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"invitation resent","content":{"application/json":{}}}}}},"/api/v3/admin/permissions":{"get":{"summary":"List the permission catalog","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the permission catalog — the grant vocabulary shared by staff role permissions and secret API key scopes. Entries are grouped for permission pickers; labels and descriptions are localized. Readable by any authenticated admin credential.","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"catalog returned","content":{"application/json":{}}}}}},"/api/v3/admin/roles":{"get":{"summary":"List roles","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns staff roles with their catalog permissions. Roles are global, not per-store; `mutable: false` marks the protected admin role and host-locked rows.\n\n**Required scope:** `read_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"roles found","content":{"application/json":{}}}}},"post":{"summary":"Create a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a staff role. `permissions` holds catalog keys (see GET /admin/permissions); a caller may only grant keys they effectively hold.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"role created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}},"required":["name"]}}}}}},"/api/v3/admin/roles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a role name, description or permissions. The admin role and host-locked roles (`mutable: false`) reject changes.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"role updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"permissions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a role","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a role. Fails with 422 while the role is protected or still referenced by staff members or pending invitations.\n\n**Required scope:** `write_staff` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"role deleted"},"422":{"description":"role cannot be deleted","content":{"application/json":{}}}}}},"/api/v3/admin/stock_locations":{"get":{"summary":"List stock locations","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the configured stock locations. Stock locations are global\n(shared across stores). Filter with Ransack predicates such as\n`q[active_eq]`, `q[kind_eq]`, `q[pickup_enabled_eq]`, or\n`q[name_cont]`.\n\nPickup-related attributes (`kind`, `pickup_enabled`,\n`pickup_stock_policy`, `pickup_ready_in_minutes`,\n`pickup_instructions`) drive merchant pickup support at checkout —\ncustomers can collect orders from any active location with\n`pickup_enabled: true`.\n\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[active_eq]","in":"query","required":false,"description":"Filter by active status","schema":{"type":"boolean"}},{"name":"q[kind_eq]","in":"query","required":false,"description":"Filter by kind (built-in: 'warehouse', 'store', 'fulfillment_center')","schema":{"type":"string"}},{"name":"q[pickup_enabled_eq]","in":"query","required":false,"description":"Filter by pickup-enabled flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock locations found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLocation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new stock location.\n\nSetting `default: true` automatically demotes the previous default\nlocation.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"stock location created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true,"description":"Internal name shown only in the admin"},"active":{"type":"boolean"},"default":{"type":"boolean","description":"Setting to true demotes the previous default."},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"],"description":"Categorizes the location."},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true,"description":"ISO-3166 alpha-2 country code (e.g. \"US\")."},"state_code":{"type":"string","nullable":true,"description":"State / province abbreviation (e.g. \"NY\"). Resolved against the selected country."},"state_name":{"type":"string","nullable":true,"description":"Free-text state for countries without a states list."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"],"description":"'local' = items at this location only; 'any' = transfer-eligible (ship-to-store)."},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/stock_locations/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock location ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock location by prefixed ID.\n\n**Required scope:** `read_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"404":{"description":"stock location not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates an existing stock location. Same address-field conventions as\nthe create endpoint.\n\nSetting `default: true` automatically demotes the previous default.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"stock location updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockLocation"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"kind":{"type":"string","enum":["warehouse","store","fulfillment_center"]},"propagate_all_variants":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"pickup_ready_in_minutes":{"type":"number","nullable":true,"minimum":0},"pickup_instructions":{"type":"string","nullable":true}}}}}}},"delete":{"summary":"Delete a stock location","tags":["Stock Locations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the stock location (sets `deleted_at`). Existing\nfulfillments that referenced it keep the historical record via\n`Spree::StockLocation.with_deleted`.\n\n\n**Required scope:** `write_stock` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"stock location deleted"}}}},"/api/v3/admin/products/{product_id}/variants":{"get":{"summary":"List product variants","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of variants for a product, including the default variant.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variants found","content":{"application/json":{}}}}},"post":{"summary":"Create a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new variant for a product. Supports nested prices and stock items.\n\nOption types and values are auto-created if they don't exist.\nPrices are upserted by currency. Stock items are upserted by stock location.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"201":{"description":"variant created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"A variant on a product with option types should declare its option pairs (e.g. size + color) — one per option type it participates in. Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}}},"/api/v3/admin/products/{product_id}/variants/{id}":{"get":{"summary":"Get a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single variant by ID.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., images, prices, stock_items, option_values). Use dot notation for nested expand (max 4 levels).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include (e.g., sku,price,stock). id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"variant found","content":{"application/json":{}}},"404":{"description":"variant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a variant. Only provided fields are updated.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"200":{"description":"variant updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string"},"cost_price":{"type":"string"},"cost_currency":{"type":"string"},"weight":{"type":"number"},"height":{"type":"number"},"width":{"type":"number"},"depth":{"type":"number"},"weight_unit":{"type":"string"},"dimensions_unit":{"type":"string"},"track_inventory":{"type":"boolean"},"tax_category_id":{"type":"string"},"options":{"type":"array","description":"One pair per option type the variant participates in (e.g. size + color). Option types and values are auto-created if missing.","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"type":"string"}}}},"position":{"type":"integer"},"barcode":{"type":"string"},"prices":{"type":"array","description":"Per-currency prices. Upserted by currency.","items":{"type":"object","required":["currency","amount"],"properties":{"currency":{"type":"string"},"amount":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true}}}},"stock_items":{"type":"array","description":"Per-stock-location inventory. Upserted by stock_location_id.","items":{"type":"object","required":["stock_location_id","count_on_hand"],"properties":{"stock_location_id":{"type":"string","description":"Stock location ID (e.g. sloc_xxx)"},"count_on_hand":{"type":"integer"},"backorderable":{"type":"boolean"}}}}}}}}}},"delete":{"summary":"Delete a variant","tags":["Variants"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes a variant.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"product_id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Variant ID","schema":{"type":"string"}}],"responses":{"204":{"description":"variant deleted"}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"List webhook deliveries","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns delivery attempts for the given endpoint, most recent first.\nEach row carries the original request payload, the response code\n(when the receiver replied), the execution time, and any transport\nerror — everything needed to audit failures and decide whether to\nredeliver.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[event_name_eq]","in":"query","required":false,"description":"Filter by event name (exact)","schema":{"type":"string"}},{"name":"q[success_eq]","in":"query","required":false,"description":"Filter by success flag","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-delivered_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}},"404":{"description":"parent webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single delivery attempt with the full request payload and\nthe response body the receiver returned. Use this for ad-hoc debug\nof failed deliveries.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery found","content":{"application/json":{}}},"404":{"description":"delivery not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/webhook_endpoints/{webhook_endpoint_id}/deliveries/{id}/redeliver":{"parameters":[{"name":"webhook_endpoint_id","in":"path","required":true,"description":"Parent webhook endpoint ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Webhook delivery ID to redeliver","schema":{"type":"string"}}],"post":{"summary":"Redeliver a webhook delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new delivery row with the same payload + event_name and\nqueues it. The original row is preserved for audit history.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"redelivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints":{"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns outbound webhook subscriptions for the current store. Each\nendpoint receives a signed POST when any subscribed event fires.\n`secret_key` is `null` on list reads — the plaintext is delivered\nexactly once on create.\n\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[url_cont]","in":"query","required":false,"description":"Filter by URL (contains)","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoints found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a new outbound webhook subscription. The plaintext\n`secret_key` is returned **once** in this response — persist it\nimmediately to verify incoming webhook signatures. Subsequent reads\nreturn `null` for the secret. Pass an empty `subscriptions` array or\nomit it to receive every event.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"webhook endpoint created — secret_key returned once","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}}},"/api/v3/admin/webhook_endpoints/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"get":{"summary":"Get a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single webhook endpoint by prefixed ID.\n\n**Required scope:** `read_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint found","content":{"application/json":{}}},"404":{"description":"webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates name, URL, active flag, or the event subscription list.\nToggling `active` here is equivalent to calling `disable`/`enable`\nwithout an audit reason.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint updated","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the endpoint and stops future deliveries.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"webhook endpoint deleted"}}}},"/api/v3/admin/webhook_endpoints/{id}/send_test":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"post":{"summary":"Send a test delivery","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a `webhook.test` delivery record and queues it. Use this to\nverify the endpoint is reachable and your signature verification\naccepts Spree's payloads.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"test delivery queued","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/enable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Re-enable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Re-enables an endpoint that was manually or automatically disabled.\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint enabled","content":{"application/json":{}}}}}},"/api/v3/admin/webhook_endpoints/{id}/disable":{"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string"}}],"patch":{"summary":"Disable a webhook endpoint","tags":["Webhooks"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Manually pauses an endpoint. Unlike auto-disable (triggered after\nrepeated delivery failures), no notification email is sent.\n\n\n**Required scope:** `write_webhooks` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"webhook endpoint disabled","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/collections":{"get":{"summary":"List collections","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of the store's collections.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collections found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Create a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a manual or automatic (rule-based) collection. For automatic collections, send the full desired rule set under `rules`.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"collection created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"sort_order":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"rules":{"type":"array","description":"Full desired rule set. Entries with an id update, id-less entries create, omitted rules are removed.","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}},"required":["name"]}}}}}},"/api/v3/admin/collections/{id}":{"get":{"summary":"Get a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single collection by ID, including its rules.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (e.g., rules, custom_fields, translations).","schema":{"type":"string"}}],"responses":{"200":{"description":"collection found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}},"404":{"description":"collection not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a collection. Send `position` to reorder it within the flat list; send the full `rules` set to sync automatic rules.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"collection updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Collection"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"permalink":{"type":"string"},"description":{"type":"string"},"meta_title":{"type":"string"},"meta_description":{"type":"string"},"meta_keywords":{"type":"string"},"sort_order":{"type":"string"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string","enum":["all","any"]},"position":{"type":"integer","description":"Reorders the collection within the flat list (acts_as_list)"},"rules":{"type":"array","description":"Full desired rule set (see create).","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"match_policy":{"type":"string"}}}}}}}}}},"delete":{"summary":"Delete a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a collection.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"204":{"description":"collection deleted"}}}},"/api/v3/admin/collections/{collection_id}/products":{"get":{"summary":"List collection products","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Products curated in the collection, ordered by their membership position.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"200":{"description":"products found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add a product to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates a product into the collection (appended to the end).\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}}],"responses":{"201":{"description":"product added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_id":{"type":"string"}},"required":["product_id"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}":{"delete":{"summary":"Remove a product from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a product from the collection's manual curation.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product removed"}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/locations":{"get":{"summary":"List company locations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the branches of a business customer. Each branch owns its own addresses and the buyers authorised to purchase for it.\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":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"locations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a branch. Addresses are supplied inline and belong to the branch, so editing one later changes the branch's own record rather than an address the buyer also uses.\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":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"location created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"Created inline and owned by the branch.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"address1":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country_code":{"type":"string"}}}},"required":["name"]}}}}}},"/api/v3/admin/company_locations/{id}":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Branches are addressed by their own id once you hold one — the company id is not needed.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"location found","content":{"application/json":{}}}}},"patch":{"summary":"Update a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Address fields sent here edit the branch's existing address in place; send only what changes.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"200":{"description":"location updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_address":{"type":"object","properties":{"city":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a company location","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes the branch, its buyers and the addresses it owned.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"204":{"description":"location deleted"}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List tax exemption certificates","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a business's exemption evidence. `active` is the field that decides whether a certificate\nexempts a sale: a verified certificate stops counting once its expiry date passes, so the status\nalone does not answer it.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"certificates found","content":{"application/json":{}}}}},"post":{"summary":"Create a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records exemption evidence against a business. Certificates start `pending` and exempt nothing\nuntil verified.\n\n`country_code` and `state_code` say where the certificate holds — omit both for one valid\neverywhere, give only the country for one valid throughout it. `document` takes an ActiveStorage\nsigned blob id obtained from `POST /api/v3/admin/direct_uploads`.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"certificate created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"certificate_number":{"type":"string"},"reason_code":{"type":"string","description":"Becomes the tax provider's entity use code."},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"issuing_authority":{"type":"string","nullable":true},"document":{"type":"string","description":"ActiveStorage signed blob id from POST /api/v3/admin/direct_uploads."}},"required":["certificate_number","reason_code"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/verify":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Verify a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Accepts the certificate as evidence, which is what makes it exempt sales. Only a pending\ncertificate can be accepted — re-accepting a revoked one would restore evidence that was\ndeliberately withdrawn. An installation that checks numbers against a registry, or requires a\nsecond approval, can refuse here, and the refusal is returned as a validation error.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate verified","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/revoke":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Revoke a tax exemption certificate","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws accepted evidence. A verified certificate cannot be deleted — how a sale was taxed has to remain explainable — so revoking is the way out.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"200":{"description":"certificate revoked","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_exemption_certificates/{id}/download":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Download a certificate document","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Streams the uploaded document. Deliberately not a storage link: the bytes come through the API so\nthe same credentials apply to every read of a confidential document. Requires only read access.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"document streamed","content":{"application/json":{}}},"422":{"description":"no document attached","content":{"application/json":{}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company tax registrations","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business's tax registrations, one per kind. A business registration takes precedence\nover the buyer's own when a sale is for that business, because the invoice is addressed to the\nentity rather than the person who placed the order.\n\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"registrations found","content":{"application/json":{}}}}},"post":{"summary":"Create a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registers a tax number against the business. Verification against the relevant registry runs in\nthe background where a validator is installed for the kind; a stock installation registers none,\nleaving the status unattempted.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"registration created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The regime the number belongs to."},"value":{"type":"string"}},"required":["kind","value"]}}}}}},"/api/v3/admin/companies/{company_id}/tax_identifiers/{id}/validate":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Re-check a company tax registration","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the registry again. Manual because a registry answers only \"valid now\" — a number verified\nlast year may have been deregistered since — and because a check that came back unavailable\ncannot otherwise be retried without editing the number.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"422":{"description":"no validator installed for this kind","content":{"application/json":{}}}}}},"/api/v3/admin/companies":{"get":{"summary":"List companies","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the business customers of the current store.\n\n**Required scope:** `read_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"companies found","content":{"application/json":{}}}}},"post":{"summary":"Create a company","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a business customer. Exemption certificates and tax registrations hang off it.\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"company created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"external_id":{"type":"string","nullable":true,"description":"Your own reference for this business, unique within the store."}},"required":["name"]}}}}}},"/api/v3/admin/company_locations/{company_location_id}/contacts":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"company_location_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List company contacts","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the customers authorised to purchase for a branch. A customer may act for more than one branch.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"contacts found","content":{"application/json":{}}}}},"post":{"summary":"Create a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Authorises a customer to purchase for a branch. A customer who acts for exactly one branch has\ntheir orders attributed to it automatically; one who acts for several needs the branch set on\nthe order, because guessing would invoice the wrong business.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"contact created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_id":{"type":"string"},"role":{"type":"string","description":"Free-form label; carries no permissions in 6.0."}},"required":["customer_id"]}}}}}},"/api/v3/admin/company_contacts/{id}":{"parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"contact found","content":{"application/json":{}}}}},"delete":{"summary":"Delete a company contact","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Withdraws the customer's authority to purchase for the branch. The customer account itself is untouched.\n\n**Required scope:** `write_customers` (for API-key authentication).","responses":{"204":{"description":"contact deleted"}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/product_types":{"get":{"summary":"List product types","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a paginated list of product types.\n\nA product type is a back-office template: it seeds option types and\ncategories onto products created with it, and defines which custom\nfields those products' forms show. It is not exposed on the Store API.\n\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}}],"responses":{"200":{"description":"product types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a product type.\n\n`option_type_ids` and `category_ids` seed products created with this\ntype. `custom_field_definitions` is a replace-set of the definitions the\nproduct form renders, in `sort_order`. `required` is advisory — the\ndashboard marks the field, but a blank value is never rejected.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"201":{"description":"product type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"422":{"description":"unprocessable entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true,"description":"Fulfillment profile stamped onto products created with this type. Null leaves new products on the store default profile."},"option_type_ids":{"type":"array","items":{"type":"string"},"description":"Option types seeded onto products created with this type."},"category_ids":{"type":"array","items":{"type":"string"},"description":"Categories seeded onto products created with this type."},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Prefixed custom field definition id."},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}},"required":["name"]}}}}}},"/api/v3/admin/product_types/{id}":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single product type with its option types, categories and custom fields.\n\n**Required scope:** `read_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}},"404":{"description":"product type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a product type.\n\nChanges never modify products that already carry the type — use\n`apply_to_products` to backfill those.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"200":{"description":"product type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"required":{"type":"boolean"},"sort_order":{"type":"integer"}}}}}}}}}},"delete":{"summary":"Delete a product type","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a product type. Types still used by products cannot be deleted.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"204":{"description":"product type deleted"}}}},"/api/v3/admin/product_types/{id}/apply_to_products":{"parameters":[{"name":"id","in":"path","description":"Product type ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Apply a product type to its existing products","tags":["Product Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Backfills the type's option types and categories onto the products that\nalready carry it. Additive and idempotent — nothing is removed, and\nre-running is safe.\n\nRuns in the background; the response reports how many products the type\ncurrently has.\n\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}}],"responses":{"202":{"description":"backfill accepted","content":{"application/json":{"schema":{"type":"object","properties":{"products_count":{"type":"integer"}}}}}}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"count":{"type":"integer","description":"Total number of records"},"pages":{"type":"integer","description":"Total number of pages"},"from":{"type":"integer","description":"Index of first record on this page"},"to":{"type":"integer","description":"Index of last record on this page"},"in":{"type":"integer","description":"Number of records on this page"},"previous":{"type":"integer","nullable":true,"description":"Previous page number"},"next":{"type":"integer","nullable":true,"description":"Next page number"}},"required":["page","limit","count","pages","from","to","in"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","description":"Field-specific validation errors","nullable":true}},"required":["code","message"]}},"required":["error"]},"AuthResponse":{"type":"object","properties":{"token":{"type":"string","description":"JWT access token"},"user":{"$ref":"#/components/schemas/AdminUser"}},"required":["token","user"]},"PermissionRule":{"type":"object","description":"A single permission rule (CanCanCan rule). Rules are applied in order, last-matching-wins.","properties":{"allow":{"type":"boolean","description":"true for `can`, false for `cannot`"},"actions":{"type":"array","items":{"type":"string"},"description":"Action names, e.g. [\"read\", \"update\"] or [\"manage\"]"},"subjects":{"type":"array","items":{"type":"string"},"description":"Subject class names, e.g. [\"Spree::Product\"] or [\"all\"]"},"has_conditions":{"type":"boolean","description":"True if the server-side rule has per-record conditions. The SPA shows the action optimistically and handles 403 from the API."}},"required":["allow","actions","subjects","has_conditions"]},"MeResponse":{"type":"object","description":"Current admin user profile and serialized permissions","properties":{"user":{"$ref":"#/components/schemas/AdminUser"},"permissions":{"type":"array","items":{"$ref":"#/components/schemas/PermissionRule"}}},"required":["user","permissions"]},"ImportSchemaField":{"type":"object","description":"A canonical column of an import type, including per-store custom field columns","properties":{"name":{"type":"string","description":"Canonical field name used in mappings"},"label":{"type":"string","description":"Human-readable label"},"required":{"type":"boolean","description":"Whether the field must be mapped before processing"}},"required":["name","label","required"]},"CheckoutRequirement":{"type":"object","properties":{"step":{"type":"string","description":"Checkout step this requirement belongs to"},"field":{"type":"string","description":"Field that needs to be satisfied"},"message":{"type":"string","description":"Human-readable requirement message"}},"required":["step","field","message"]},"CartWarning":{"type":"object","description":"A warning about a cart issue (e.g., item removed due to stock change)","properties":{"code":{"type":"string","description":"Machine-readable warning code"},"message":{"type":"string","description":"Human-readable warning message"},"line_item_id":{"type":"string","nullable":true,"description":"Prefixed line item ID (when applicable)"},"variant_id":{"type":"string","nullable":true,"description":"Prefixed variant ID (when applicable)"},"item_index":{"type":"integer","nullable":true,"description":"Position in the submitted items array, for warnings raised while applying a batch of item changes"}},"required":["code","message"]},"FulfillmentManifestItem":{"type":"object","description":"An item within a fulfillment — which line item and how many units are in this fulfillment","properties":{"item_id":{"type":"string","description":"Line item ID"},"variant_id":{"type":"string","description":"Variant ID"},"quantity":{"type":"integer","description":"Quantity in this fulfillment"}},"required":["item_id","variant_id","quantity"]},"AdminUserRoleAssignment":{"type":"object","description":"A role assignment for the current store on a staff member","properties":{"id":{"type":"string","description":"Prefixed role ID"},"name":{"type":"string","description":"Role name"}},"required":["id","name"]},"AdminUserStore":{"type":"object","description":"A store the staff member can access through a role assignment","properties":{"id":{"type":"string","description":"Prefixed store ID"},"name":{"type":"string","description":"Store name"},"code":{"type":"string","description":"Store code"}},"required":["id","name","code"]},"PreferenceField":{"type":"object","description":"A single configurable preference on a payment method, promotion rule/action, or calculator. The frontend uses `type` + `default` to render a sensible input.","properties":{"key":{"type":"string"},"type":{"type":"string","description":"string | text | password | integer | decimal | boolean | array | hash"},"default":{"description":"Default value (any JSON type), null when there is no default","nullable":true}},"required":["key","type"]},"PromotionActionCalculator":{"type":"object","description":"The action's nested calculator (when the action carries one — null for actions like `free_shipping`)","properties":{"type":{"type":"string","description":"Wire shorthand for the calculator subclass"},"label":{"type":"string"},"preferences":{"type":"object","additionalProperties":true},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}}},"required":["type","label","preferences","preference_schema"]},"PromotionActionLineItem":{"type":"object","description":"One row in a `create_line_items` action — the variant added to the order and how many","properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer"}},"required":["variant_id","quantity"]},"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_code":{"type":"string"},"state_text":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"quick_checkout":{"type":"boolean"},"is_default_billing":{"type":"boolean"},"is_default_shipping":{"type":"boolean"},"state_abbr":{"type":"string","nullable":true},"country_iso":{"type":"string"},"state_name":{"type":"string","nullable":true},"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_code","state_text","state_code","quick_checkout","is_default_billing","is_default_shipping","state_abbr","country_iso","state_name","label","metadata","created_at","updated_at","customer_id"],"x-typelizer":true},"AdminUser":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"full_name":{"type":"string","nullable":true},"selected_locale":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true},"roles":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserRoleAssignment"}},"stores":{"type":"array","items":{"$ref":"#/components/schemas/AdminUserStore"}}},"required":["id","email","first_name","last_name","full_name","selected_locale","created_at","updated_at","avatar_url","roles","stores"],"x-typelizer":true},"AllowedOrigin":{"type":"object","properties":{"id":{"type":"string"},"origin":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","origin","created_at","updated_at"],"x-typelizer":true},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_type":{"type":"string"},"token_prefix":{"type":"string","nullable":true},"scopes":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"revoked_at":{"type":"string","nullable":true},"last_used_at":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"plaintext_token":{"type":"string","nullable":true},"created_by_email":{"type":"string","nullable":true}},"required":["id","name","key_type","token_prefix","scopes","created_at","updated_at","revoked_at","last_used_at","channel_id","plaintext_token","created_by_email"],"x-typelizer":true},"AppliedPromotion":{"type":"object","properties":{"id":{"type":"string"},"promotion_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","promotion_id","name","description","code","amount","display_amount","created_at","updated_at"],"x-typelizer":true},"Cart":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"preferred_stock_location_id":{"type":"string","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/CartWarning"}},"coupon_code":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"adjustment_total":{"type":"string","nullable":true},"display_adjustment_total":{"type":"string","nullable":true},"discount_total":{"type":"string","nullable":true},"display_discount_total":{"type":"string","nullable":true},"tax_total":{"type":"string","nullable":true},"display_tax_total":{"type":"string","nullable":true},"included_tax_total":{"type":"string","nullable":true},"display_included_tax_total":{"type":"string","nullable":true},"additional_tax_total":{"type":"string","nullable":true},"display_additional_tax_total":{"type":"string","nullable":true},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"gift_card_total":{"type":"string","nullable":true},"display_gift_card_total":{"type":"string","nullable":true},"amount_due":{"type":"string","nullable":true},"display_amount_due":{"type":"string","nullable":true},"delivery_total":{"type":"string","nullable":true},"display_delivery_total":{"type":"string","nullable":true},"fee_total":{"type":"string","nullable":true},"display_fee_total":{"type":"string","nullable":true},"store_credit_total":{"type":"string","nullable":true},"display_store_credit_total":{"type":"string","nullable":true},"covered_by_store_credit":{"type":"boolean"},"current_step":{"type":"string"},"completed_steps":{"type":"array","items":{"type":"string"}},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRequirement"}},"shipping_eq_billing_address":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"completed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}}},"required":["id","market_id","channel_id","preferred_stock_location_id","number","token","email","customer_note","currency","locale","total_quantity","warnings","coupon_code","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","current_step","completed_steps","requirements","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"Category":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"depth":{"type":"number"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"children_count":{"type":"number"},"parent_id":{"type":"string","nullable":true},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"is_root":{"type":"boolean"},"is_child":{"type":"boolean"},"is_leaf":{"type":"boolean"},"parent":{"$ref":"#/components/schemas/Category"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"metadata":{"type":"object"},"pretty_name":{"type":"string"},"lft":{"type":"number"},"rgt":{"type":"number"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","permalink","position","depth","meta_title","meta_description","meta_keywords","children_count","parent_id","description","description_html","image_url","square_image_url","is_root","is_child","is_leaf","metadata","pretty_name","lft","rgt","products_count","created_at","updated_at"],"x-typelizer":true},"Channel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string"},"active":{"type":"boolean"},"default":{"type":"boolean"},"storefront_access":{"type":"string"},"guest_checkout":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string","nullable":true},"preferred_storefront_access":{"type":"string","nullable":true},"preferred_guest_checkout":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","code","active","default","storefront_access","guest_checkout","preferred_order_routing_strategy","preferred_storefront_access","preferred_guest_checkout","created_at","updated_at","stock_location_ids"],"x-typelizer":true},"ClaimLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"send_replacement":{"type":"boolean"},"description":{"type":"string","nullable":true},"refund_amount":{"type":"string"},"paid_amount":{"type":"string"},"display_refund_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"replacement_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"replacement_variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","quantity","send_replacement","description","refund_amount","paid_amount","display_refund_amount","variant_id","replacement_variant_id","line_item_id","created_at","updated_at"],"x-typelizer":true},"ClaimReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Claim":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"resolution":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"resolved_at":{"type":"string","nullable":true},"denied_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ClaimReason"},"claim_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ClaimLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","resolution","order_id","reason_id","refund_total","display_refund_total","approved_at","resolved_at","denied_at","canceled_at","memo","metadata","created_at","updated_at","created_by_id"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string"}},"required":["id","type","value","match_policy"],"x-typelizer":true},"Collection":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"permalink":{"type":"string"},"position":{"type":"number"},"sort_order":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"products_count":{"type":"number"},"description":{"type":"string"},"description_html":{"type":"string"},"image_url":{"type":"string","nullable":true},"square_image_url":{"type":"string","nullable":true},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"translations":{"type":"object"},"automatic":{"type":"boolean"},"rules_match_policy":{"type":"string"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CollectionRule"}}},"required":["id","name","permalink","position","sort_order","meta_title","meta_description","meta_keywords","products_count","description","description_html","image_url","square_image_url","automatic","rules_match_policy","metadata","created_at","updated_at"],"x-typelizer":true},"CommissionLine":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string"},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","label","description"],"x-typelizer":true},"CompanyContact":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_location_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true}},"required":["id","role","created_at","updated_at","company_location_id","customer_id","email"],"x-typelizer":true},"CompanyLocation":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"contacts_count":{"type":"number"},"billing_address":{"$ref":"#/components/schemas/Address"},"shipping_address":{"$ref":"#/components/schemas/Address"},"company_contacts":{"type":"array","items":{"$ref":"#/components/schemas/CompanyContact"}}},"required":["id","name","external_id","metadata","created_at","updated_at","company_id","contacts_count","billing_address","shipping_address"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"locations_count":{"type":"number"},"company_locations":{"type":"array","items":{"$ref":"#/components/schemas/CompanyLocation"}}},"required":["id","name","external_id","metadata","created_at","updated_at","locations_count"],"x-typelizer":true},"Country":{"type":"object","properties":{"iso":{"type":"string"},"iso3":{"type":"string"},"name":{"type":"string"},"states_required":{"type":"boolean"},"zipcode_required":{"type":"boolean"},"states":{"type":"array","items":{"$ref":"#/components/schemas/State"}},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true}},"required":["iso","iso3","name","states_required","zipcode_required"],"x-typelizer":true},"CouponCode":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"state":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"promotion_id":{"type":"string"},"order_id":{"type":"string","nullable":true}},"required":["id","code","state","created_at","updated_at","promotion_id","order_id"],"x-typelizer":true},"CreditCard":{"type":"object","properties":{"id":{"type":"string"},"brand":{"type":"string"},"last4":{"type":"string"},"month":{"type":"number"},"year":{"type":"number"},"name":{"type":"string","nullable":true},"default":{"type":"boolean"},"gateway_payment_profile_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"payment_method_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","brand","last4","month","year","name","default","gateway_payment_profile_id","customer_id","payment_method_id","metadata","created_at","updated_at"],"x-typelizer":true},"CustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"namespace":{"type":"string"},"key":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"resource_type":{"type":"string"},"storefront_visible":{"type":"boolean"},"searchable":{"type":"boolean"},"sortable":{"type":"boolean"},"filter_key":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","namespace","key","label","field_type","resource_type","storefront_visible","searchable","sortable","filter_key","created_at","updated_at"],"x-typelizer":true},"CustomField":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"type":{"type":"string","deprecated":true},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"key":{"type":"string"},"value":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"storefront_visible":{"type":"boolean"},"custom_field_definition_id":{"type":"string"}},"required":["id","label","type","field_type","key","value","created_at","updated_at","storefront_visible","custom_field_definition_id"],"x-typelizer":true},"CustomerGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"customers_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","name","description","customers_count","created_at","updated_at"],"x-typelizer":true},"Customer":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"accepts_email_marketing":{"type":"boolean"},"full_name":{"type":"string"},"available_store_credit_total":{"type":"string"},"display_available_store_credit_total":{"type":"string"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"default_billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"default_shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"newsletter_subscriber":{"allOf":[{"$ref":"#/components/schemas/NewsletterSubscriber"}],"nullable":true},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"failed_attempts":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"default_billing_address_id":{"type":"string","nullable":true},"default_shipping_address_id":{"type":"string","nullable":true},"orders_count":{"type":"number"},"total_spent":{"type":"string"},"display_total_spent":{"type":"string"},"last_order_completed_at":{"type":"string","nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"store_credits":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"customer_group_ids":{"type":"array","items":{"type":"string"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","created_at","updated_at","tags","internal_note","internal_note_html","default_billing_address_id","default_shipping_address_id","orders_count","total_spent","display_total_spent","last_order_completed_at","customer_group_ids"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","name","description","preferences","preference_schema","product_ids"],"x-typelizer":true},"DeliveryMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"number","nullable":true},"estimated_transit_business_days_max":{"type":"number","nullable":true},"digital":{"type":"boolean"},"pickup":{"type":"boolean"},"pickup_point":{"type":"boolean"},"admin_name":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string"},"pickup_point_provider":{"type":"string","nullable":true},"rate_provider":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"services":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodService"}},"rules":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryMethodRule"}},"tax_category_id":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_zone_id":{"type":"string","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"}},"calculator_type":{"type":"string","nullable":true},"calculator_preferences":{"type":"object","nullable":true}},"required":["id","name","code","estimated_transit_business_days_min","estimated_transit_business_days_max","digital","pickup","pickup_point","admin_name","fulfillment_provider","pickup_point_provider","rate_provider","storefront_visible","tracking_url","markup_flat","markup_percent","created_at","updated_at","deleted_at","services","rules","tax_category_id","delivery_profile_id","delivery_origin_group_id","delivery_zone_id","stock_location_ids","calculator_type","calculator_preferences"],"x-typelizer":true},"DeliveryMethodService":{"type":"object","properties":{"id":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"label":{"type":"string","nullable":true},"markup_flat":{"type":"string","nullable":true},"markup_percent":{"type":"string","nullable":true},"position":{"type":"number"}},"required":["id","carrier","service","label","markup_flat","markup_percent","position"],"x-typelizer":true},"DeliveryOriginGroup":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"delivery_zones_count":{"type":"number"},"delivery_methods_count":{"type":"number"}},"required":["id","name","position","created_at","updated_at","delivery_profile_id","stock_location_ids","delivery_zones_count","delivery_methods_count"],"x-typelizer":true},"DeliveryProfile":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"default":{"type":"boolean"},"position":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string"},"digital":{"type":"boolean"},"offers_pickup":{"type":"boolean"},"offers_shipping":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}},"origin_groups":{"type":"object"},"products_count":{"type":"number"},"delivery_methods_count":{"type":"number"},"delivery_zones_count":{"type":"number"}},"required":["id","name","default","position","created_at","updated_at","kind","digital","offers_pickup","offers_shipping","stock_location_ids","origin_groups","products_count","delivery_methods_count","delivery_zones_count"],"x-typelizer":true},"DeliveryRate":{"type":"object","properties":{"id":{"type":"string"},"delivery_method_id":{"type":"string"},"name":{"type":"string"},"selected":{"type":"boolean"},"cost":{"type":"string"},"total":{"type":"string"},"additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"carrier":{"type":"string","nullable":true},"service_level":{"type":"string","nullable":true},"estimated_delivery_date":{"type":"string","nullable":true},"display_cost":{"type":"string"},"display_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"delivery_method":{"$ref":"#/components/schemas/DeliveryMethod"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","delivery_method_id","name","selected","cost","total","additional_tax_total","included_tax_total","tax_total","carrier","service_level","estimated_delivery_date","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"member_type":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","member_type","country_code","state_code","postal_code_prefix","postal_code_from","postal_code_to","country_name","state_name","created_at","updated_at"],"x-typelizer":true},"DeliveryZone":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryZoneMember"}},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string"},"delivery_origin_group_id":{"type":"string","nullable":true},"delivery_method_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","created_at","updated_at","delivery_profile_id","delivery_origin_group_id","delivery_method_ids"],"x-typelizer":true},"DigitalLink":{"type":"object","properties":{"id":{"type":"string"},"access_counter":{"type":"number"},"filename":{"type":"string"},"content_type":{"type":"string"},"download_url":{"type":"string"},"authorizable":{"type":"boolean"},"expired":{"type":"boolean"},"access_limit_exceeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","access_counter","filename","content_type","download_url","authorizable","expired","access_limit_exceeded","created_at","updated_at"],"x-typelizer":true},"Discount":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"code":{"type":"string","nullable":true},"value_type":{"type":"string","nullable":true},"value":{"type":"string","nullable":true},"promotion_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","code","value_type","value","promotion_id","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"ExchangeLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"original_price":{"type":"string"},"new_variant_price":{"type":"string"},"price_difference":{"type":"string"},"original_variant_id":{"type":"string","nullable":true},"new_variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"original_variant":{"$ref":"#/components/schemas/Variant"},"new_variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","quantity","received_quantity","resellable","original_price","new_variant_price","price_difference","original_variant_id","new_variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"Exchange":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"price_difference":{"type":"string"},"display_price_difference":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"fulfilled_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"exchange_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ExchangeLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","price_difference","display_price_difference","approved_at","received_at","fulfilled_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id"],"x-typelizer":true},"Export":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"format":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"done":{"type":"boolean"},"filename":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"download_url":{"type":"string","nullable":true}},"required":["id","number","format","created_at","updated_at","type","user_id","done","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","kind","line_item_id","fulfillment_id","amount","display_amount","metadata","created_at","updated_at"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"tracking_carrier":{"type":"string","nullable":true},"tracking_carrier_name":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"cost":{"type":"string"},"display_cost":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"status":{"type":"string"},"fulfillment_type":{"type":"string"},"fulfilled_at":{"type":"string","nullable":true},"tracking_status":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_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"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"tracking_details":{"type":"object","nullable":true},"adjustment_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"documents":{"type":"object"},"provider_generates_labels":{"type":"boolean"},"fulfillment_items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentItem"}},"order":{"$ref":"#/components/schemas/Order"}},"required":["id","number","tracking","tracking_url","tracking_carrier","tracking_carrier_name","pickup_point_data","selected_delivery_rate_id","cost","display_cost","total","display_total","discount_total","display_discount_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","tax_total","display_tax_total","status","fulfillment_type","fulfilled_at","tracking_status","estimated_delivery_at","delivered_at","items","metadata","tracking_details","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","provider_generates_labels"],"x-typelizer":true},"GiftCardBatch":{"type":"object","properties":{"id":{"type":"string"},"codes_count":{"type":"number"},"currency":{"type":"string","nullable":true},"prefix":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true}},"required":["id","codes_count","currency","prefix","created_at","updated_at","amount","expires_at","created_by_id"],"x-typelizer":true},"GiftCard":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_authorized":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"expires_at":{"type":"string","nullable":true},"redeemed_at":{"type":"string","nullable":true},"expired":{"type":"boolean"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"},"gift_card_batch":{"$ref":"#/components/schemas/GiftCardBatch"},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}},"required":["id","code","status","currency","amount","amount_used","amount_authorized","amount_remaining","display_amount","display_amount_used","display_amount_remaining","expires_at","redeemed_at","expired","active","created_at","updated_at","customer_id","created_by_id"],"x-typelizer":true},"ImportMapping":{"type":"object","properties":{"id":{"type":"string"},"schema_field":{"type":"string"},"file_column":{"type":"string","nullable":true},"required":{"type":"boolean"}},"required":["id","schema_field","file_column","required"],"x-typelizer":true},"ImportRow":{"type":"object","properties":{"id":{"type":"string"},"row_number":{"type":"number"},"status":{"type":"string"},"validation_errors":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"import_id":{"type":"string","nullable":true},"item_type":{"type":"string","nullable":true},"item_id":{"type":"string","nullable":true},"data":{"type":"object"}},"required":["id","row_number","status","validation_errors","created_at","updated_at","import_id","item_type","item_id","data"],"x-typelizer":true},"Import":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"rows_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","nullable":true},"status":{"type":"string"},"owner_type":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"user_id":{"type":"string","nullable":true},"processing_errors":{"type":"string","nullable":true},"preferred_delimiter":{"type":"string"},"original_filename":{"type":"string","nullable":true},"original_byte_size":{"type":"number","nullable":true},"original_file_url":{"type":"string","nullable":true},"completed_rows_count":{"type":"number"},"failed_rows_count":{"type":"number"},"schema_fields":{"type":"array","items":{"$ref":"#/components/schemas/ImportSchemaField"}},"csv_headers":{"type":"array","items":{"type":"string"}},"sample_row":{"type":"object"},"mappings":{"type":"array","items":{"$ref":"#/components/schemas/ImportMapping"}}},"required":["id","number","rows_count","created_at","updated_at","type","status","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","original_filename","original_byte_size","original_file_url","completed_rows_count","failed_rows_count","schema_fields","csv_headers","sample_row","mappings"],"x-typelizer":true},"Integration":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"group":{"type":"string","nullable":true},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","active","created_at","updated_at","type","group","preferences","preference_schema"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","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_codes":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"tax_provider":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","currency","default_locale","tax_inclusive","default","country_codes","supported_locales","tax_provider","created_at","updated_at"],"x-typelizer":true},"Media":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string","nullable":true},"variant_ids":{"type":"array","items":{"type":"string"}},"position":{"type":"number"},"alt":{"type":"string","nullable":true},"media_type":{"type":"string"},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"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","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","created_at","updated_at","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"NewsletterSubscriber":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"verified":{"type":"boolean"},"verified_at":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true}},"required":["id","email","created_at","updated_at","verified","verified_at","customer_id"],"x-typelizer":true},"OptionType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"kind":{"type":"string"},"translations":{"type":"object"},"metadata":{"type":"object"},"filterable":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","name","label","position","kind","metadata","filterable","created_at","updated_at"],"x-typelizer":true},"OptionValue":{"type":"object","properties":{"id":{"type":"string"},"option_type_id":{"type":"string"},"name":{"type":"string"},"label":{"type":"string"},"position":{"type":"number"},"color_code":{"type":"string","nullable":true},"option_type_name":{"type":"string"},"option_type_label":{"type":"string"},"image_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"option_type":{"$ref":"#/components/schemas/OptionType"}},"required":["id","option_type_id","name","label","position","color_code","option_type_name","option_type_label","image_url","metadata","created_at","updated_at"],"x-typelizer":true},"OrderRoutingRule":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"label":{"type":"string"},"description":{"type":"string"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"currency":{"type":"string"},"locale":{"type":"string","nullable":true},"total_quantity":{"type":"number"},"coupon_code":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true},"payment_status":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"item_total":{"type":"string"},"display_item_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"tax_total":{"type":"string"},"display_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"gift_card_total":{"type":"string"},"display_gift_card_total":{"type":"string"},"amount_due":{"type":"string"},"display_amount_due":{"type":"string"},"delivery_total":{"type":"string"},"display_delivery_total":{"type":"string"},"fee_total":{"type":"string"},"display_fee_total":{"type":"string"},"store_credit_total":{"type":"string"},"display_store_credit_total":{"type":"string"},"covered_by_store_credit":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/LineItem"}},"fulfillments":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"gift_card":{"allOf":[{"$ref":"#/components/schemas/GiftCard"}],"nullable":true},"market":{"allOf":[{"$ref":"#/components/schemas/Market"}],"nullable":true},"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},"company_location_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"internal_note":{"type":"string","nullable":true},"internal_note_html":{"type":"string","nullable":true},"approver_id":{"type":"string","nullable":true},"canceler_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"cart":{"$ref":"#/components/schemas/Cart"},"channel":{"$ref":"#/components/schemas/Channel"},"preferred_stock_location":{"$ref":"#/components/schemas/StockLocation"},"payment_methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"customer":{"$ref":"#/components/schemas/Customer"},"approver":{"$ref":"#/components/schemas/Customer"},"canceler":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/Customer"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}},"required":["id","market_id","cart_id","channel_id","number","email","customer_note","currency","locale","total_quantity","coupon_code","fulfillment_status","payment_status","completed_at","item_total","display_item_total","adjustment_total","display_adjustment_total","discount_total","display_discount_total","tax_total","display_tax_total","included_tax_total","display_included_tax_total","additional_tax_total","display_additional_tax_total","total","display_total","gift_card_total","display_gift_card_total","amount_due","display_amount_due","delivery_total","display_delivery_total","fee_total","display_fee_total","store_credit_total","display_store_credit_total","covered_by_store_credit","gift_card","market","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","company_location_id","company_id","tags","internal_note","internal_note_html","approver_id","canceler_id","created_by_id","customer_id"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string"},"session_required":{"type":"boolean"},"source_required":{"type":"boolean"},"metadata":{"type":"object"},"active":{"type":"boolean"},"auto_capture":{"type":"boolean","nullable":true},"capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"],"nullable":true},"resolved_capture_method":{"type":"string","enum":["checkout","on_dispatch","manual"]},"storefront_visible":{"type":"boolean"},"position":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","name","description","type","session_required","source_required","metadata","active","auto_capture","capture_method","resolved_capture_method","storefront_visible","position","created_at","updated_at","preferences","preference_schema"],"x-typelizer":true},"Payment":{"type":"object","properties":{"id":{"type":"string"},"payment_method_id":{"type":"string"},"response_code":{"type":"string","nullable":true},"number":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"status":{"type":"string"},"source_type":{"type":"string","nullable":true,"enum":["credit_card","store_credit","payment_source"]},"source_id":{"type":"string","nullable":true},"source":{"anyOf":[{"$ref":"#/components/schemas/CreditCard"},{"$ref":"#/components/schemas/StoreCredit"},{"$ref":"#/components/schemas/PaymentSource"}],"nullable":true},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"metadata":{"type":"object"},"avs_response":{"type":"string","nullable":true},"cvv_response_code":{"type":"string","nullable":true},"cvv_response_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"captured_amount":{"type":"string"},"order_id":{"type":"string","nullable":true},"order":{"$ref":"#/components/schemas/Order"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","payment_method_id","response_code","number","amount","display_amount","status","source_type","source_id","source","metadata","avs_response","cvv_response_code","cvv_response_message","created_at","updated_at","captured_amount","order_id"],"x-typelizer":true},"PaymentSource":{"type":"object","properties":{"id":{"type":"string"},"gateway_payment_profile_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","gateway_payment_profile_id","metadata","created_at","updated_at"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string"},"group":{"type":"string"},"group_label":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"}},"required":["key","resource","kind","group","group_label","label","description"],"x-typelizer":true},"PriceHistory":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_in_cents":{"type":"number"},"currency":{"type":"string"},"display_amount":{"type":"string"},"recorded_at":{"type":"string"},"variant_id":{"type":"string"},"price_id":{"type":"string"},"compare_at_amount":{"type":"string","nullable":true},"created_at":{"type":"string"}},"required":["id","amount","amount_in_cents","currency","display_amount","recorded_at","variant_id","price_id","compare_at_amount","created_at"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string"},"position":{"type":"number"},"match_policy":{"type":"string"},"starts_at":{"type":"string","nullable":true},"ends_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"product_ids":{"type":"array","items":{"type":"string"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","starts_at","ends_at","deleted_at","created_at","updated_at","currently_active","products_count","prices_count","product_ids"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"description":{"type":"string","nullable":true},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}}},"required":["id","created_at","updated_at","type","price_list_id","preferences","preference_schema","label","description"],"x-typelizer":true},"Price":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string","nullable":true},"amount_in_cents":{"type":"number","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"compare_at_amount_in_cents":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"display_amount":{"type":"string","nullable":true},"display_compare_at_amount":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant":{"$ref":"#/components/schemas/Variant"}},"required":["id","amount","amount_in_cents","compare_at_amount","compare_at_amount_in_cents","currency","display_amount","display_compare_at_amount","price_list_id","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"translations":{"type":"object"},"status":{"type":"string"},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductTypeCustomFieldDefinition":{"type":"object","properties":{"id":{"type":"string"},"key":{"type":"string"},"namespace":{"type":"string"},"label":{"type":"string"},"field_type":{"type":"string","enum":["short_text","long_text","rich_text","number","boolean","json"]},"required":{"type":"boolean"},"sort_order":{"type":"number"}},"required":["id","key","namespace","label","field_type","required","sort_order"],"x-typelizer":true},"ProductType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"translations":{"type":"object"},"products_count":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"option_type_ids":{"type":"array","items":{"type":"string"}},"category_ids":{"type":"array","items":{"type":"string"}},"custom_field_definitions":{"type":"array","items":{"$ref":"#/components/schemas/ProductTypeCustomFieldDefinition"}}},"required":["id","name","products_count","created_at","updated_at","delivery_profile_id","option_type_ids","category_ids","custom_field_definitions"],"x-typelizer":true},"PromotionAction":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"calculator":{"allOf":[{"$ref":"#/components/schemas/PromotionActionCalculator"}],"nullable":true},"line_items":{"type":"array","items":{"$ref":"#/components/schemas/PromotionActionLineItem"},"nullable":true}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string"},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"label":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"},"nullable":true},"category_ids":{"type":"array","items":{"type":"string"},"nullable":true},"customer_ids":{"type":"array","items":{"type":"string"},"nullable":true},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"customer_groups":{"type":"array","items":{"$ref":"#/components/schemas/CustomerGroup"}},"countries":{"type":"array","items":{"$ref":"#/components/schemas/Country"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"markets":{"type":"array","items":{"$ref":"#/components/schemas/Market"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","label","product_ids","category_ids","customer_ids"],"x-typelizer":true},"Promotion":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"starts_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"usage_limit":{"type":"number","nullable":true},"match_policy":{"type":"string","enum":["all","any"]},"path":{"type":"string","nullable":true},"kind":{"type":"string","enum":["coupon_code","automatic"]},"multi_codes":{"type":"boolean"},"number_of_codes":{"type":"number","nullable":true},"code_prefix":{"type":"string","nullable":true},"promotion_category_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"action_ids":{"type":"array","items":{"type":"string"}},"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["id","name","description","code","starts_at","expires_at","usage_limit","match_policy","path","kind","multi_codes","number_of_codes","code_prefix","promotion_category_id","metadata","created_at","updated_at","action_ids","rule_ids"],"x-typelizer":true},"RefundReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Refund":{"type":"object","properties":{"id":{"type":"string"},"transaction_id":{"type":"string","nullable":true},"amount":{"type":"string","nullable":true},"payment_id":{"type":"string","nullable":true},"refund_reason_id":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at"],"x-typelizer":true},"ReturnLineItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"received_quantity":{"type":"number"},"resellable":{"type":"boolean"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_item_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"line_item":{"$ref":"#/components/schemas/LineItem"}},"required":["id","quantity","received_quantity","resellable","pre_tax_amount","display_pre_tax_amount","variant_id","line_item_id","fulfillment_item_id","created_at","updated_at"],"x-typelizer":true},"ReturnReason":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"can_be_deleted":{"type":"boolean"}},"required":["id","name","active","created_at","updated_at","can_be_deleted"],"x-typelizer":true},"Return":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"order_id":{"type":"string","nullable":true},"reason_id":{"type":"string","nullable":true},"refund_total":{"type":"string"},"display_refund_total":{"type":"string"},"approved_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"refunded_at":{"type":"string","nullable":true},"canceled_at":{"type":"string","nullable":true},"reason":{"$ref":"#/components/schemas/ReturnReason"},"return_line_items":{"type":"array","items":{"$ref":"#/components/schemas/ReturnLineItem"}},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"refunded_total":{"type":"string"},"refundable_total":{"type":"string"},"order":{"$ref":"#/components/schemas/Order"},"stock_location":{"$ref":"#/components/schemas/StockLocation"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}},"required":["id","number","status","order_id","reason_id","refund_total","display_refund_total","approved_at","received_at","refunded_at","canceled_at","memo","metadata","created_at","updated_at","stock_location_id","created_by_id","refunded_total","refundable_total"],"x-typelizer":true},"Role":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"mutable":{"type":"boolean"},"users_count":{"type":"number"}},"required":["id","name","description","created_at","updated_at","permissions","mutable","users_count"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"type":"string"},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"tax_remittance":{"type":"string"},"payouts_schedule_interval":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"holiday_mode_until":{"type":"string","nullable":true},"terms_accepted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"on_holiday":{"type":"boolean"},"sellable":{"type":"boolean"},"products_count":{"type":"number"},"users_count":{"type":"number"},"billing_address":{"$ref":"#/components/schemas/Address"},"returns_address":{"$ref":"#/components/schemas/Address"}},"required":["id","name","slug","about","about_html","logo_url","square_logo_url","cover_photo_url","status","contact_email","billing_email","tax_remittance","payouts_schedule_interval","metadata","holiday_mode_until","terms_accepted_at","created_at","updated_at","deleted_at","minimum_payout_amount","on_holiday","sellable","products_count","users_count"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"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"},"name":{"type":"string"},"address1":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"zipcode":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"country_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_text":{"type":"string","nullable":true},"pickup_ready_in_minutes":{"type":"number","nullable":true},"pickup_instructions":{"type":"string","nullable":true},"admin_name":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"active":{"type":"boolean"},"default":{"type":"boolean"},"backorderable_default":{"type":"boolean"},"propagate_all_variants":{"type":"boolean"},"kind":{"type":"string"},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","created_at","updated_at"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_item_id":{"type":"string"},"line_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"quantity":{"type":"number"},"expires_at":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","stock_item_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","metadata","created_at","updated_at","source_location_id","destination_location_id"],"x-typelizer":true},"StoreCreditCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"non_expiring":{"type":"boolean"}},"required":["id","name","created_at","updated_at","non_expiring"],"x-typelizer":true},"StoreCredit":{"type":"object","properties":{"id":{"type":"string"},"amount":{"type":"string"},"amount_used":{"type":"string"},"amount_remaining":{"type":"string"},"display_amount":{"type":"string"},"display_amount_used":{"type":"string"},"display_amount_remaining":{"type":"string"},"currency":{"type":"string"},"memo":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"category_id":{"type":"string","nullable":true},"category_name":{"type":"string","nullable":true}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","customer_id","created_by_id","category_id","category_name"],"x-typelizer":true},"Store":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object"},"name":{"type":"string"},"code":{"type":"string"},"preferred_storefront_url":{"type":"string","nullable":true},"default_currency":{"type":"string"},"default_locale":{"type":"string"},"mail_from_address":{"type":"string","nullable":true},"customer_support_email":{"type":"string","nullable":true},"new_order_notifications_email":{"type":"string","nullable":true},"preferred_send_consumer_transactional_emails":{"type":"boolean"},"preferred_admin_locale":{"type":"string","nullable":true},"preferred_timezone":{"type":"string"},"preferred_weight_unit":{"type":"string"},"preferred_default_package_weight":{"type":"number"},"preferred_default_package_length":{"type":"number"},"preferred_default_package_width":{"type":"number"},"preferred_default_package_height":{"type":"number"},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_company_field_enabled":{"type":"boolean"},"preferred_address_requires_company":{"type":"boolean"},"preferred_address_requires_phone":{"type":"boolean"},"preferred_capture_method":{"type":"string"},"preferred_track_inventory_levels":{"type":"boolean"},"preferred_stock_reservations_enabled":{"type":"boolean"},"preferred_track_price_history":{"type":"boolean"},"preferred_show_products_without_price":{"type":"boolean"},"preferred_disable_sku_validation":{"type":"boolean"},"preferred_order_routing_strategy":{"type":"string"},"preferred_document_number_format":{"type":"string"},"preferred_order_number_prefix":{"type":"string"},"preferred_order_number_suffix":{"type":"string"},"preferred_order_number_sequence_start":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"order_number_sequence_started":{"type":"boolean"},"url":{"type":"string"},"api_url":{"type":"string"},"setup_tasks":{"type":"array","items":{"$ref":"#/components/schemas/SetupTask"}},"supported_currencies":{"type":"array","items":{"type":"string"}},"supported_locales":{"type":"array","items":{"type":"string"}},"available_locales":{"type":"array","items":{"type":"string"}},"logo_url":{"type":"string","nullable":true},"mailer_logo_url":{"type":"string","nullable":true}},"required":["id","metadata","name","code","preferred_storefront_url","default_currency","default_locale","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_default_package_weight","preferred_default_package_length","preferred_default_package_width","preferred_default_package_height","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","created_at","updated_at","order_number_sequence_started","url","api_url","setup_tasks","supported_currencies","supported_locales","available_locales","logo_url","mailer_logo_url"],"x-typelizer":true},"TaxCategory":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tax_code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","name","tax_code","description","is_default","created_at","updated_at"],"x-typelizer":true},"TaxExemptionCertificate":{"type":"object","properties":{"id":{"type":"string"},"certificate_number":{"type":"string"},"reason_code":{"type":"string"},"status":{"type":"string"},"issuing_authority":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"issued_at":{"type":"string"},"expires_at":{"type":"string"},"verified_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"company_id":{"type":"string"},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"active":{"type":"boolean"},"lapsed":{"type":"boolean"},"can_be_deleted":{"type":"boolean"},"document_filename":{"type":"string","nullable":true},"document_byte_size":{"type":"number","nullable":true},"document_url":{"type":"string","nullable":true}},"required":["id","certificate_number","reason_code","status","issuing_authority","metadata","issued_at","expires_at","verified_at","created_at","updated_at","company_id","country_code","state_code","active","lapsed","can_be_deleted","document_filename","document_byte_size","document_url"],"x-typelizer":true},"TaxIdentifier":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"validatable":{"type":"boolean"},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true}},"required":["id","kind","value","validation_status","validation_evidence","source","validated_at","created_at","updated_at","validatable","customer_id","cart_id","order_id"],"x-typelizer":true},"TaxLine":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"included":{"type":"boolean"},"rate":{"type":"string"},"tax_rate_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"fee_id":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"provider_id":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"data":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","label","included","rate","tax_rate_id","line_item_id","fulfillment_id","fee_id","amount","display_amount","provider_id","metadata","taxability_reason","country_code","state_code","data","created_at","updated_at"],"x-typelizer":true},"TaxRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"included_in_price":{"type":"boolean"},"show_rate_in_label":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"amount":{"type":"string"},"amount_percentage":{"type":"number","nullable":true},"tax_category_id":{"type":"string","nullable":true},"store_id":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true}},"required":["id","name","included_in_price","show_rate_in_label","metadata","created_at","updated_at","deleted_at","amount","amount_percentage","tax_category_id","store_id","country_code","state_code"],"x-typelizer":true},"Variant":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"sku":{"type":"string","nullable":true},"options_text":{"type":"string"},"track_inventory":{"type":"boolean"},"media_count":{"type":"number"},"preorder_ships_at":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"preorder":{"type":"boolean"},"weight":{"type":"number","nullable":true},"height":{"type":"number","nullable":true},"width":{"type":"number","nullable":true},"depth":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"type":"string","nullable":true},"weight_unit":{"type":"string","nullable":true},"dimensions_unit":{"type":"string","nullable":true},"backorder_limit":{"type":"number","nullable":true},"hs_code":{"type":"string","nullable":true},"country_of_origin":{"type":"string","nullable":true},"customs_description":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","price","original_price","seller_id","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","hs_code","country_of_origin","customs_description","deleted_at","created_at","updated_at","preorderable","tax_category_id","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
diff --git a/packages/dashboard/e2e/products-helpers.ts b/packages/dashboard/e2e/products-helpers.ts
index 43e4c31e6e..56c13e9a24 100644
--- a/packages/dashboard/e2e/products-helpers.ts
+++ b/packages/dashboard/e2e/products-helpers.ts
@@ -123,9 +123,11 @@ export async function clickMediaThumbnailAction(
media: Locator,
action: 'edit' | 'delete',
): Promise<void> {
- const thumb = media.locator('img[src]').first()
+ // Hover the tile itself, not its image — a video with no poster renders an
+ // icon instead, and waiting on an <img> would hang.
+ const thumb = media.locator('[data-slot="media-thumbnail"]').first()
const button = media.getByRole('button', {
- name: action === 'edit' ? /^edit image$/i : /^delete image$/i,
+ name: action === 'edit' ? /^edit media$/i : /^delete image$/i,
})
await thumb.scrollIntoViewIfNeeded()
diff --git a/packages/dashboard/e2e/products-media-video.spec.ts b/packages/dashboard/e2e/products-media-video.spec.ts
new file mode 100644
index 0000000000..3388bc78aa
--- /dev/null
+++ b/packages/dashboard/e2e/products-media-video.spec.ts
@@ -0,0 +1,87 @@
+import * as path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { expect, test } from '@playwright/test'
+import { login } from './helpers'
+import { clickMediaThumbnailAction, createProduct, mediaCard } from './products-helpers'
+
+const FIXTURE_IMAGE = path.join(
+ path.dirname(fileURLToPath(import.meta.url)),
+ 'fixtures/test-image.png',
+)
+
+test.describe('product media — video', () => {
+ test('adds a YouTube video and persists it through save', async ({ page }) => {
+ const creds = await login(page)
+ await createProduct(page, creds.store_id, `E2E Video ${Date.now()}`)
+
+ const media = mediaCard(page)
+ await media.getByRole('button', { name: /add video link/i }).click()
+
+ const dialog = page.getByRole('dialog')
+ await dialog.getByLabel(/video link/i).fill('https://www.youtube.com/watch?v=dQw4w9WgXcQ')
+ await dialog.getByRole('button', { name: /^add video$/i }).click()
+
+ // The tile previews from YouTube's own still, so an image appears without
+ // anything being uploaded.
+ await expect(media.locator('img[src]').first()).toBeVisible({ timeout: 15_000 })
+
+ // Wait for the button to disable — that's the save completing, so the
+ // reload below reads persisted state rather than racing the request.
+ await page.getByRole('button', { name: /save product/i }).click()
+ await expect(page.getByRole('button', { name: /save product/i })).toBeDisabled({
+ timeout: 30_000,
+ })
+ await page.reload()
+
+ // Survives the round trip: the gallery still shows one tile after reload.
+ await expect(media.locator('img[src]').first()).toBeVisible({ timeout: 30_000 })
+ })
+
+ test('gives a video a poster image', async ({ page }) => {
+ const creds = await login(page)
+ await createProduct(page, creds.store_id, `E2E Poster ${Date.now()}`)
+
+ const media = mediaCard(page)
+ await media.getByRole('button', { name: /add video link/i }).click()
+
+ const dialog = page.getByRole('dialog')
+ // Vimeo supplies no thumbnail, so this is the case that needs a poster.
+ await dialog.getByLabel(/video link/i).fill('https://vimeo.com/123456789')
+ await dialog.getByRole('button', { name: /^add video$/i }).click()
+
+ // Open the tile's editor and upload the still.
+ await clickMediaThumbnailAction(media, 'edit')
+ const sheet = page.getByRole('dialog')
+ await sheet.locator('input[type="file"]').setInputFiles(FIXTURE_IMAGE)
+ await expect(sheet.locator('img[src]').first()).toBeVisible({ timeout: 15_000 })
+ await sheet.getByRole('button', { name: /^done$/i }).click()
+
+ // Wait for the button to disable — that's the save completing, so the
+ // reload below reads persisted state rather than racing the request.
+ await page.getByRole('button', { name: /save product/i }).click()
+ await expect(page.getByRole('button', { name: /save product/i })).toBeDisabled({
+ timeout: 30_000,
+ })
+ await page.reload()
+
+ // The poster survives the round trip — the tile renders it after reload.
+ await expect(media.locator('img[src]').first()).toBeVisible({ timeout: 30_000 })
+ })
+
+ test('refuses a link that is not a video', async ({ page }) => {
+ const creds = await login(page)
+ await createProduct(page, creds.store_id, `E2E Bad Video ${Date.now()}`)
+
+ await mediaCard(page)
+ .getByRole('button', { name: /add video link/i })
+ .click()
+
+ const dialog = page.getByRole('dialog')
+ await dialog.getByLabel(/video link/i).fill('https://example.com/clip.mp4')
+ await dialog.getByRole('button', { name: /^add video$/i }).click()
+
+ await expect(dialog.getByText(/youtube or vimeo/i)).toBeVisible()
+ // The dialog stays open — nothing was added.
+ await expect(dialog).toBeVisible()
+ })
+})
diff --git a/packages/dashboard/src/components/spree/products/add-video-dialog.tsx b/packages/dashboard/src/components/spree/products/add-video-dialog.tsx
new file mode 100644
index 0000000000..9cfe503826
--- /dev/null
+++ b/packages/dashboard/src/components/spree/products/add-video-dialog.tsx
@@ -0,0 +1,100 @@
+import {
+ Button,
+ Dialog,
+ DialogBody,
+ DialogContent,
+ DialogFooter,
+ DialogHeader,
+ DialogTitle,
+ Field,
+ FieldDescription,
+ FieldError,
+ FieldLabel,
+ Input,
+} from '@spree/dashboard-ui'
+import { type FormEvent, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { isSupportedVideoUrl } from '../../../lib/video-url'
+
+interface Props {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+ onAdd: (url: string) => void
+}
+
+// Collects a YouTube or Vimeo link. The same check runs again on the server,
+// so this is here to tell the merchant straight away rather than after a save.
+export function AddVideoDialog({ open, onOpenChange, onAdd }: Props) {
+ const { t } = useTranslation()
+ const [url, setUrl] = useState('')
+ const [touched, setTouched] = useState(false)
+
+ const invalid = touched && url.trim().length > 0 && !isSupportedVideoUrl(url)
+
+ const close = () => {
+ setUrl('')
+ setTouched(false)
+ onOpenChange(false)
+ }
+
+ // This dialog renders inside the product form, so the submit must be stopped
+ // here — letting it bubble would save the whole product.
+ const submit = (event: FormEvent<HTMLFormElement>) => {
+ event.preventDefault()
+ event.stopPropagation()
+ setTouched(true)
+ if (!isSupportedVideoUrl(url)) return
+ onAdd(url.trim())
+ close()
+ }
+
+ return (
+ <Dialog
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) close()
+ }}
+ >
+ <DialogContent>
+ <DialogHeader>
+ <DialogTitle>{t('admin.products.media.add_video_title')}</DialogTitle>
+ </DialogHeader>
+
+ <form onSubmit={submit} className="contents">
+ <DialogBody>
+ <Field>
+ <FieldLabel htmlFor="external-video-url">
+ {t('admin.fields.media.external_video_url.label')}
+ </FieldLabel>
+ <Input
+ id="external-video-url"
+ value={url}
+ autoFocus
+ aria-invalid={invalid || undefined}
+ placeholder={t('admin.fields.media.external_video_url.placeholder')}
+ onChange={(e) => setUrl(e.target.value)}
+ onBlur={() => setTouched(true)}
+ />
+ {invalid ? (
+ <FieldError>{t('admin.products.media.video_url_invalid')}</FieldError>
+ ) : (
+ <FieldDescription>
+ {t('admin.fields.media.external_video_url.help')}
+ </FieldDescription>
+ )}
+ </Field>
+ </DialogBody>
+
+ <DialogFooter>
+ <Button type="button" variant="outline" onClick={close}>
+ {t('admin.actions.cancel')}
+ </Button>
+ <Button type="submit" disabled={url.trim().length === 0}>
+ {t('admin.products.media.add_video_submit')}
+ </Button>
+ </DialogFooter>
+ </form>
+ </DialogContent>
+ </Dialog>
+ )
+}
diff --git a/packages/dashboard/src/components/spree/products/media-edit-sheet.tsx b/packages/dashboard/src/components/spree/products/media-edit-sheet.tsx
index 50d7007d9c..b959deeaac 100644
--- a/packages/dashboard/src/components/spree/products/media-edit-sheet.tsx
+++ b/packages/dashboard/src/components/spree/products/media-edit-sheet.tsx
@@ -1,9 +1,11 @@
import type { Variant } from '@spree/admin-sdk'
-import { useTranslation } from '@spree/dashboard-core'
+import { ImageUploadField, useTranslation } from '@spree/dashboard-core'
import {
Button,
Field,
+ FieldError,
FieldLabel,
+ Input,
Sheet,
SheetContent,
SheetFooter,
@@ -12,11 +14,25 @@ import {
Textarea,
} from '@spree/dashboard-ui'
import i18n from 'i18next'
-import { CheckIcon, ImagePlusIcon } from 'lucide-react'
+import { CheckIcon, FilmIcon, ImagePlusIcon } from 'lucide-react'
import { useCallback, useEffect, useRef } from 'react'
import type { UseFormReturn } from 'react-hook-form'
+import { parseVideoUrl } from '../../../lib/video-url'
import type { ProductFormValues } from '../../../schemas/product'
+// The fields this sheet edits. Snapshot, cancel-restore and the type all derive
+// from this one list, so a new editable field can't reach the form and then be
+// missed by the restore — which would silently keep an edit the merchant cancelled.
+const EDITED_FIELDS = [
+ 'alt',
+ 'variant_ids',
+ 'external_video_url',
+ 'focal_point_x',
+ 'focal_point_y',
+ 'poster_signed_id',
+ 'posterUrl',
+] as const
+
interface Props {
// eslint-disable-next-line @typescript-eslint/no-explicit-any
form: UseFormReturn<ProductFormValues, any, any>
@@ -43,11 +59,8 @@ export function MediaEditSheet({ form, mediaIndex, variants, open, onOpenChange
// freshly-uploaded row that has no id yet we fall back to the current
// index — uploads don't surface a drag handle so the race is impossible.
type MediaRow = NonNullable<ProductFormValues['media']>[number]
- const snapshotRef = useRef<{
- alt: string | null
- variant_ids: string[]
- key: string | null
- } | null>(null)
+ type Snapshot = Pick<MediaRow, (typeof EDITED_FIELDS)[number]> & { key: string | null }
+ const snapshotRef = useRef<Snapshot | null>(null)
const rowKey = useCallback(
(m: MediaRow): string | null => m.id ?? m.signed_id ?? m.uploadId ?? null,
[],
@@ -62,7 +75,14 @@ export function MediaEditSheet({ form, mediaIndex, variants, open, onOpenChange
const row = current[mediaIndex]
if (!row) return
snapshotRef.current = {
- alt: row.alt ?? null,
+ // Copy each value as-is. Normalizing to null would turn an absent
+ // `poster_signed_id` — typed string | undefined — into a value the
+ // schema rejects, so cancelling would break the next save.
+ ...(Object.fromEntries(EDITED_FIELDS.map((field) => [field, row[field]])) as Pick<
+ MediaRow,
+ (typeof EDITED_FIELDS)[number]
+ >),
+ // Copy the array — the snapshot must not alias the row's own value.
variant_ids: [...(row.variant_ids ?? [])],
key: rowKey(row),
}
@@ -71,6 +91,8 @@ export function MediaEditSheet({ form, mediaIndex, variants, open, onOpenChange
const entry = form.watch(`media.${mediaIndex}`)
if (!entry) return null
+ // For an image this is the picture itself; for a hosted video it is the file
+ // the merchant just picked (a blob URL) or the URL the API serves it at.
const previewUrl = entry.previewUrl ?? null
const alt = entry.alt ?? ''
const selectedVariantIds = new Set(entry.variant_ids ?? [])
@@ -79,6 +101,76 @@ export function MediaEditSheet({ form, mediaIndex, variants, open, onOpenChange
form.setValue(`media.${mediaIndex}.alt`, value, { shouldDirty: true })
}
+ const mediaType = entry.media_type ?? 'image'
+ const isImage = mediaType === 'image'
+ const isHostedVideo = mediaType === 'video'
+ const isExternalVideo = mediaType === 'external_video'
+ // Mirrors Spree::Media#playable_video? — both kinds want a poster.
+ const isVideo = isHostedVideo || isExternalVideo
+ const externalVideoUrl = entry.external_video_url ?? ''
+ // The video file itself — a blob URL before save, the served file after.
+ const videoUrl = entry.videoUrl ?? null
+ const parsedVideo = parseVideoUrl(externalVideoUrl)
+ const videoUrlInvalid = externalVideoUrl.length > 0 && !parsedVideo
+
+ const focalPoint =
+ entry.focal_point_x != null && entry.focal_point_y != null
+ ? { x: entry.focal_point_x, y: entry.focal_point_y }
+ : null
+
+ const setExternalVideoUrl = (value: string) => {
+ form.setValue(`media.${mediaIndex}.external_video_url`, value, { shouldDirty: true })
+ }
+
+ // Click the image where it should stay in frame when a storefront crops it.
+ const handleFocalPointClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+ if (!isImage) return
+
+ const bounds = event.currentTarget.getBoundingClientRect()
+ if (bounds.width === 0 || bounds.height === 0) return
+
+ const round = (value: number) => Math.round(Math.min(1, Math.max(0, value)) * 1000) / 1000
+
+ form.setValue(
+ `media.${mediaIndex}.focal_point_x`,
+ round((event.clientX - bounds.left) / bounds.width),
+ { shouldDirty: true },
+ )
+ form.setValue(
+ `media.${mediaIndex}.focal_point_y`,
+ round((event.clientY - bounds.top) / bounds.height),
+ { shouldDirty: true },
+ )
+ }
+
+ // The poster is a still the merchant supplies for a video. YouTube provides
+ // one, so this is how the other cases — Vimeo, uploaded files — get a tile
+ // that isn't blank.
+ const posterValue = {
+ signedId: entry.poster_signed_id ?? null,
+ previewUrl: entry.posterUrl ?? null,
+ cleared: entry.poster_signed_id === '',
+ }
+
+ const setPoster = (value: {
+ signedId: string | null
+ previewUrl: string | null
+ cleared: boolean
+ }) => {
+ // An empty string is how the API is told to drop the poster; `undefined`
+ // would fall out of the request body and leave the old one in place.
+ const next = value.cleared ? '' : (value.signedId ?? undefined)
+ form.setValue(`media.${mediaIndex}.poster_signed_id`, next, { shouldDirty: true })
+ form.setValue(`media.${mediaIndex}.posterUrl`, value.cleared ? null : value.previewUrl, {
+ shouldDirty: true,
+ })
+ }
+
+ const clearFocalPoint = () => {
+ form.setValue(`media.${mediaIndex}.focal_point_x`, null, { shouldDirty: true })
+ form.setValue(`media.${mediaIndex}.focal_point_y`, null, { shouldDirty: true })
+ }
+
const toggleVariant = (variantId: string) => {
const next = new Set(selectedVariantIds)
if (next.has(variantId)) next.delete(variantId)
@@ -100,24 +192,16 @@ export function MediaEditSheet({ form, mediaIndex, variants, open, onOpenChange
if (found === -1) return onOpenChange(false)
targetIndex = found
}
- // Restore the two fields the sheet writes to (`alt`, `variant_ids`)
- // from the open-time snapshot. We deliberately scope to those keys
- // rather than overwriting the whole `media` array — a sibling card
- // might have appended a new upload while the sheet was open.
- //
- // Use setValue with `shouldDirty: false` to write the snapshot
- // value back; the UI updates immediately via the form.watch
- // subscriptions. We accept that the parent form's isDirty bit may
- // stay true if the user typed and then cancelled (it'll clear on
- // the parent form's Save round-trip).
- form.setValue(`media.${targetIndex}.alt`, snap.alt, {
- shouldDirty: false,
- shouldTouch: false,
- })
- form.setValue(`media.${targetIndex}.variant_ids`, snap.variant_ids, {
- shouldDirty: false,
- shouldTouch: false,
- })
+ // Restore only the fields the sheet writes to — a sibling card might have
+ // appended a new upload while the sheet was open, so overwriting the whole
+ // `media` array would drop it. The parent form's isDirty bit may stay true
+ // after a cancel; it clears on the next Save round-trip.
+ for (const field of EDITED_FIELDS) {
+ form.setValue(`media.${targetIndex}.${field}`, snap[field], {
+ shouldDirty: false,
+ shouldTouch: false,
+ })
+ }
}
onOpenChange(false)
}
@@ -130,15 +214,81 @@ export function MediaEditSheet({ form, mediaIndex, variants, open, onOpenChange
</SheetHeader>
<div className="flex-1 overflow-y-auto p-4 flex flex-col gap-5">
- <div className="group relative overflow-hidden rounded-lg border border-border bg-muted">
- {previewUrl ? (
- <img src={previewUrl} alt={alt} className="w-full max-h-[60vh] object-contain" />
- ) : (
- <div className="flex aspect-square w-full items-center justify-center text-muted-foreground">
- <ImagePlusIcon className="size-8" />
- </div>
- )}
- </div>
+ {isExternalVideo && parsedVideo ? (
+ <div className="aspect-video w-full shrink-0 overflow-hidden rounded-lg border border-border bg-black">
+ <iframe
+ src={parsedVideo.embedUrl}
+ title={alt || t('admin.products.media.video_preview_title')}
+ allowFullScreen
+ className="size-full"
+ />
+ </div>
+ ) : isHostedVideo && videoUrl ? (
+ // biome-ignore lint/a11y/useMediaCaption: merchant-supplied product footage has no track
+ <video
+ src={videoUrl}
+ controls
+ className="max-h-[60vh] w-full shrink-0 rounded-lg bg-black"
+ />
+ ) : (
+ <button
+ type="button"
+ disabled={!isImage || !previewUrl}
+ onClick={handleFocalPointClick}
+ className="group relative block w-full shrink-0 overflow-hidden rounded-lg border border-border bg-muted disabled:cursor-default"
+ >
+ {previewUrl ? (
+ <>
+ <img src={previewUrl} alt={alt} className="w-full max-h-[60vh] object-contain" />
+ {isImage && focalPoint && (
+ <span
+ aria-hidden
+ className="pointer-events-none absolute size-5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white shadow-[0_0_0_2px_rgba(0,0,0,0.4)]"
+ style={{
+ left: `${focalPoint.x * 100}%`,
+ top: `${focalPoint.y * 100}%`,
+ }}
+ />
+ )}
+ </>
+ ) : (
+ <div className="flex aspect-square w-full items-center justify-center text-muted-foreground">
+ {isImage ? <ImagePlusIcon className="size-8" /> : <FilmIcon className="size-8" />}
+ </div>
+ )}
+ </button>
+ )}
+
+ {isImage && previewUrl && (
+ <div className="flex items-center justify-between gap-2 -mt-3">
+ <p className="text-xs text-muted-foreground">
+ {t('admin.products.media.focal_point_help')}
+ </p>
+ {focalPoint && (
+ <Button type="button" variant="ghost" size="sm" onClick={clearFocalPoint}>
+ {t('admin.products.media.focal_point_reset')}
+ </Button>
+ )}
+ </div>
+ )}
+
+ {isExternalVideo && (
+ <Field>
+ <FieldLabel htmlFor="media-video-url">
+ {t('admin.fields.media.external_video_url.label')}
+ </FieldLabel>
+ <Input
+ id="media-video-url"
+ value={externalVideoUrl}
+ aria-invalid={videoUrlInvalid || undefined}
+ onChange={(e) => setExternalVideoUrl(e.target.value)}
+ placeholder={t('admin.fields.media.external_video_url.placeholder')}
+ />
+ {videoUrlInvalid && (
+ <FieldError>{t('admin.products.media.video_url_invalid')}</FieldError>
+ )}
+ </Field>
+ )}
<Field>
<FieldLabel htmlFor="media-alt">{t('admin.fields.media.alt.label')}</FieldLabel>
@@ -151,6 +301,17 @@ export function MediaEditSheet({ form, mediaIndex, variants, open, onOpenChange
/>
</Field>
+ {isVideo && (
+ <Field>
+ <FieldLabel>{t('admin.fields.media.poster.label')}</FieldLabel>
+ <ImageUploadField
+ value={posterValue}
+ onChange={setPoster}
+ help={t('admin.fields.media.poster.help')}
+ />
+ </Field>
+ )}
+
{variants.length > 0 && (
<Field>
<FieldLabel>{t('admin.products.media.assigned_variants_label')}</FieldLabel>
diff --git a/packages/dashboard/src/components/spree/products/product-form-cards.tsx b/packages/dashboard/src/components/spree/products/product-form-cards.tsx
index cb4b787066..b08bcc85b5 100644
--- a/packages/dashboard/src/components/spree/products/product-form-cards.tsx
+++ b/packages/dashboard/src/components/spree/products/product-form-cards.tsx
@@ -39,7 +39,7 @@ import {
Textarea,
useConfirm,
} from '@spree/dashboard-ui'
-import { ImagePlusIcon, Loader2Icon, PencilIcon, TrashIcon } from 'lucide-react'
+import { FilmIcon, ImagePlusIcon, Loader2Icon, PencilIcon, PlayIcon, TrashIcon } from 'lucide-react'
import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
import { Controller, type UseFormReturn, useWatch } from 'react-hook-form'
import { useTranslation } from 'react-i18next'
@@ -51,8 +51,10 @@ import { useOptionTypesByIds } from '../../../hooks/use-option-types'
import { useDeleteProductMedia } from '../../../hooks/use-product-media'
import { useProductType, useProductTypes } from '../../../hooks/use-product-types'
import { useTaxCategories } from '../../../hooks/use-tax-categories'
-import type { ProductFormValues } from '../../../schemas/product'
+import { parseVideoUrl } from '../../../lib/video-url'
+import type { MediaType, ProductFormValues } from '../../../schemas/product'
import { ProductBulkPriceEditor } from '../bulk-price-editor/product-bulk-price-editor'
+import { AddVideoDialog } from './add-video-dialog'
import { InventorySection } from './inventory-section'
import { MediaEditSheet } from './media-edit-sheet'
import { VariantsSection } from './variants-section'
@@ -165,6 +167,17 @@ interface PendingUpload {
progress: 'uploading' | 'attaching' | 'done' | 'error'
}
+// What the gallery accepts. `accept` on the file input only constrains the OS
+// picker — a drop bypasses it entirely, so handleDrop filters against the same
+// list or an unsupported file uploads and then fails the whole product save.
+const ACCEPTED_MEDIA = ['image/', 'video/mp4', 'video/webm', 'video/quicktime']
+
+function isAcceptedMedia(file: File): boolean {
+ return ACCEPTED_MEDIA.some((type) =>
+ type.endsWith('/') ? file.type.startsWith(type) : file.type === type,
+ )
+}
+
// Unified, form-backed media card. Single source of truth: form.media.
// Both new and edit pages use the same component; the only difference is
// whether form.media starts empty (new) or pre-hydrated from the persisted
@@ -192,6 +205,7 @@ export function MediaCard({
const confirm = useConfirm()
const [pending, setPending] = useState<PendingUpload[]>([])
const [editingIndex, setEditingIndex] = useState<number | null>(null)
+ const [addingVideo, setAddingVideo] = useState(false)
const fileInputRef = useRef<HTMLInputElement>(null)
const items = useWatch({ control: form.control, name: 'media' }) ?? []
@@ -247,7 +261,12 @@ export function MediaCard({
signed_id: result.signedId,
alt: file.name,
position: current.length + 1,
+ media_type: file.type.startsWith('video/')
+ ? ('video' as const)
+ : ('image' as const),
previewUrl: preview,
+ // Lets an uploaded video play in the editor before it is saved.
+ videoUrl: file.type.startsWith('video/') ? preview : null,
uploadId,
},
],
@@ -270,15 +289,42 @@ export function MediaCard({
const handleDrop = useCallback(
(e: React.DragEvent) => {
e.preventDefault()
- if (e.dataTransfer.files.length > 0) handleFiles(e.dataTransfer.files)
+ const accepted = Array.from(e.dataTransfer.files).filter(isAcceptedMedia)
+ const rejected = e.dataTransfer.files.length - accepted.length
+
+ if (rejected > 0) toast.error(t('admin.products.media.unsupported_file', { count: rejected }))
+ if (accepted.length > 0) handleFiles(accepted)
},
- [handleFiles],
+ [handleFiles, t],
)
const handleDragOver = useCallback((e: React.DragEvent) => {
e.preventDefault()
}, [])
+ // An external video has no file to upload — it goes straight into form state
+ // with its link, and the provider's own still stands in as the preview.
+ const handleAddVideo = useCallback(
+ (url: string) => {
+ const current = form.getValues('media') ?? []
+ form.setValue(
+ 'media',
+ [
+ ...current,
+ {
+ media_type: 'external_video' as const,
+ external_video_url: url,
+ position: current.length + 1,
+ previewUrl: parseVideoUrl(url)?.thumbnailUrl ?? undefined,
+ uploadId: crypto.randomUUID(),
+ },
+ ],
+ { shouldDirty: true },
+ )
+ },
+ [form],
+ )
+
const handleDelete = useCallback(
async (index: number) => {
const current = form.getValues('media') ?? []
@@ -356,6 +402,7 @@ export function MediaCard({
sortableId={sortableIds[index]}
previewUrl={media.previewUrl ?? null}
alt={media.alt ?? ''}
+ mediaType={media.media_type ?? 'image'}
onEdit={() => setEditingIndex(index)}
onDelete={() => handleDelete(index)}
/>
@@ -365,11 +412,21 @@ export function MediaCard({
key={upload.id}
className="relative aspect-square overflow-hidden rounded-lg border border-border bg-muted"
>
- <img
- src={upload.preview}
- alt=""
- className="size-full object-cover opacity-60"
- />
+ {upload.file.type.startsWith('video/') ? (
+ <video
+ src={upload.preview}
+ muted
+ playsInline
+ preload="metadata"
+ className="size-full object-cover opacity-60"
+ />
+ ) : (
+ <img
+ src={upload.preview}
+ alt=""
+ className="size-full object-cover opacity-60"
+ />
+ )}
<div className="absolute inset-0 flex items-center justify-center">
{upload.progress === 'error' ? (
<span className="text-xs text-destructive font-medium">
@@ -402,13 +459,26 @@ export function MediaCard({
<input
ref={fileInputRef}
type="file"
- accept="image/*"
+ accept={ACCEPTED_MEDIA.map((type) => (type.endsWith('/') ? `${type}*` : type)).join(
+ ',',
+ )}
multiple
className="hidden"
onChange={(e) => e.target.files && handleFiles(e.target.files)}
/>
+
+ <Button
+ type="button"
+ variant="outline"
+ className="self-start"
+ onClick={() => setAddingVideo(true)}
+ >
+ <FilmIcon />
+ {t('admin.products.media.add_video')}
+ </Button>
</CardContent>
</Card>
+ <AddVideoDialog open={addingVideo} onOpenChange={setAddingVideo} onAdd={handleAddVideo} />
{editingEntry && editingIndex !== null && (
<MediaEditSheet
form={form}
@@ -428,12 +498,14 @@ function SortableMediaThumbnail({
sortableId,
previewUrl,
alt,
+ mediaType,
onEdit,
onDelete,
}: {
sortableId: string
previewUrl: string | null
alt: string
+ mediaType: MediaType
onEdit: () => void
onDelete: () => void
}) {
@@ -451,13 +523,24 @@ function SortableMediaThumbnail({
<div
ref={setNodeRef}
style={style}
+ data-slot="media-thumbnail"
{...attributes}
{...listeners}
className={`group relative aspect-square cursor-grab overflow-hidden rounded-md border border-border bg-muted touch-none active:cursor-grabbing ${
isDragging ? 'opacity-40 ring-2 ring-primary/40' : ''
}`}
>
- {previewUrl ? (
+ {previewUrl && mediaType === 'video' ? (
+ // An uploaded video has no still until a poster is set, so its own
+ // first frame stands in — an <img> would render a broken icon.
+ <video
+ src={previewUrl}
+ muted
+ playsInline
+ preload="metadata"
+ className="pointer-events-none size-full object-cover"
+ />
+ ) : previewUrl ? (
<img
src={previewUrl}
alt={alt}
@@ -466,10 +549,20 @@ function SortableMediaThumbnail({
/>
) : (
<div className="flex size-full items-center justify-center text-muted-foreground">
- <ImagePlusIcon className="size-6" />
+ {mediaType === 'image' ? (
+ <ImagePlusIcon className="size-6" />
+ ) : (
+ <FilmIcon className="size-6" />
+ )}
</div>
)}
+ {mediaType !== 'image' && (
+ <span className="pointer-events-none absolute left-1.5 top-1.5 z-10 flex size-6 items-center justify-center rounded-full bg-black/60 text-white">
+ <PlayIcon className="size-3 fill-current" />
+ </span>
+ )}
+
<div className="pointer-events-none absolute inset-x-0 bottom-0 z-10 flex justify-end gap-1 p-1.5 opacity-0 translate-y-1 transition-all duration-200 ease-out group-hover:pointer-events-auto group-hover:opacity-100 group-hover:translate-y-0 group-focus-within:pointer-events-auto group-focus-within:opacity-100 group-focus-within:translate-y-0">
<Button
type="button"
diff --git a/packages/dashboard/src/components/spree/products/variant-media-picker.tsx b/packages/dashboard/src/components/spree/products/variant-media-picker.tsx
deleted file mode 100644
index 99fa545cc7..0000000000
--- a/packages/dashboard/src/components/spree/products/variant-media-picker.tsx
+++ /dev/null
@@ -1,158 +0,0 @@
-import {
- Button,
- Dialog,
- DialogBody,
- DialogContent,
- DialogFooter,
- DialogHeader,
- DialogTitle,
-} from '@spree/dashboard-ui'
-import { CheckIcon, ImagePlusIcon, Loader2Icon } from 'lucide-react'
-import { useMemo, useState } from 'react'
-import { useTranslation } from 'react-i18next'
-import { useProductMedia, useUpdateProductMedia } from '../../../hooks/use-product-media'
-import { useVariantMedia } from '../../../hooks/use-variant-media'
-
-type Props = {
- productId: string
- variantId: string
- triggerLabel?: string
- triggerVariant?: 'default' | 'outline' | 'ghost' | 'destructive' | 'link'
-}
-
-export function VariantMediaPicker({
- productId,
- variantId,
- triggerLabel,
- triggerVariant = 'outline',
-}: Props) {
- const { t } = useTranslation()
- const resolvedTriggerLabel = triggerLabel ?? t('admin.products.variant_media_picker.trigger')
- const [open, setOpen] = useState(false)
- const [selectedMediaIds, setSelectedMediaIds] = useState<Set<string>>(new Set())
-
- const productMediaQuery = useProductMedia(productId)
- const variantMediaQuery = useVariantMedia(productId, variantId)
- const updateMedia = useUpdateProductMedia(productId)
-
- const productMedia = productMediaQuery.data?.data ?? []
- const variantLinkedMediaIds = useMemo(
- () => new Set((variantMediaQuery.data?.data ?? []).map((m) => m.id)),
- [variantMediaQuery.data],
- )
-
- const linkable = productMedia.filter((m) => !variantLinkedMediaIds.has(m.id))
-
- const toggle = (mediaId: string) => {
- setSelectedMediaIds((prev) => {
- const next = new Set(prev)
- if (next.has(mediaId)) {
- next.delete(mediaId)
- } else {
- next.add(mediaId)
- }
- return next
- })
- }
-
- const handleAdd = async () => {
- await Promise.all(
- Array.from(selectedMediaIds).map((mediaId) => {
- const asset = productMedia.find((m) => m.id === mediaId)
- const next = new Set(asset?.variant_ids ?? [])
- next.add(variantId)
- return updateMedia.mutateAsync({ id: mediaId, variant_ids: Array.from(next) })
- }),
- )
- setSelectedMediaIds(new Set())
- setOpen(false)
- }
-
- return (
- <>
- <Button variant={triggerVariant} size="sm" onClick={() => setOpen(true)}>
- {resolvedTriggerLabel}
- </Button>
- <Dialog open={open} onOpenChange={setOpen}>
- <DialogContent className="max-w-2xl">
- <DialogHeader>
- <DialogTitle>{t('admin.products.variant_media_picker.title')}</DialogTitle>
- </DialogHeader>
- <DialogBody>
- {productMediaQuery.isLoading ? (
- <div className="flex items-center justify-center py-12 text-muted-foreground">
- <Loader2Icon className="size-5 animate-spin" />
- </div>
- ) : linkable.length === 0 ? (
- <div className="flex flex-col items-center justify-center gap-2 py-12 text-muted-foreground">
- <ImagePlusIcon className="size-6" />
- <p className="text-sm">
- {productMedia.length === 0
- ? t('admin.products.variant_media_picker.empty_no_media')
- : t('admin.products.variant_media_picker.empty_all_linked')}
- </p>
- </div>
- ) : (
- <div className="grid grid-cols-3 gap-3 sm:grid-cols-4">
- {linkable.map((mediaItem) => {
- const selected = selectedMediaIds.has(mediaItem.id)
- const url = mediaItem.small_url || mediaItem.mini_url || mediaItem.original_url
- return (
- <button
- key={mediaItem.id}
- type="button"
- onClick={() => toggle(mediaItem.id)}
- aria-pressed={selected}
- className={`group relative aspect-square overflow-hidden rounded-lg border-2 transition-colors ${
- selected ? 'border-primary' : 'border-border hover:border-muted-foreground'
- }`}
- >
- {url ? (
- <img
- src={url}
- alt={mediaItem.alt ?? ''}
- className="size-full object-cover"
- />
- ) : (
- <div className="flex size-full items-center justify-center bg-muted text-muted-foreground">
- <ImagePlusIcon className="size-6" />
- </div>
- )}
- {selected && (
- <span className="absolute top-1.5 right-1.5 inline-flex items-center justify-center rounded-full bg-primary text-primary-foreground size-5 shadow-sm">
- <CheckIcon className="size-3" />
- </span>
- )}
- </button>
- )
- })}
- </div>
- )}
- </DialogBody>
- <DialogFooter>
- <Button variant="ghost" onClick={() => setOpen(false)}>
- {t('admin.actions.cancel')}
- </Button>
- <Button
- onClick={handleAdd}
- disabled={selectedMediaIds.size === 0 || updateMedia.isPending}
- >
- {updateMedia.isPending ? (
- <>
- <Loader2Icon className="size-4 animate-spin" />
- {t('admin.actions.adding')}
- </>
- ) : selectedMediaIds.size > 0 ? (
- t('admin.products.variant_media_picker.add_count', {
- count: selectedMediaIds.size,
- })
- ) : (
- t('admin.actions.add')
- )}
- </Button>
- </DialogFooter>
- </DialogContent>
- </Dialog>
- </>
- )
-}
diff --git a/packages/dashboard/src/hooks/use-product-media.ts b/packages/dashboard/src/hooks/use-product-media.ts
index 838562b202..eb826904cc 100644
--- a/packages/dashboard/src/hooks/use-product-media.ts
+++ b/packages/dashboard/src/hooks/use-product-media.ts
@@ -1,4 +1,4 @@
-import type { Media } from '@spree/admin-sdk'
+import type { Media, MediaCreateParams, MediaUpdateParams } from '@spree/admin-sdk'
import { adminClient, useResourceKey, useResourceKeyBuilder } from '@spree/dashboard-core'
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
@@ -17,12 +17,7 @@ export function useCreateProductMedia(productId: string) {
const buildKey = useResourceKeyBuilder()
return useMutation({
- mutationFn: (params: {
- signed_id: string
- alt?: string
- position?: number
- variant_ids?: string[]
- }) => adminClient.products.media.create(productId, params),
+ mutationFn: (params: MediaCreateParams) => adminClient.products.media.create(productId, params),
onSuccess: (_data, variables) => {
queryClient.invalidateQueries({ queryKey: buildKey('products', productId, 'media') })
queryClient.invalidateQueries({ queryKey: buildKey('products', productId) })
@@ -39,15 +34,8 @@ export function useUpdateProductMedia(productId: string) {
const queryKey = buildKey('products', productId, 'media')
return useMutation({
- mutationFn: ({
- id,
- ...params
- }: {
- id: string
- alt?: string
- position?: number
- variant_ids?: string[]
- }) => adminClient.products.media.update(productId, id, params),
+ mutationFn: ({ id, ...params }: MediaUpdateParams & { id: string }) =>
+ adminClient.products.media.update(productId, id, params),
// Optimistically splice on `position` change — server-side acts_as_list
// shifts siblings, so the post-success refetch will match.
diff --git a/packages/dashboard/src/hooks/use-variant-media.ts b/packages/dashboard/src/hooks/use-variant-media.ts
deleted file mode 100644
index 3cab305530..0000000000
--- a/packages/dashboard/src/hooks/use-variant-media.ts
+++ /dev/null
@@ -1,12 +0,0 @@
-import { adminClient, useResourceKey } from '@spree/dashboard-core'
-import { useQuery } from '@tanstack/react-query'
-
-// Lists media linked to a variant. Mutations go through useUpdateProductMedia
-// with `variant_ids` — there's no variant-scoped mutation endpoint.
-export function useVariantMedia(productId: string, variantId: string) {
- return useQuery({
- queryKey: useResourceKey('products', productId, 'variants', variantId, 'media'),
- queryFn: () => adminClient.products.variants.media.list(productId, variantId),
- enabled: !!productId && !!variantId,
- })
-}
diff --git a/packages/dashboard/src/lib/video-url.test.ts b/packages/dashboard/src/lib/video-url.test.ts
new file mode 100644
index 0000000000..405591fabb
--- /dev/null
+++ b/packages/dashboard/src/lib/video-url.test.ts
@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest'
+import { isSupportedVideoUrl, parseVideoUrl } from './video-url'
+
+describe('parseVideoUrl', () => {
+ it.each([
+ 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+ 'https://m.youtube.com/watch?v=dQw4w9WgXcQ&t=42',
+ 'https://youtu.be/dQw4w9WgXcQ',
+ 'https://www.youtube.com/embed/dQw4w9WgXcQ',
+ 'https://www.youtube.com/shorts/dQw4w9WgXcQ',
+ ])('reads the YouTube link %s', (url) => {
+ expect(parseVideoUrl(url)).toEqual({
+ provider: 'youtube',
+ videoId: 'dQw4w9WgXcQ',
+ embedUrl: 'https://www.youtube.com/embed/dQw4w9WgXcQ',
+ thumbnailUrl: 'https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg',
+ })
+ })
+
+ it.each([
+ 'https://vimeo.com/123456789',
+ 'https://player.vimeo.com/video/123456789',
+ 'https://vimeo.com/channels/staffpicks/123456789',
+ ])('reads the Vimeo link %s', (url) => {
+ expect(parseVideoUrl(url)).toEqual({
+ provider: 'vimeo',
+ videoId: '123456789',
+ embedUrl: 'https://player.vimeo.com/video/123456789',
+ thumbnailUrl: null,
+ })
+ })
+
+ // Mirrors the Ruby spec of the same name — the two parsers must agree, or
+ // the dialog accepts a link the server rejects.
+ it('accepts a trailing slash, as an address-bar copy carries', () => {
+ expect(parseVideoUrl('https://youtu.be/dQw4w9WgXcQ/')?.videoId).toBe('dQw4w9WgXcQ')
+ expect(parseVideoUrl('https://vimeo.com/123456789/')?.videoId).toBe('123456789')
+ })
+
+ it('ignores surrounding whitespace', () => {
+ expect(parseVideoUrl(' https://vimeo.com/123456789 ')?.videoId).toBe('123456789')
+ })
+
+ it.each([
+ // Not videos: a channel, a handle, an arbitrary nested path, or a short
+ // link with anything after the id.
+ 'https://www.youtube.com/c/dQw4w9WgXcQ',
+ 'https://www.youtube.com/not-a-video/ABCDEFGHIJK',
+ 'https://youtu.be/dQw4w9WgXcQ/extra',
+ 'https://example.com/video.mp4',
+ 'https://www.youtube.com/watch?v=short',
+ 'https://vimeo.com/not-a-number',
+ 'javascript:alert(1)',
+ 'not a url',
+ '',
+ null,
+ undefined,
+ ])('returns null for %s', (url) => {
+ expect(parseVideoUrl(url)).toBeNull()
+ })
+})
+
+describe('isSupportedVideoUrl', () => {
+ it('accepts a link Spree can embed', () => {
+ expect(isSupportedVideoUrl('https://vimeo.com/123456789')).toBe(true)
+ })
+
+ it('rejects anything else', () => {
+ expect(isSupportedVideoUrl('https://example.com/clip.mp4')).toBe(false)
+ })
+})
diff --git a/packages/dashboard/src/lib/video-url.ts b/packages/dashboard/src/lib/video-url.ts
new file mode 100644
index 0000000000..eda6cfe3ba
--- /dev/null
+++ b/packages/dashboard/src/lib/video-url.ts
@@ -0,0 +1,83 @@
+// Mirror of Spree::ExternalVideo on the server. The server is the authority —
+// this exists so the merchant learns a link is unusable while typing it, not
+// after a failed save.
+
+const YOUTUBE_HOSTS = [
+ 'youtube.com',
+ 'www.youtube.com',
+ 'm.youtube.com',
+ 'youtu.be',
+ 'www.youtu.be',
+]
+const VIMEO_HOSTS = ['vimeo.com', 'www.vimeo.com', 'player.vimeo.com']
+
+// Path shapes that actually carry a video id. Anything else on the domain —
+// /c/name, /@handle, /playlist — is not a video. Mirrors Spree::ExternalVideo.
+const YOUTUBE_ID_PATHS = ['embed', 'shorts', 'live', 'v']
+
+const YOUTUBE_ID = /^[\w-]{11}$/
+const VIMEO_ID = /^\d+$/
+
+export interface ParsedVideoUrl {
+ provider: 'youtube' | 'vimeo'
+ videoId: string
+ embedUrl: string
+ thumbnailUrl: string | null
+}
+
+export function parseVideoUrl(input: string | null | undefined): ParsedVideoUrl | null {
+ if (!input?.trim()) return null
+
+ let url: URL
+ try {
+ url = new URL(input.trim())
+ } catch {
+ return null
+ }
+
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return null
+
+ const host = url.hostname.toLowerCase()
+ const segments = url.pathname.split('/').filter(Boolean)
+
+ if (YOUTUBE_HOSTS.includes(host)) {
+ const videoId = host.includes('youtu.be')
+ ? // A short link is the id and nothing else.
+ segments.length === 1
+ ? segments[0]
+ : ''
+ : url.pathname.replace(/\/$/, '') === '/watch'
+ ? (url.searchParams.get('v') ?? '')
+ : segments.length === 2 && YOUTUBE_ID_PATHS.includes(segments[0])
+ ? segments[1]
+ : ''
+
+ if (!YOUTUBE_ID.test(videoId)) return null
+
+ return {
+ provider: 'youtube',
+ videoId,
+ embedUrl: `https://www.youtube.com/embed/${videoId}`,
+ thumbnailUrl: `https://img.youtube.com/vi/${videoId}/hqdefault.jpg`,
+ }
+ }
+
+ if (VIMEO_HOSTS.includes(host)) {
+ const videoId = segments.at(-1) ?? ''
+ if (!VIMEO_ID.test(videoId)) return null
+
+ // Vimeo thumbnails need an API call, so there is no provider still here.
+ return {
+ provider: 'vimeo',
+ videoId,
+ embedUrl: `https://player.vimeo.com/video/${videoId}`,
+ thumbnailUrl: null,
+ }
+ }
+
+ return null
+}
+
+export function isSupportedVideoUrl(url: string | null | undefined): boolean {
+ return parseVideoUrl(url) !== null
+}
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index b7e3976760..2825a4db45 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -2,7 +2,7 @@
"admin": {
"a11y": {
"delete_image": "حذف الصورة",
- "edit_media": "تعديل الصورة"
+ "edit_media": "تحرير الوسائط"
},
"allowed_origins": {
"add_cta": "أضف الأصل المسموح به",
@@ -912,6 +912,15 @@
"alt": {
"label": "Alt text",
"placeholder": "صف الصورة لإمكانية الوصول وSEO"
+ },
+ "external_video_url": {
+ "help": "الصق رابط YouTube أو Vimeo.",
+ "label": "رابط الفيديو",
+ "placeholder": "https://www.youtube.com/watch?v=..."
+ },
+ "poster": {
+ "help": "الصورة الثابتة التي تظهر قبل تشغيل الفيديو. اتركها فارغة لاستخدام صورة المزود إن وُجدت.",
+ "label": "صورة الغلاف"
}
},
"option_type": {
@@ -3326,14 +3335,22 @@
"unknown_location": "موقع غير معروف"
},
"media": {
+ "add_video": "إضافة رابط فيديو",
+ "add_video_submit": "إضافة الفيديو",
+ "add_video_title": "إضافة رابط فيديو",
"assigned_variants_help": "اختر المتغيرات التي تمثلها هذه الصورة. اتركه فارغًا ليتم تطبيقه على كافة المتغيرات.",
"assigned_variants_label": "المتغيرات المخصصة",
"delete_confirm": "هل تريد حذف هذه الوسائط؟ لا يمكن التراجع عن هذا.",
"drop_hint": "قم بسحب وإفلات الوسائط هنا، أو انقر للتصفح",
"edit_title": "تحرير الوسائط",
- "file_types_hint": "PNG، JPG، WebP حتى 10 ميغابايت",
+ "file_types_hint": "صور (PNG، JPG، WebP) وفيديو (MP4، WebM، MOV)",
+ "focal_point_help": "انقر على الصورة لتحديد الجزء الذي يبقى ظاهراً عند الاقتصاص.",
+ "focal_point_reset": "إعادة تعيين",
+ "unsupported_file": "لم تتم إضافة {{count}} ملف — الصور والفيديو فقط مدعومة.",
"upload_failed": "فشل تحميل {{name}}: {{message}}",
- "upload_status_failed": "فشل"
+ "upload_status_failed": "فشل",
+ "video_preview_title": "معاينة الفيديو",
+ "video_url_invalid": "أدخل رابط YouTube أو Vimeo."
},
"no_categories_found": "لم يتم العثور على فئات",
"no_collections_found": "لم يتم العثور على مجموعات",
@@ -3413,14 +3430,6 @@
"review_description": "قم بمراجعة النقل قبل الإنشاء. لا يمكن تغيير العناصر بعد ذلك.",
"search_items_placeholder": "البحث بالاسم أو SKU (3+ أحرف) …"
},
- "variant_media_picker": {
- "add_count_one": "إضافة {{count}}",
- "add_count_other": "إضافة {{count}}",
- "empty_all_linked": "جميع وسائط المنتج مرتبطة بالفعل بهذا المتغير.",
- "empty_no_media": "لا توجد وسائط للمنتج بعد — ارفع الصور على المنتج أولاً.",
- "title": "اختر من معرض المنتج",
- "trigger": "اختر من معرض المنتج"
- },
"variants": {
"add_option": "إضافة خيار",
"bulk_edit": {
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index 36bb89645c..03a1d3b27c 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -2,7 +2,7 @@
"admin": {
"a11y": {
"delete_image": "Bild löschen",
- "edit_media": "Bild bearbeiten"
+ "edit_media": "Medien bearbeiten"
},
"allowed_origins": {
"add_cta": "Erlaubten Ursprung hinzufügen",
@@ -901,6 +901,15 @@
"alt": {
"label": "Alt-Text",
"placeholder": "Beschreiben Sie das Bild für Barrierefreiheit und SEO"
+ },
+ "external_video_url": {
+ "help": "Fügen Sie einen YouTube- oder Vimeo-Link ein.",
+ "label": "Video-Link",
+ "placeholder": "https://www.youtube.com/watch?v=..."
+ },
+ "poster": {
+ "help": "Das Standbild, das vor dem Abspielen angezeigt wird. Leer lassen, um das Bild des Anbieters zu verwenden, sofern vorhanden.",
+ "label": "Vorschaubild"
}
},
"option_type": {
@@ -3310,14 +3319,23 @@
"unknown_location": "Unbekannter Standort"
},
"media": {
+ "add_video": "Videolink hinzufügen",
+ "add_video_submit": "Video hinzufügen",
+ "add_video_title": "Videolink hinzufügen",
"assigned_variants_help": "Wählen Sie die Varianten aus, die dieses Bild repräsentiert. Leer lassen, um es auf alle Varianten anzuwenden.",
"assigned_variants_label": "Zugeordnete Varianten",
"delete_confirm": "Dieses Medium löschen? Dies kann nicht rückgängig gemacht werden.",
"drop_hint": "Medien hierher ziehen und ablegen oder zum Durchsuchen klicken",
"edit_title": "Medium bearbeiten",
- "file_types_hint": "PNG, JPG, WebP bis zu 10 MB",
+ "file_types_hint": "Bilder (PNG, JPG, WebP) und Videos (MP4, WebM, MOV)",
+ "focal_point_help": "Klicken Sie auf das Bild, um festzulegen, was beim Zuschneiden sichtbar bleibt.",
+ "focal_point_reset": "Zurücksetzen",
+ "unsupported_file_one": "{{count}} Datei wurde nicht hinzugefügt — nur Bilder und Videos werden unterstützt.",
+ "unsupported_file_other": "{{count}} Dateien wurden nicht hinzugefügt — nur Bilder und Videos werden unterstützt.",
"upload_failed": "Hochladen von {{name}} fehlgeschlagen: {{message}}",
- "upload_status_failed": "Fehlgeschlagen"
+ "upload_status_failed": "Fehlgeschlagen",
+ "video_preview_title": "Videovorschau",
+ "video_url_invalid": "Geben Sie einen YouTube- oder Vimeo-Link ein."
},
"no_categories_found": "Keine Kategorien gefunden",
"no_collections_found": "Keine Kollektionen gefunden",
@@ -3397,14 +3415,6 @@
"review_description": "Überprüfen Sie den Transfer vor dem Erstellen. Artikel können danach nicht mehr geändert werden.",
"search_items_placeholder": "Nach Name oder SKU suchen (3+ Zeichen)…"
},
- "variant_media_picker": {
- "add_count_one": "{{count}} hinzufügen",
- "add_count_other": "{{count}} hinzufügen",
- "empty_all_linked": "Alle Produktmedien sind bereits mit dieser Variante verknüpft.",
- "empty_no_media": "Noch keine Produktmedien — laden Sie zuerst Bilder auf dem Produkt hoch.",
- "title": "Aus Produktgalerie auswählen",
- "trigger": "Aus Produktgalerie auswählen"
- },
"variants": {
"add_option": "Option hinzufügen",
"bulk_edit": {
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index b688612e3d..1c84fc6e00 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -2,7 +2,7 @@
"admin": {
"a11y": {
"delete_image": "Delete image",
- "edit_media": "Edit image"
+ "edit_media": "Edit media"
},
"allowed_origins": {
"add_cta": "Add allowed origin",
@@ -901,6 +901,15 @@
"alt": {
"label": "Alt text",
"placeholder": "Describe the image for accessibility and SEO"
+ },
+ "external_video_url": {
+ "help": "Paste a YouTube or Vimeo link.",
+ "label": "Video link",
+ "placeholder": "https://www.youtube.com/watch?v=..."
+ },
+ "poster": {
+ "help": "The still shown before the video plays. Leave blank to use the provider’s own image where there is one.",
+ "label": "Poster image"
}
},
"option_type": {
@@ -3310,14 +3319,23 @@
"unknown_location": "Unknown location"
},
"media": {
+ "add_video": "Add video link",
+ "add_video_submit": "Add video",
+ "add_video_title": "Add a video link",
"assigned_variants_help": "Pick the variants this image represents. Leave blank to apply to all variants.",
"assigned_variants_label": "Assigned variants",
"delete_confirm": "Delete this media? This cannot be undone.",
"drop_hint": "Drag & drop media here, or click to browse",
"edit_title": "Edit media",
- "file_types_hint": "PNG, JPG, WebP up to 10MB",
+ "file_types_hint": "Images (PNG, JPG, WebP) and video (MP4, WebM, MOV)",
+ "focal_point_help": "Click the image to set what stays in frame when it is cropped.",
+ "focal_point_reset": "Reset",
+ "unsupported_file_one": "{{count}} file was not added — only images and video are supported.",
+ "unsupported_file_other": "{{count}} files were not added — only images and video are supported.",
"upload_failed": "Failed to upload {{name}}: {{message}}",
- "upload_status_failed": "Failed"
+ "upload_status_failed": "Failed",
+ "video_preview_title": "Video preview",
+ "video_url_invalid": "Enter a YouTube or Vimeo link."
},
"no_categories_found": "No categories found",
"no_collections_found": "No collections found",
@@ -3397,14 +3415,6 @@
"review_description": "Review the transfer before creating. Items can't be changed afterwards.",
"search_items_placeholder": "Search by name or SKU (3+ chars)…"
},
- "variant_media_picker": {
- "add_count_one": "Add {{count}}",
- "add_count_other": "Add {{count}}",
- "empty_all_linked": "All product media is already linked to this variant.",
- "empty_no_media": "No product media yet — upload images on the product first.",
- "title": "Select from product gallery",
- "trigger": "Select from product gallery"
- },
"variants": {
"add_option": "Add option",
"bulk_edit": {
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index 2b6e3fb779..cd0f9689d2 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -2,7 +2,7 @@
"admin": {
"a11y": {
"delete_image": "Supprimer l'image",
- "edit_media": "Modifier l'image"
+ "edit_media": "Modifier le média"
},
"allowed_origins": {
"add_cta": "Ajouter une origine autorisée",
@@ -901,6 +901,15 @@
"alt": {
"label": "Texte alternatif",
"placeholder": "Décrivez l'image pour l'accessibilité et le référencement"
+ },
+ "external_video_url": {
+ "help": "Collez un lien YouTube ou Vimeo.",
+ "label": "Lien vidéo",
+ "placeholder": "https://www.youtube.com/watch?v=..."
+ },
+ "poster": {
+ "help": "L'image fixe affichée avant la lecture. Laissez vide pour utiliser celle du fournisseur, si elle existe.",
+ "label": "Image de couverture"
}
},
"option_type": {
@@ -3310,14 +3319,23 @@
"unknown_location": "Emplacement inconnu"
},
"media": {
+ "add_video": "Ajouter un lien vidéo",
+ "add_video_submit": "Ajouter la vidéo",
+ "add_video_title": "Ajouter un lien vidéo",
"assigned_variants_help": "Sélectionnez les variantes que cette image représente. Laissez vide pour l'appliquer à toutes les variantes.",
"assigned_variants_label": "Variantes associées",
"delete_confirm": "Supprimer ce média ? Cette action est irréversible.",
"drop_hint": "Glissez-déposez un média ici, ou cliquez pour parcourir",
"edit_title": "Modifier le média",
- "file_types_hint": "PNG, JPG, WebP jusqu'à 10 Mo",
+ "file_types_hint": "Images (PNG, JPG, WebP) et vidéos (MP4, WebM, MOV)",
+ "focal_point_help": "Cliquez sur l'image pour définir ce qui reste visible lors du recadrage.",
+ "focal_point_reset": "Réinitialiser",
+ "unsupported_file_one": "{{count}} fichier n'a pas été ajouté — seules les images et vidéos sont prises en charge.",
+ "unsupported_file_other": "{{count}} fichiers n'ont pas été ajoutés — seules les images et vidéos sont prises en charge.",
"upload_failed": "Échec du téléversement de {{name}} : {{message}}",
- "upload_status_failed": "Échec"
+ "upload_status_failed": "Échec",
+ "video_preview_title": "Aperçu de la vidéo",
+ "video_url_invalid": "Saisissez un lien YouTube ou Vimeo."
},
"no_categories_found": "Aucune catégorie trouvée",
"no_collections_found": "Aucune collection trouvée",
@@ -3397,14 +3415,6 @@
"review_description": "Vérifiez le transfert avant de le créer. Les articles ne pourront plus être modifiés ensuite.",
"search_items_placeholder": "Rechercher par nom ou SKU (3 caractères ou plus)…"
},
- "variant_media_picker": {
- "add_count_one": "Ajouter {{count}}",
- "add_count_other": "Ajouter {{count}}",
- "empty_all_linked": "Tous les médias produit sont déjà liés à cette variante.",
- "empty_no_media": "Aucun média produit — téléversez d’abord des images sur le produit.",
- "title": "Sélectionner dans la galerie produit",
- "trigger": "Sélectionner dans la galerie produit"
- },
"variants": {
"add_option": "Ajouter une option",
"bulk_edit": {
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index 11006b2085..70ff4aa113 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -2,7 +2,7 @@
"admin": {
"a11y": {
"delete_image": "Usuń obraz",
- "edit_media": "Edytuj obraz"
+ "edit_media": "Edytuj multimedia"
},
"allowed_origins": {
"add_cta": "Dodaj dozwolone źródło",
@@ -915,6 +915,15 @@
"alt": {
"label": "Tekst alternatywny",
"placeholder": "Opisz obraz na potrzeby dostępności i SEO"
+ },
+ "external_video_url": {
+ "help": "Wklej link do YouTube lub Vimeo.",
+ "label": "Link do wideo",
+ "placeholder": "https://www.youtube.com/watch?v=..."
+ },
+ "poster": {
+ "help": "Nieruchomy obraz pokazywany przed odtworzeniem. Zostaw puste, aby użyć obrazu dostawcy, jeśli jest dostępny.",
+ "label": "Miniatura wideo"
}
},
"option_type": {
@@ -3358,14 +3367,23 @@
"unknown_location": "Nieznana lokalizacja"
},
"media": {
+ "add_video": "Dodaj link do wideo",
+ "add_video_submit": "Dodaj wideo",
+ "add_video_title": "Dodaj link do wideo",
"assigned_variants_help": "Wybierz warianty, które reprezentuje to zdjęcie. Pozostaw puste, aby zastosować do wszystkich wariantów.",
"assigned_variants_label": "Przypisane warianty",
"delete_confirm": "Usunąć ten plik multimedialny? Tej operacji nie można cofnąć.",
"drop_hint": "Przeciągnij i upuść pliki tutaj lub kliknij, aby przeglądać",
"edit_title": "Edytuj plik multimedialny",
- "file_types_hint": "PNG, JPG, WebP do 10 MB",
+ "file_types_hint": "Zdjęcia (PNG, JPG, WebP) i wideo (MP4, WebM, MOV)",
+ "focal_point_help": "Kliknij zdjęcie, aby wskazać, co ma pozostać widoczne po przycięciu.",
+ "focal_point_reset": "Przywróć",
+ "unsupported_file_one": "Nie dodano {{count}} pliku — obsługiwane są tylko zdjęcia i wideo.",
+ "unsupported_file_other": "Nie dodano {{count}} plików — obsługiwane są tylko zdjęcia i wideo.",
"upload_failed": "Nie udało się przesłać {{name}}: {{message}}",
- "upload_status_failed": "Niepowodzenie"
+ "upload_status_failed": "Niepowodzenie",
+ "video_preview_title": "Podgląd wideo",
+ "video_url_invalid": "Podaj link do YouTube lub Vimeo."
},
"no_categories_found": "Nie znaleziono kategorii",
"no_collections_found": "Nie znaleziono kolekcji",
@@ -3449,14 +3467,6 @@
"review_description": "Sprawdź transfer przed utworzeniem. Pozycji nie można później zmienić.",
"search_items_placeholder": "Szukaj według nazwy lub SKU (min. 3 znaki)…"
},
- "variant_media_picker": {
- "add_count_one": "Dodaj {{count}}",
- "add_count_other": "Dodaj {{count}}",
- "empty_all_linked": "Wszystkie media produktu są już powiązane z tym wariantem.",
- "empty_no_media": "Brak mediów produktu — najpierw prześlij obrazy do produktu.",
- "title": "Wybierz z galerii produktu",
- "trigger": "Wybierz z galerii produktu"
- },
"variants": {
"add_option": "Dodaj opcję",
"bulk_edit": {
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index 2ba5ef9752..c2f37e4991 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -2,7 +2,7 @@
"admin": {
"a11y": {
"delete_image": "删除图片",
- "edit_media": "编辑图片"
+ "edit_media": "编辑媒体"
},
"allowed_origins": {
"add_cta": "添加允许的来源",
@@ -898,6 +898,15 @@
"alt": {
"label": "替代文本",
"placeholder": "为无障碍访问和 SEO 描述该图片"
+ },
+ "external_video_url": {
+ "help": "粘贴 YouTube 或 Vimeo 链接。",
+ "label": "视频链接",
+ "placeholder": "https://www.youtube.com/watch?v=..."
+ },
+ "poster": {
+ "help": "播放前显示的静态图片。留空则使用视频平台自带的封面(如果有)。",
+ "label": "视频封面"
}
},
"option_type": {
@@ -3306,14 +3315,22 @@
"unknown_location": "未知位置"
},
"media": {
+ "add_video": "添加视频链接",
+ "add_video_submit": "添加视频",
+ "add_video_title": "添加视频链接",
"assigned_variants_help": "选择此图片所代表的变体。留空则应用于所有变体。",
"assigned_variants_label": "关联的变体",
"delete_confirm": "删除此媒体?此操作无法撤销。",
"drop_hint": "将媒体拖放到此处,或点击浏览",
"edit_title": "编辑媒体",
- "file_types_hint": "PNG、JPG、WebP,最大 10MB",
+ "file_types_hint": "图片(PNG、JPG、WebP)和视频(MP4、WebM、MOV)",
+ "focal_point_help": "点击图片,设置裁剪时需要保留的画面位置。",
+ "focal_point_reset": "重置",
+ "unsupported_file": "有 {{count}} 个文件未添加 — 仅支持图片和视频。",
"upload_failed": "上传 {{name}} 失败:{{message}}",
- "upload_status_failed": "失败"
+ "upload_status_failed": "失败",
+ "video_preview_title": "视频预览",
+ "video_url_invalid": "请输入 YouTube 或 Vimeo 链接。"
},
"no_categories_found": "未找到分类",
"no_collections_found": "未找到系列",
@@ -3393,14 +3410,6 @@
"review_description": "创建前请检查此调拨。创建后将无法更改商品项。",
"search_items_placeholder": "按名称或 SKU 搜索(3 个以上字符)…"
},
- "variant_media_picker": {
- "add_count_one": "添加 {{count}} 个",
- "add_count_other": "添加 {{count}} 个",
- "empty_all_linked": "所有产品媒体已关联到此变体。",
- "empty_no_media": "尚无产品媒体 — 请先在产品上上传图片。",
- "title": "从产品图库选择",
- "trigger": "从产品图库选择"
- },
"variants": {
"add_option": "添加选项",
"bulk_edit": {
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
index 21d5e30e29..c4446db8bf 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/$productId.tsx
@@ -1,5 +1,5 @@
import { zodResolver } from '@hookform/resolvers/zod'
-import { type Product, SpreeError, type Variant } from '@spree/admin-sdk'
+import { type Media, type Product, SpreeError, type Variant } from '@spree/admin-sdk'
import {
adminClient,
extensionFormValues,
@@ -43,6 +43,7 @@ import { useDeleteProduct, useProduct, useUpdateProduct } from '../../../../hook
import { useProductMedia } from '../../../../hooks/use-product-media'
import { spreeJsonLinkResolver } from '../../../../lib/json-link-resolver'
import {
+ type MediaType,
type ProductFormValues,
productFormSchema,
type VariantFormValues,
@@ -108,21 +109,37 @@ function variantToFormValues(variant: Variant, position: number): VariantFormVal
}
}
+// One mapping for both hydration paths (the form reset and the media-only
+// late paint) so a new media field can't reach one and miss the other.
+// Takes the generated SDK type rather than a hand-listed shape, so a field
+// added to the serializer can't quietly go missing here.
+function mediaToFormValues(media: Media, index: number) {
+ return {
+ id: media.id,
+ alt: media.alt ?? null,
+ position: media.position ?? index + 1,
+ variant_ids: media.variant_ids ?? [],
+ media_type: (media.media_type ?? 'image') as MediaType,
+ external_video_url: media.external_video_url ?? null,
+ focal_point_x: media.focal_point_x ?? null,
+ focal_point_y: media.focal_point_y ?? null,
+ // Video rows have no image of their own, so the poster is the preview.
+ previewUrl:
+ media.small_url ?? media.mini_url ?? media.poster_url ?? media.original_url ?? undefined,
+ posterUrl: media.poster_url,
+ // The file itself, so an uploaded video can actually play. Every sized URL
+ // on a video row resolves to its poster, so none of them work here.
+ videoUrl: media.video_url,
+ }
+}
+
function productToFormValues(
product: Product,
// Optional media list — passed in from useProductMedia (which is a separate
// query). When provided we hydrate form.media here so the form.reset cycle
// captures it atomically instead of via a follow-up setValue that races
// with the merchant's unsaved edits.
- media?: Array<{
- id: string
- alt: string | null
- position: number | null
- variant_ids: string[] | null
- small_url: string | null
- mini_url: string | null
- original_url: string | null
- }>,
+ media?: Media[],
): ProductFormValues {
const hasVariants = (product.variant_count ?? 0) > 0
const variantSource = hasVariants
@@ -159,14 +176,7 @@ function productToFormValues(
custom_field_definition_id: cf.custom_field_definition_id,
value: cf.value,
})) ?? [],
- media:
- media?.map((m, i) => ({
- id: m.id,
- alt: m.alt ?? null,
- position: m.position ?? i + 1,
- variant_ids: m.variant_ids ?? [],
- previewUrl: m.small_url ?? m.mini_url ?? m.original_url ?? undefined,
- })) ?? [],
+ media: media?.map(mediaToFormValues) ?? [],
product_publications: (product.product_publications ?? []).map((l) => ({
id: l.id,
channel_id: l.channel_id,
@@ -326,17 +336,7 @@ function ProductForm({ product }: { product: Product }) {
const current = form.getValues('media') ?? []
if (current.length > 0) return
if (form.formState.dirtyFields?.media) return
- form.setValue(
- 'media',
- mediaItems.map((m, i) => ({
- id: m.id,
- alt: m.alt ?? null,
- position: m.position ?? i + 1,
- variant_ids: m.variant_ids ?? [],
- previewUrl: m.small_url ?? m.mini_url ?? m.original_url ?? undefined,
- })),
- { shouldDirty: false },
- )
+ form.setValue('media', mediaItems.map(mediaToFormValues), { shouldDirty: false })
}, [mediaItems, form])
const onSubmit = async (data: ProductFormValues) => {
@@ -358,7 +358,7 @@ function ProductForm({ product }: { product: Product }) {
// dedicated DELETE /media endpoint, which the MediaCard already calls
// before removing an entry from form state.
if (media && media.length > 0) {
- payload.media = media.map(({ previewUrl, uploadId, ...rest }, i) => ({
+ payload.media = media.map(({ previewUrl, posterUrl, videoUrl, uploadId, ...rest }, i) => ({
...rest,
position: i + 1,
}))
@@ -381,7 +381,15 @@ function ProductForm({ product }: { product: Product }) {
// values back so the reset doesn't blank their inputs pre-refetch.
...extensionValues,
media: (data.media ?? []).map(
- ({ signed_id: _sid, previewUrl: _p, uploadId: _u, ...rest }) => rest,
+ ({
+ signed_id: _sid,
+ poster_signed_id: _psid,
+ previewUrl: _p,
+ posterUrl: _pu,
+ videoUrl: _vu,
+ uploadId: _u,
+ ...rest
+ }) => rest,
),
}
form.reset(baseline)
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx
index 6c2340347c..002352d505 100644
--- a/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/products/new.tsx
@@ -77,8 +77,7 @@ function NewProductPage() {
// The server's Product#media= setter attaches each blob via signed_id
// after the product is created (deferred to after_save).
if (media && media.length > 0) {
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- ;(payload as any).media = media.map(({ previewUrl, uploadId, ...rest }, i) => ({
+ payload.media = media.map(({ previewUrl, posterUrl, videoUrl, uploadId, ...rest }, i) => ({
...rest,
position: i + 1,
}))
diff --git a/packages/dashboard/src/schemas/product.ts b/packages/dashboard/src/schemas/product.ts
index d70e8e7254..5d5004f11d 100644
--- a/packages/dashboard/src/schemas/product.ts
+++ b/packages/dashboard/src/schemas/product.ts
@@ -1,5 +1,6 @@
import { requiredMessage } from '@spree/dashboard-ui'
import { z } from 'zod/v4'
+import { isSupportedVideoUrl } from '../lib/video-url'
export const stockItemFormSchema = z.object({
id: z.string().optional(),
@@ -74,16 +75,39 @@ export type CustomFieldFormValues = z.infer<typeof customFieldFormSchema>
// can hold edits to alt, position, and variant_ids that the parent product
// PATCH/POST ships inline. previewUrl + uploadId are UI-only; stripped at
// submit.
-export const mediaFormSchema = z.object({
- id: z.string().optional(),
- signed_id: z.string().optional(),
- alt: z.string().nullable().optional(),
- position: z.number().int().nonnegative().optional(),
- variant_ids: z.array(z.string()).optional(),
- // UI-only — strip at submit.
- previewUrl: z.string().optional(),
- uploadId: z.string().optional(),
-})
+export const MEDIA_TYPES = ['image', 'video', 'external_video'] as const
+
+export type MediaType = (typeof MEDIA_TYPES)[number]
+
+export const mediaFormSchema = z
+ .object({
+ id: z.string().optional(),
+ signed_id: z.string().optional(),
+ alt: z.string().nullable().optional(),
+ position: z.number().int().nonnegative().optional(),
+ variant_ids: z.array(z.string()).optional(),
+ media_type: z.enum(MEDIA_TYPES).optional(),
+ external_video_url: z.string().nullable().optional(),
+ // A video's still frame. Sent as a signed id like the media file itself;
+ // `posterUrl` is the UI-only preview and never reaches the API.
+ poster_signed_id: z.string().optional(),
+ posterUrl: z.string().nullable().optional(),
+ // Playback source for an uploaded video. UI-only: a blob URL before save,
+ // the served file after. Never sent back.
+ videoUrl: z.string().nullable().optional(),
+ focal_point_x: z.number().min(0).max(1).nullable().optional(),
+ focal_point_y: z.number().min(0).max(1).nullable().optional(),
+ // UI-only — strip at submit.
+ previewUrl: z.string().optional(),
+ uploadId: z.string().optional(),
+ })
+ // The server rejects a link it can't embed, and that failure aborts the whole
+ // product save. Catch it here so the merchant sees it on the field instead.
+ .refine(
+ (media) =>
+ media.media_type !== 'external_video' || isSupportedVideoUrl(media.external_video_url),
+ { message: 'unsupported_video_provider', path: ['external_video_url'] },
+ )
export type MediaFormValues = z.infer<typeof mediaFormSchema>
diff --git a/packages/sdk/src/types/generated/Media.ts b/packages/sdk/src/types/generated/Media.ts
index 2a0f23a56b..016cb0e36f 100644
--- a/packages/sdk/src/types/generated/Media.ts
+++ b/packages/sdk/src/types/generated/Media.ts
@@ -1,4 +1,4 @@
-// Typelizer digest a5e3fc9471b70defb20d943d458ef05d
+// Typelizer digest 982fb1c77e99644481ed30fe4261bc1b
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
@@ -12,6 +12,10 @@ interface Media {
focal_point_x: number | null;
focal_point_y: number | null;
external_video_url: string | null;
+ video_provider: string | null;
+ video_embed_url: string | null;
+ video_url: string | null;
+ poster_url: string | null;
original_url: string | null;
mini_url: string | null;
small_url: string | null;
diff --git a/packages/sdk/src/types/generated/MediaEvent.ts b/packages/sdk/src/types/generated/MediaEvent.ts
new file mode 100644
index 0000000000..eb081ace07
--- /dev/null
+++ b/packages/sdk/src/types/generated/MediaEvent.ts
@@ -0,0 +1,16 @@
+// Typelizer digest cd9acca40c7ec79ea85949ee87288d92
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface MediaEvent {
+ id: string;
+ viewable_id: string;
+ viewable_type: string;
+ media_type: string;
+ position: number | null;
+ alt: string | null;
+ created_at: string;
+ updated_at: string;
+}
+
+export default MediaEvent;
diff --git a/packages/sdk/src/types/generated/index.ts b/packages/sdk/src/types/generated/index.ts
index a17ca258fb..49ad4210f6 100644
--- a/packages/sdk/src/types/generated/index.ts
+++ b/packages/sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest 976c58296cb2b9a554be05730f40d259
+// Typelizer digest c6033982878e42f3a5015ec1552f31bd
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -32,6 +32,7 @@ export type { default as Invitation } from './Invitation'
export type { default as LineItem } from './LineItem'
export type { default as Locale } from './Locale'
export type { default as Market } from './Market'
+export type { default as MediaEvent } from './MediaEvent'
export type { default as Media } from './Media'
export type { default as NewsletterSubscriber } from './NewsletterSubscriber'
export type { default as OptionType } from './OptionType'
diff --git a/packages/sdk/src/zod/generated/Media.ts b/packages/sdk/src/zod/generated/Media.ts
index dd152cc967..e84487846e 100644
--- a/packages/sdk/src/zod/generated/Media.ts
+++ b/packages/sdk/src/zod/generated/Media.ts
@@ -11,6 +11,10 @@ export const MediaSchema = z.object({
focal_point_x: z.number().nullable(),
focal_point_y: z.number().nullable(),
external_video_url: z.string().nullable(),
+ video_provider: z.string().nullable(),
+ video_embed_url: z.string().nullable(),
+ video_url: z.string().nullable(),
+ poster_url: z.string().nullable(),
original_url: z.string().nullable(),
mini_url: z.string().nullable(),
small_url: z.string().nullable(),
diff --git a/packages/sdk/src/zod/generated/MediaEvent.ts b/packages/sdk/src/zod/generated/MediaEvent.ts
new file mode 100644
index 0000000000..9ee868d528
--- /dev/null
+++ b/packages/sdk/src/zod/generated/MediaEvent.ts
@@ -0,0 +1,15 @@
+// This file is auto-generated. Do not edit directly.
+import { z } from 'zod';
+
+export const MediaEventSchema = z.object({
+ id: z.string(),
+ viewable_id: z.string(),
+ viewable_type: z.string(),
+ media_type: z.string(),
+ position: z.number().nullable(),
+ alt: z.string().nullable(),
+ created_at: z.string(),
+ updated_at: z.string(),
+});
+
+export type MediaEvent = z.infer<typeof MediaEventSchema>;
diff --git a/packages/sdk/src/zod/generated/index.ts b/packages/sdk/src/zod/generated/index.ts
index dddcd782a9..09014946af 100644
--- a/packages/sdk/src/zod/generated/index.ts
+++ b/packages/sdk/src/zod/generated/index.ts
@@ -31,6 +31,7 @@ export { LineItemSchema, type LineItem } from './LineItem';
export { LocaleSchema, type Locale } from './Locale';
export { MarketSchema, type Market } from './Market';
export { MediaSchema, type Media } from './Media';
+export { MediaEventSchema, type MediaEvent } from './MediaEvent';
export { NewsletterSubscriberSchema, type NewsletterSubscriber } from './NewsletterSubscriber';
export { OptionTypeSchema, type OptionType } from './OptionType';
export { OptionValueSchema, type OptionValue } from './OptionValue';
diff --git a/spree/api/app/controllers/concerns/spree/api/v3/admin/product_listing.rb b/spree/api/app/controllers/concerns/spree/api/v3/admin/product_listing.rb
index 91bc94ddf7..2a768907f3 100644
--- a/spree/api/app/controllers/concerns/spree/api/v3/admin/product_listing.rb
+++ b/spree/api/app/controllers/concerns/spree/api/v3/admin/product_listing.rb
@@ -33,7 +33,7 @@ module Spree
:tax_category,
:product_type,
{ product_publications: :channel },
- { primary_media: [attachment_attachment: :blob] },
+ { primary_media: [attachment_attachment: :blob, poster_attachment: :blob] },
{ default_variant: [:prices, { stock_items: [:stock_location, :active_stock_reservations] }] },
{ variants: [:prices, { stock_items: [:stock_location, :active_stock_reservations] }] }
]
diff --git a/spree/api/app/controllers/spree/api/v3/admin/media_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/media_controller.rb
index 81fb69484b..967a9e1ce6 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/media_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/media_controller.rb
@@ -6,7 +6,10 @@ module Spree
scoped_resource :products
def create
- if permitted_params[:url].present?
+ # An external video has no file, so it takes the plain create path
+ # even though a URL is present — `url` means "fetch this image from
+ # here" and only applies to image rows.
+ if permitted_params[:url].present? && !external_video_request?
create_from_url
elsif permitted_params[:signed_id].present?
create_from_signed_id
@@ -25,7 +28,7 @@ module Spree
protected
def model_class
- Spree::Asset
+ Spree::Media
end
def serializer_class
@@ -44,7 +47,7 @@ module Spree
end
# Variants store assets via the polymorphic `images` association; products own
- # their gallery via `media`. Both resolve to `Spree::Asset` rows with different
+ # their gallery via `media`. Both resolve to `Spree::Media` rows with different
# `viewable_type` values.
def parent_association
params[:variant_id].present? ? :images : :media
@@ -57,36 +60,35 @@ module Spree
def scope
return super if params[:variant_id].present?
- Spree::Asset.where(
+ Spree::Media.where(
viewable_type: 'Spree::Product', viewable_id: @product.id
).or(
- Spree::Asset.where(
+ Spree::Media.where(
viewable_type: 'Spree::Variant', viewable_id: @product.default_variant&.id
)
).order(:position)
end
- ALLOWED_MEDIA_TYPES = -> { [Spree::Asset, *Spree::Asset.descendants].map(&:name).to_set.freeze }
-
def build_resource
- media_type = permitted_params[:type] || 'Spree::Image'
-
- unless ALLOWED_MEDIA_TYPES.call.include?(media_type)
- raise ArgumentError, "Invalid media type: #{media_type}"
- end
-
- media = @parent.send(parent_association).build(permitted_params.except(:type, :url, :signed_id))
- media.type = media_type
-
- media
+ @parent.send(parent_association).build(permitted_params.except(:url, :signed_id))
end
+ # The media file and a URL to fetch one from are transport, not
+ # attributes — everything a client can set lives on the model.
def permitted_params
- params.permit(:type, :alt, :position, :attachment, :url, :signed_id, variant_ids: [])
+ params.permit(
+ *Spree::Media::WRITABLE_ATTRIBUTES,
+ :attachment, :url, :signed_id,
+ variant_ids: []
+ )
+ end
+
+ def external_video_request?
+ permitted_params[:media_type] == 'external_video'
end
def create_from_url
- authorize!(:create, Spree::Asset)
+ authorize!(:create, Spree::Media)
url = permitted_params[:url]
position = permitted_params[:position]
diff --git a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb
index c2ede1388a..b6fadb67ff 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/products_controller.rb
@@ -227,12 +227,12 @@ module Spree
# whether the parsed payload is an array or an object, while
# text/number/boolean ship scalars.
custom_fields: [:id, :custom_field_definition_id, :value, { value: [] }, { value: {} }],
- # Inline media. Entries with `id` patch an existing asset
- # (alt, position, variant_ids). Entries with `signed_id` create
- # + attach a fresh upload. Lets the dashboard ship media changes
- # alongside the rest of the product form. See
- # `Spree::Product#media=`.
- media: [:id, :signed_id, :alt, :position, :type, variant_ids: []],
+ # Inline media. Entries with `id` patch an existing asset.
+ # Entries with `signed_id` create + attach a fresh upload; an
+ # external video creates with a URL and no file. Lets the
+ # dashboard ship media changes alongside the rest of the product
+ # form. See `Spree::Product#media=`.
+ media: [*Spree::Media::WRITABLE_ATTRIBUTES, :id, :signed_id, { variant_ids: [] }],
product_publications: [:id, :channel_id, :published_at, :unpublished_at],
variants: [
:id, :sku, :barcode,
diff --git a/spree/api/app/controllers/spree/api/v3/admin/variants_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/variants_controller.rb
index 53a573a2ea..b9d09819c1 100644
--- a/spree/api/app/controllers/spree/api/v3/admin/variants_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/admin/variants_controller.rb
@@ -23,7 +23,7 @@ module Spree
[
:prices, stock_items: :stock_location,
option_values: :option_type,
- primary_media: [attachment_attachment: :blob]
+ primary_media: [attachment_attachment: :blob, poster_attachment: :blob]
]
end
end
diff --git a/spree/api/app/controllers/spree/api/v3/store/products_controller.rb b/spree/api/app/controllers/spree/api/v3/store/products_controller.rb
index 4cba3082a4..be2befa487 100644
--- a/spree/api/app/controllers/spree/api/v3/store/products_controller.rb
+++ b/spree/api/app/controllers/spree/api/v3/store/products_controller.rb
@@ -43,7 +43,7 @@ module Spree
:seller,
{
product_publications: [],
- primary_media: [attachment_attachment: :blob],
+ primary_media: [attachment_attachment: :blob, poster_attachment: :blob],
default_variant: [:prices, stock_items: [:stock_location, :active_stock_reservations]],
variants: [:prices, :seller, stock_items: [:stock_location, :active_stock_reservations]]
}
diff --git a/spree/api/app/serializers/spree/api/v3/base_serializer.rb b/spree/api/app/serializers/spree/api/v3/base_serializer.rb
index 179627b06e..e78a923aff 100644
--- a/spree/api/app/serializers/spree/api/v3/base_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/base_serializer.rb
@@ -126,9 +126,9 @@ module Spree
return nil if image.nil?
return nil unless image.respond_to?(:attached?) && image.attached?
- # Handle Spree::Asset models (like Spree::Image) which have attachment inside
+ # Handle Spree::Media rows, which keep the file in `attachment`
# vs direct ActiveStorage attachments (like taxon.image)
- attachment = image.is_a?(Spree::Asset) ? image.attachment : image
+ attachment = image.is_a?(Spree::Media) ? image.attachment : image
Rails.application.routes.url_helpers.cdn_image_url(attachment)
end
end
diff --git a/spree/api/app/serializers/spree/api/v3/asset_serializer.rb b/spree/api/app/serializers/spree/api/v3/media_event_serializer.rb
similarity index 78%
rename from spree/api/app/serializers/spree/api/v3/asset_serializer.rb
rename to spree/api/app/serializers/spree/api/v3/media_event_serializer.rb
index ab881a9591..5bcd4f8496 100644
--- a/spree/api/app/serializers/spree/api/v3/asset_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/media_event_serializer.rb
@@ -3,9 +3,9 @@
module Spree
module Api
module V3
- class AssetSerializer < BaseSerializer
- # `type` is not exposed: Spree::Image/Spree::Video were collapsed into
- # Spree::Asset, so the STI column is a legacy vestige with no subclasses
+ class MediaEventSerializer < BaseSerializer
+ # `type` is not exposed: the old Spree::Image/Spree::Video STI collapsed
+ # into one class, so the column is a legacy vestige with no subclasses
# — `media_type` is the discriminator (see MediaSerializer).
typelize media_type: :string, viewable_type: :string,
viewable_id: :string, position: [:number, nullable: true],
diff --git a/spree/api/app/serializers/spree/api/v3/media_serializer.rb b/spree/api/app/serializers/spree/api/v3/media_serializer.rb
index 0e478710d1..8d08ca1a32 100644
--- a/spree/api/app/serializers/spree/api/v3/media_serializer.rb
+++ b/spree/api/app/serializers/spree/api/v3/media_serializer.rb
@@ -9,6 +9,10 @@ module Spree
focal_point_x: [:number, nullable: true],
focal_point_y: [:number, nullable: true],
external_video_url: [:string, nullable: true],
+ video_provider: [:string, nullable: true],
+ video_embed_url: [:string, nullable: true],
+ video_url: [:string, nullable: true],
+ poster_url: [:string, nullable: true],
original_url: [:string, nullable: true], mini_url: [:string, nullable: true],
small_url: [:string, nullable: true], medium_url: [:string, nullable: true],
large_url: [:string, nullable: true], xlarge_url: [:string, nullable: true],
@@ -33,7 +37,36 @@ module Spree
attributes :position, :alt, :media_type,
:focal_point_x, :focal_point_y, :external_video_url
+ # Spree parses the YouTube/Vimeo link once, here, so no storefront has
+ # to reimplement it. Nil on anything that isn't an external video.
+ attribute :video_provider do |asset|
+ asset.external_video&.provider
+ end
+
+ attribute :video_embed_url do |asset|
+ asset.external_video&.embed_url
+ end
+
+ # The uploaded video file itself. Served as-is — Spree does not
+ # transcode.
+ attribute :video_url do |asset|
+ next nil unless asset.video? && asset.attachment.attached?
+
+ url_helpers.cdn_image_url(asset.attachment)
+ end
+
+ # Still frame for a video tile: the merchant's upload when there is one,
+ # otherwise the provider's own thumbnail.
+ attribute :poster_url do |asset|
+ next nil unless asset.playable_video?
+
+ still_url(asset)
+ end
+
+ # Nil for video rows — there is no image to size.
attribute :original_url do |asset|
+ next nil if asset.playable_video?
+
image_url_for(asset)
end
@@ -42,18 +75,26 @@ module Spree
# (e.g., mini, small, medium, large, xlarge)
Spree::Config.product_image_variant_sizes.each_key do |variant_name|
attribute :"#{variant_name}_url" do |asset|
- variant_url(asset, variant_name)
+ still_url(asset, variant_name)
end
end
private
- def variant_url(asset, variant_name)
- return nil unless asset&.attachment&.attached?
+ # The row's still frame, sized when it's an attachment we control — an
+ # image's own file, or a video's poster, so a gallery that only knows
+ # how to draw an image still renders the right picture. A provider's
+ # thumbnail is served as-is: it isn't ours to resize, so every size
+ # resolves to the same URL.
+ def still_url(asset, variant_name = nil)
+ source = asset&.still_image
+ return asset&.provider_still_url if source.nil?
+
+ url_helpers.cdn_image_url(variant_name ? source.variant(variant_name) : source)
+ end
- Rails.application.routes.url_helpers.cdn_image_url(
- asset.attachment.variant(variant_name)
- )
+ def url_helpers
+ Rails.application.routes.url_helpers
end
end
end
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index fe89812e1d..b784ef5c51 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -68,7 +68,7 @@ module Spree
product_filter_sort_option_serializer: 'Spree::Api::V3::ProductFilterSortOptionSerializer',
# v3 event serializers (for models without Store API endpoints yet)
- asset_serializer: 'Spree::Api::V3::AssetSerializer',
+ media_event_serializer: 'Spree::Api::V3::MediaEventSerializer',
return_serializer: 'Spree::Api::V3::ReturnSerializer',
return_line_item_serializer: 'Spree::Api::V3::ReturnLineItemSerializer',
exchange_serializer: 'Spree::Api::V3::ExchangeSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/products/media_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/products/media_controller_spec.rb
index 37f6b4a4a7..17ffc4a3df 100644
--- a/spree/api/spec/controllers/spree/api/v3/admin/products/media_controller_spec.rb
+++ b/spree/api/spec/controllers/spree/api/v3/admin/products/media_controller_spec.rb
@@ -156,6 +156,137 @@ RSpec.describe Spree::Api::V3::Admin::MediaController, type: :controller do
end
end
+ describe 'video' do
+ describe 'POST #create' do
+ it 'adds an external video from a link' do
+ post :create, params: {
+ product_id: product.prefixed_id,
+ media_type: 'external_video',
+ external_video_url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+ alt: 'Product walkthrough'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['media_type']).to eq('external_video')
+ expect(json_response['video_provider']).to eq('youtube')
+ expect(json_response['video_embed_url']).to eq('https://www.youtube.com/embed/dQw4w9WgXcQ')
+ expect(json_response['poster_url']).to eq('https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg')
+ end
+
+ it 'adds a Vimeo video' do
+ post :create, params: {
+ product_id: product.prefixed_id,
+ media_type: 'external_video',
+ external_video_url: 'https://vimeo.com/123456789'
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['video_provider']).to eq('vimeo')
+ expect(json_response['video_embed_url']).to eq('https://player.vimeo.com/video/123456789')
+ end
+
+ it 'rejects a link Spree cannot embed' do
+ post :create, params: {
+ product_id: product.prefixed_id,
+ media_type: 'external_video',
+ external_video_url: 'https://example.com/clip.mp4'
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+
+ it 'rejects an external video with no link' do
+ post :create, params: {
+ product_id: product.prefixed_id,
+ media_type: 'external_video'
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ end
+ end
+
+ describe 'PATCH #update' do
+ let!(:video) do
+ create(:external_video_asset, viewable: product,
+ external_video_url: 'https://vimeo.com/123456789')
+ end
+
+ it 'swaps the video link' do
+ patch :update, params: {
+ product_id: product.prefixed_id,
+ id: video.prefixed_id,
+ external_video_url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['video_provider']).to eq('youtube')
+ end
+
+ it 'rejects a link Spree cannot embed' do
+ patch :update, params: {
+ product_id: product.prefixed_id,
+ id: video.prefixed_id,
+ external_video_url: 'https://example.com/clip.mp4'
+ }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_content)
+ expect(video.reload.external_video_url).to eq('https://vimeo.com/123456789')
+ end
+ end
+
+ describe 'poster' do
+ let(:poster_blob) do
+ ActiveStorage::Blob.create_and_upload!(
+ io: File.open(Spree::Core::Engine.root.join('spec', 'fixtures', 'thinking-cat.jpg')),
+ filename: 'poster.jpg',
+ content_type: 'image/jpeg'
+ )
+ end
+
+ it 'attaches a poster when the video is created' do
+ post :create, params: {
+ product_id: product.prefixed_id,
+ media_type: 'external_video',
+ external_video_url: 'https://vimeo.com/123456789',
+ poster_signed_id: poster_blob.signed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['poster_url']).to be_present
+ expect(Spree::Media.find_by_prefix_id(json_response['id']).poster).to be_attached
+ end
+
+ it 'attaches a poster to an existing video' do
+ video = create(:external_video_asset, viewable: product,
+ external_video_url: 'https://vimeo.com/123456789')
+
+ patch :update, params: {
+ product_id: product.prefixed_id,
+ id: video.prefixed_id,
+ poster_signed_id: poster_blob.signed_id
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(video.reload.poster).to be_attached
+ expect(json_response['poster_url']).to be_present
+ end
+ end
+
+ describe 'focal point' do
+ it 'writes the focal point on an image' do
+ patch :update, params: {
+ product_id: product.prefixed_id,
+ id: image.prefixed_id,
+ focal_point_x: 0.25,
+ focal_point_y: 0.75
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(image.reload.focal_point).to eq({ x: 0.25, y: 0.75 })
+ end
+ end
+ end
+
describe 'variant assets' do
let!(:variant) { create(:variant, product: product) }
let!(:variant_image) { create(:image, viewable: variant) }
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 b96ffc85ff..0a60ff7d4d 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
@@ -629,7 +629,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
]
}, as: :json
}.to change(Spree::Product, :count).by(1)
- .and change(Spree::Asset, :count).by(2)
+ .and change(Spree::Media, :count).by(2)
expect(response).to have_http_status(:created)
created = Spree::Product.find_by(name: 'test product')
@@ -714,7 +714,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
]
}, as: :json
}.to change(Spree::Product, :count).by(1)
- .and change(Spree::Asset, :count).by(1)
+ .and change(Spree::Media, :count).by(1)
expect(response).to have_http_status(:created)
@@ -723,22 +723,42 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
media = created.media.first
expect(media.alt).to eq('A cat thinking')
expect(media.attachment).to be_attached
- expect(media.type).to eq('Spree::Image')
+ expect(media.media_type).to eq('image')
end
- it 'rejects an unknown media type' do
- post :create, params: {
- name: 'Product Bad Type',
- media: [
- { signed_id: blob.signed_id, type: 'NotAClass' }
- ]
- }, as: :json
+ it 'attaches an external video inline on create' do
+ expect {
+ post :create, params: {
+ name: 'Product With Video',
+ media: [
+ {
+ media_type: 'external_video',
+ external_video_url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+ position: 1
+ }
+ ]
+ }, as: :json
+ }.to change(Spree::Media, :count).by(1)
- # Product created, but the bad media entry was silently skipped —
- # ApplyMedia is strict about ALLOWED_MEDIA_TYPES.
expect(response).to have_http_status(:created)
- created = Spree::Product.find_by(name: 'Product Bad Type')
- expect(created.media).to be_empty
+
+ media = Spree::Product.find_by(name: 'Product With Video').media.first
+ expect(media.media_type).to eq('external_video')
+ expect(media.attachment).not_to be_attached
+ expect(media.external_video.provider).to eq('youtube')
+ end
+
+ it 'rejects an unknown media type' do
+ expect {
+ post :create, params: {
+ name: 'Product Bad Type',
+ media: [
+ { signed_id: blob.signed_id, media_type: 'audio' }
+ ]
+ }, as: :json
+ }.not_to change(Spree::Media, :count)
+
+ expect(response).to have_http_status(:unprocessable_content)
end
end
end
@@ -1251,7 +1271,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
{ signed_id: blob.signed_id, alt: 'A cat', position: 1 }
]
}, as: :json
- }.to change(Spree::Asset, :count).by(1)
+ }.to change(Spree::Media, :count).by(1)
expect(response).to have_http_status(:ok)
media = product.media.find_by(alt: 'A cat')
@@ -1260,7 +1280,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
end
it 'patches an existing media item by id' do
- existing = product.media.build(alt: 'Old', position: 1, type: 'Spree::Image')
+ existing = product.media.build(alt: 'Old', position: 1, type: 'Spree::Media')
existing.attachment.attach(blob)
existing.save!
@@ -1279,7 +1299,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
it 'assigns variant_ids when patching an existing media item' do
variant = create(:variant, product: product)
- existing = product.media.build(alt: 'Variant linked', position: 1, type: 'Spree::Image')
+ existing = product.media.build(alt: 'Variant linked', position: 1, type: 'Spree::Media')
existing.attachment.attach(blob)
existing.save!
@@ -1295,7 +1315,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
end
it 'leaves persisted media untouched when omitted from the payload' do
- kept = product.media.build(alt: 'Kept', position: 1, type: 'Spree::Image')
+ kept = product.media.build(alt: 'Kept', position: 1, type: 'Spree::Media')
kept.attachment.attach(blob)
kept.save!
@@ -1306,7 +1326,7 @@ RSpec.describe Spree::Api::V3::Admin::ProductsController, type: :controller do
{ signed_id: blob.signed_id, alt: 'New entry', position: 2 }
]
}, as: :json
- }.to change(Spree::Asset, :count).by(1)
+ }.to change(Spree::Media, :count).by(1)
expect(response).to have_http_status(:ok)
expect(product.media.where(id: kept.id)).to exist
diff --git a/spree/api/spec/serializers/spree/api/v3/asset_serializer_spec.rb b/spree/api/spec/serializers/spree/api/v3/media_event_serializer_spec.rb
similarity index 95%
rename from spree/api/spec/serializers/spree/api/v3/asset_serializer_spec.rb
rename to spree/api/spec/serializers/spree/api/v3/media_event_serializer_spec.rb
index 73b1a70a34..6847e1d42d 100644
--- a/spree/api/spec/serializers/spree/api/v3/asset_serializer_spec.rb
+++ b/spree/api/spec/serializers/spree/api/v3/media_event_serializer_spec.rb
@@ -2,7 +2,7 @@
require 'spec_helper'
-RSpec.describe Spree::Api::V3::AssetSerializer do
+RSpec.describe Spree::Api::V3::MediaEventSerializer do
let(:store) { @default_store }
let(:product) { create(:product) }
let(:asset) { create(:asset, viewable: product.default_variant) }
diff --git a/spree/core/app/helpers/spree/images_helper.rb b/spree/core/app/helpers/spree/images_helper.rb
index d4b8623b60..af7e450c69 100644
--- a/spree/core/app/helpers/spree/images_helper.rb
+++ b/spree/core/app/helpers/spree/images_helper.rb
@@ -101,7 +101,7 @@ module Spree
# in URLs and JSON converts symbols to strings, causing digest mismatches.
def spree_image_variant_options(options = {})
format_opt = options[:format]&.to_s
- saver_options = format_opt == "png" ? png_saver_options : Spree::Asset::WEBP_SAVER_OPTIONS
+ saver_options = format_opt == "png" ? png_saver_options : Spree::Media::WEBP_SAVER_OPTIONS
format = format_opt || "webp"
# Build hash in alphabetical order to match Active Storage's key ordering
diff --git a/spree/core/app/jobs/spree/media/migrate_product_assets_job.rb b/spree/core/app/jobs/spree/images/migrate_product_media_job.rb
similarity index 94%
rename from spree/core/app/jobs/spree/media/migrate_product_assets_job.rb
rename to spree/core/app/jobs/spree/images/migrate_product_media_job.rb
index 865663420b..8813b40c51 100644
--- a/spree/core/app/jobs/spree/media/migrate_product_assets_job.rb
+++ b/spree/core/app/jobs/spree/images/migrate_product_media_job.rb
@@ -1,7 +1,7 @@
module Spree
- module Media
+ module Images
# Per-product worker for the 5.4 → 5.5 media migration. Idempotent.
- class MigrateProductAssetsJob < Spree::BaseJob
+ class MigrateProductMediaJob < Spree::BaseJob
queue_as Spree.queues.images
def perform(product_id)
@@ -13,7 +13,7 @@ module Spree
viewable_ids = product.variants.map(&:id)
return if viewable_ids.empty?
- assets_by_variant = Spree::Asset
+ assets_by_variant = Spree::Media
.where(viewable_type: 'Spree::Variant', viewable_id: viewable_ids)
.pluck(:id, :viewable_id)
.group_by(&:last)
@@ -43,7 +43,7 @@ module Spree
private
def move_assets_to_product(asset_ids, product)
- Spree::Asset.where(id: asset_ids).update_all(
+ Spree::Media.where(id: asset_ids).update_all(
viewable_type: 'Spree::Product',
viewable_id: product.id,
updated_at: Time.current
diff --git a/spree/core/app/jobs/spree/images/save_from_url_job.rb b/spree/core/app/jobs/spree/images/save_from_url_job.rb
index 6371bc900c..3ea86b4797 100644
--- a/spree/core/app/jobs/spree/images/save_from_url_job.rb
+++ b/spree/core/app/jobs/spree/images/save_from_url_job.rb
@@ -14,7 +14,7 @@ module Spree
def perform(viewable_id, viewable_type, external_url, external_id = nil, position = nil, link_variant_id = nil)
viewable = viewable_type.safe_constantize.find(viewable_id)
- Spree::Image.ensure_custom_field_definition_exists!(Spree::Image::EXTERNAL_URL_CUSTOM_FIELD_KEY)
+ Spree::Media.ensure_custom_field_definition_exists!(Spree::Media::EXTERNAL_URL_CUSTOM_FIELD_KEY)
external_url = external_url.strip
external_id = external_id.to_s.downcase.strip if external_id.present?
diff --git a/spree/core/app/models/spree/asset.rb b/spree/core/app/models/spree/asset.rb
index d2d3b3f90f..9512640914 100644
--- a/spree/core/app/models/spree/asset.rb
+++ b/spree/core/app/models/spree/asset.rb
@@ -1,191 +1,16 @@
-module Spree
- class Asset < Spree.base_class
- has_prefix_id :media
-
- include Support::ActiveStorage
- include Rails.application.routes.url_helpers
- include Spree::HasCustomFields
- include Spree::Metadata
-
- # Legacy styles support (was in Spree::Image::Configuration::ActiveStorage)
- # @deprecated Will be removed in Spree 6
- def self.styles
- @styles ||= Spree::Config.product_image_variant_sizes.transform_values do |dimensions|
- "#{dimensions[0]}x#{dimensions[1]}>"
- end
- end
-
- def default_style
- :small
- end
-
- publishes_lifecycle_events
-
- EXTERNAL_URL_CUSTOM_FIELD_KEY = 'external.url'
- MEDIA_TYPES = %w[image video external_video].freeze
-
- after_initialize { self.media_type ||= 'image' }
-
- belongs_to :viewable, polymorphic: true, touch: true
- has_many :variant_media, class_name: 'Spree::VariantMedia', foreign_key: :media_id,
- dependent: :destroy, inverse_of: :asset
- has_many :variants, through: :variant_media, source: :variant, class_name: 'Spree::Variant'
- acts_as_list scope: [:viewable_id, :viewable_type]
-
- delegate :key, :attached?, :variant, :variable?, :blob, :filename, :variation, to: :attachment
-
- validates :media_type, inclusion: { in: MEDIA_TYPES }
- validates :attachment, attached: true, content_type: Rails.application.config.active_storage.web_image_content_types,
- if: -> { media_type == 'image' }
- validates :external_video_url, presence: true, if: -> { media_type.in?(%w[video external_video]) }
-
- WEBP_SAVER_OPTIONS = {
- strip: true,
- quality: 75,
- lossless: false,
- alpha_q: 85,
- reduction_effort: 6,
- smart_subsample: true
- }.freeze
-
- has_one_attached :attachment, service: Spree.public_storage_service_name do |attachable|
- # Note: Key order matters for variation digest matching.
- # Active Storage reorders keys alphabetically when calling variant(:name),
- # so we must define them in alphabetical order: format, resize_to_fill, saver
- #
- # IMPORTANT: Use string values (not symbols) for format because the variation key
- # is JSON-encoded in URLs. JSON converts symbols to strings, so "webp" != :webp
- # after round-tripping, which causes digest mismatches.
- Spree::Config.product_image_variant_sizes.each do |name, (width, height)|
- attachable.variant name,
- format: "webp",
- resize_to_fill: [width, height],
- saver: WEBP_SAVER_OPTIONS,
- preprocessed: true
- end
- end
-
- default_scope { includes(attachment_attachment: :blob) }
-
- # STI was disabled in Spree::Image, keep it disabled here
- self.inheritance_column = nil
-
- store_accessor :metadata, :session_uploaded_assets_uuid
- scope :with_session_uploaded_assets_uuid, lambda { |uuid|
- where(session_id: uuid)
- }
- scope :with_external_url, ->(url) { url.present? ? with_custom_field_key_value(EXTERNAL_URL_CUSTOM_FIELD_KEY, url.strip) : none }
-
- # Callbacks merged from Spree::Image
- after_commit :touch_product_variants, if: :should_touch_product_variants?, on: :update
- after_commit :update_viewable_thumbnail_on_create, on: :create
- after_commit :update_viewable_thumbnail_on_destroy, on: :destroy
- after_commit :update_viewable_thumbnail_on_reorder, on: :update, if: :saved_change_to_position?
- after_commit :update_viewable_thumbnail_on_viewable_change, on: :update, if: :saved_change_to_viewable_id?
-
- after_create :increment_viewable_media_count
- after_destroy :decrement_viewable_media_count
-
- def product
- @product ||= case viewable_type
- when 'Spree::Variant' then viewable&.product
- when 'Spree::Product' then viewable
- end
- end
+# frozen_string_literal: true
- # Accepts prefixed IDs ("variant_abc") or raw IDs from admin forms.
- # Variants from a different product are silently dropped — the security
- # boundary against form tampering.
- def variant_ids=(ids)
- return if viewable_type != 'Spree::Product' || product.blank?
-
- super(Spree::VariantMedia.resolve_variant_ids(product, ids || []))
- end
-
- def focal_point
- return nil if focal_point_x.nil? || focal_point_y.nil?
-
- { x: focal_point_x, y: focal_point_y }
- end
-
- def focal_point=(point)
- if point.nil?
- self.focal_point_x = nil
- self.focal_point_y = nil
- else
- self.focal_point_x = point[:x]
- self.focal_point_y = point[:y]
- end
- end
-
- def external_url
- get_custom_field(EXTERNAL_URL_CUSTOM_FIELD_KEY)&.value
- end
-
- def external_url=(url)
- set_custom_field(EXTERNAL_URL_CUSTOM_FIELD_KEY, url.strip)
- end
-
- def skip_import?
- false
- end
-
- def event_prefix
- 'media'
- end
-
- private
-
- def touch_product_variants
- product = viewable.is_a?(Spree::Product) ? viewable : viewable.product
- product.variants.touch_all
- end
-
- def should_touch_product_variants?
- return false unless saved_change_to_position?
-
- # Variants fall back to product-level media, so only reordering a
- # product-level asset changes what the variants display.
- viewable.is_a?(Spree::Product)
- end
-
- def increment_viewable_media_count
- case viewable
- when Spree::Variant
- Spree::Variant.increment_counter(:media_count, viewable_id)
- Spree::Product.increment_counter(:media_count, viewable.product_id)
- when Spree::Product
- Spree::Product.increment_counter(:media_count, viewable_id)
- end
- end
-
- def decrement_viewable_media_count
- case viewable
- when Spree::Variant
- Spree::Variant.decrement_counter(:media_count, viewable_id)
- Spree::Product.decrement_counter(:media_count, viewable.product_id)
- when Spree::Product
- Spree::Product.decrement_counter(:media_count, viewable_id)
- end
- end
-
- def update_viewable_thumbnail
- case viewable
- when Spree::Variant
- viewable.update_thumbnail!
- viewable.product.update_thumbnail!
- when Spree::Product
- viewable.update_thumbnail!
- # Linked variants resolve their own thumbnail through gallery_media,
- # which sorts by this asset's product-level position. Reorders or
- # destroys here can change a linked variant's first asset.
- variants.find_each(&:update_thumbnail!)
- end
- end
-
- alias update_viewable_thumbnail_on_create update_viewable_thumbnail
- alias update_viewable_thumbnail_on_destroy update_viewable_thumbnail
- alias update_viewable_thumbnail_on_reorder update_viewable_thumbnail
- alias update_viewable_thumbnail_on_viewable_change update_viewable_thumbnail
- end
+module Spree
+ # Deprecation alias for Spree::Media, renamed from Spree::Asset in 6.0.
+ # Retained for one release so existing code and extensions that reference
+ # Spree::Asset keep working; the canonical class is Spree::Media. Removed in
+ # 6.1, together with Spree::Image (which this replaces).
+ #
+ # This is a true constant alias — the underlying class, table (spree_media)
+ # and prefix (media) are all Spree::Media. Only the constant differs, so
+ # is_a?, polymorphic *_type strings, and class_name: references keep
+ # resolving to Spree::Media.
+ Asset = Media
+
+ Spree::Deprecation.warn('Spree::Asset is deprecated and will be removed in Spree 6.1. Use Spree::Media instead.')
end
diff --git a/spree/core/app/models/spree/asset/support/active_storage.rb b/spree/core/app/models/spree/asset/support/active_storage.rb
deleted file mode 100644
index c206571f9b..0000000000
--- a/spree/core/app/models/spree/asset/support/active_storage.rb
+++ /dev/null
@@ -1,26 +0,0 @@
-module Spree
- class Asset < Spree.base_class
- module Support
- module ActiveStorage
- extend ActiveSupport::Concern
-
- included do
- def url(style)
- return placeholder(style) unless attachment.attached?
-
- attachment.variant(resize_to_limit: dimensions_for_style(style))
- end
-
- def placeholder(style)
- "noimage/#{style}.png"
- end
-
- def dimensions_for_style(style)
- dimensions = self.class.styles.with_indifferent_access[style] || self.class.styles.with_indifferent_access[default_style]
- dimensions.split('x').map(&:to_i)
- end
- end
- end
- end
- end
-end
diff --git a/spree/core/app/models/spree/custom_field.rb b/spree/core/app/models/spree/custom_field.rb
index 36ffb6de87..edcd0ec9b7 100644
--- a/spree/core/app/models/spree/custom_field.rb
+++ b/spree/core/app/models/spree/custom_field.rb
@@ -129,10 +129,9 @@ module Spree
end
# A definition belongs to one resource type; attaching it to a different
- # one produces a row no lookup for either type would return. STI resources
- # store their base class in the polymorphic column (an Image row reads
- # `Spree::Asset`) while definitions name the concrete class, so compare
- # against the definition's base class too.
+ # one produces a row no lookup for either type would return. An STI row
+ # stores its base class in the polymorphic column while the definition
+ # names the subclass, so compare against the definition's base class too.
def resource_type_must_match_custom_field_definition
return if custom_field_definition.blank? || resource_type.blank?
diff --git a/spree/core/app/models/spree/external_video.rb b/spree/core/app/models/spree/external_video.rb
new file mode 100644
index 0000000000..5a3af64f08
--- /dev/null
+++ b/spree/core/app/models/spree/external_video.rb
@@ -0,0 +1,117 @@
+module Spree
+ # Value object that reads a YouTube or Vimeo link and tells you which
+ # provider it belongs to, which video it points at, and how to embed it.
+ #
+ # Spree does this once, at the write boundary, so the URL is validated before
+ # it is stored and every storefront reads the same derived values instead of
+ # re-implementing link parsing.
+ class ExternalVideo
+ include ActiveModel::Model
+ include ActiveModel::Attributes
+
+ YOUTUBE_HOSTS = %w[youtube.com www.youtube.com m.youtube.com youtu.be www.youtu.be].freeze
+ VIMEO_HOSTS = %w[vimeo.com www.vimeo.com player.vimeo.com].freeze
+
+ YOUTUBE_ID_FORMAT = /\A[\w-]{11}\z/
+ VIMEO_ID_FORMAT = /\A\d+\z/
+
+ attribute :provider, :string
+ attribute :video_id, :string
+
+ # Reads a URL and returns the video it describes, or nil when the URL is
+ # blank, malformed, or points somewhere Spree doesn't support.
+ #
+ # @param url [String, nil]
+ # @return [Spree::ExternalVideo, nil]
+ def self.parse(url)
+ return nil if url.blank?
+
+ uri = begin
+ URI.parse(url.strip)
+ rescue URI::InvalidURIError
+ return nil
+ end
+
+ return nil unless uri.scheme.in?(%w[http https])
+
+ host = uri.host&.downcase
+ return nil if host.blank?
+
+ if host.in?(YOUTUBE_HOSTS)
+ youtube_from(uri, host)
+ elsif host.in?(VIMEO_HOSTS)
+ vimeo_from(uri)
+ end
+ end
+
+ # @return [Boolean] whether the URL is one Spree can embed
+ def self.supported?(url)
+ parse(url).present?
+ end
+
+ # Path shapes that actually carry a video id. Anything else on the domain —
+ # /c/name, /@handle, /playlist — is not a video, and treating its last
+ # segment as an id yields an embed URL that plays nothing.
+ YOUTUBE_ID_PATHS = %w[embed shorts live v].freeze
+
+ def self.youtube_from(uri, host)
+ # Ignore empty segments so a trailing slash — ordinary when a URL is
+ # copied from the address bar — parses like the same link without one.
+ segments = uri.path.split('/').reject(&:blank?)
+
+ video_id =
+ if host.include?('youtu.be')
+ # A short link is the id and nothing else.
+ segments.first if segments.one?
+ elsif uri.path.chomp('/') == '/watch'
+ URI.decode_www_form(uri.query.to_s).to_h['v']
+ elsif segments.size == 2 && segments.first.in?(YOUTUBE_ID_PATHS)
+ segments.last
+ end
+
+ return nil unless video_id.to_s.match?(YOUTUBE_ID_FORMAT)
+
+ new(provider: 'youtube', video_id: video_id)
+ end
+ private_class_method :youtube_from
+
+ def self.vimeo_from(uri)
+ # /ID, /video/ID, /channels/name/ID all end in the numeric id.
+ video_id = uri.path.split('/').reject(&:blank?).last
+
+ return nil unless video_id.to_s.match?(VIMEO_ID_FORMAT)
+
+ new(provider: 'vimeo', video_id: video_id)
+ end
+ private_class_method :vimeo_from
+
+ # @return [String] URL for an iframe player
+ def embed_url
+ case provider
+ when 'youtube' then "https://www.youtube.com/embed/#{video_id}"
+ when 'vimeo' then "https://player.vimeo.com/video/#{video_id}"
+ end
+ end
+
+ # @return [String] canonical watch URL on the provider's own site
+ def watch_url
+ case provider
+ when 'youtube' then "https://www.youtube.com/watch?v=#{video_id}"
+ when 'vimeo' then "https://vimeo.com/#{video_id}"
+ end
+ end
+
+ # Provider-hosted still frame. YouTube serves one at a predictable URL;
+ # Vimeo requires an API call, so it has none here and the merchant uploads
+ # a poster instead.
+ #
+ # `hqdefault` is the only size YouTube guarantees for every video —
+ # `maxresdefault` 404s on anything without an HD source, which would leave
+ # a broken image as the video's only still.
+ #
+ # @return [String, nil]
+ def thumbnail_url
+ return "https://img.youtube.com/vi/#{video_id}/hqdefault.jpg" if provider == 'youtube'
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/image.rb b/spree/core/app/models/spree/image.rb
deleted file mode 100644
index 9b5b29cda1..0000000000
--- a/spree/core/app/models/spree/image.rb
+++ /dev/null
@@ -1,6 +0,0 @@
-# Backward compatibility — all logic now lives in Spree::Asset.
-# This class will be removed in Spree 6.0.
-module Spree
- class Image < Asset
- end
-end
diff --git a/spree/core/app/models/spree/line_item.rb b/spree/core/app/models/spree/line_item.rb
index 3194839b18..4f4e954529 100644
--- a/spree/core/app/models/spree/line_item.rb
+++ b/spree/core/app/models/spree/line_item.rb
@@ -76,7 +76,7 @@ module Spree
# Returns the thumbnail image for this line item
# Prefers variant primary media, falls back to product primary media
- # @return [Spree::Asset, nil]
+ # @return [Spree::Media, nil]
def thumbnail
variant.primary_media || product.primary_media
end
diff --git a/spree/core/app/models/spree/media.rb b/spree/core/app/models/spree/media.rb
new file mode 100644
index 0000000000..7914546d24
--- /dev/null
+++ b/spree/core/app/models/spree/media.rb
@@ -0,0 +1,364 @@
+module Spree
+ # Merchandising media for commerce entities — product photography, variant
+ # shots, product video. Renamed from Spree::Asset in 6.0; Spree::Asset stays
+ # readable as a deprecated alias for one release.
+ class Media < Spree.base_class
+ has_prefix_id :media
+
+ include Rails.application.routes.url_helpers
+ include Spree::HasCustomFields
+ include Spree::Metadata
+
+ publishes_lifecycle_events
+
+ EXTERNAL_URL_CUSTOM_FIELD_KEY = 'external.url'
+ MEDIA_TYPES = %w[image video external_video].freeze
+
+ # Domain attributes a client may write, shared by every write path — the
+ # media endpoints and the inline `media:` list on a product. Each path adds
+ # its own transport keys (an upload's signed id, a row id) on top. Adding a
+ # field here reaches both, so it can't be dropped on the one a client uses.
+ WRITABLE_ATTRIBUTES = %i[
+ alt position media_type external_video_url poster_signed_id
+ focal_point_x focal_point_y
+ ].freeze
+
+ after_initialize { self.media_type ||= 'image' }
+
+ belongs_to :viewable, polymorphic: true, touch: true
+ has_many :variant_media, class_name: 'Spree::VariantMedia', foreign_key: :media_id,
+ dependent: :destroy, inverse_of: :asset
+ has_many :variants, through: :variant_media, source: :variant, class_name: 'Spree::Variant'
+ acts_as_list scope: [:viewable_id, :viewable_type]
+
+ delegate :key, :attached?, :variant, :variable?, :blob, :filename, :variation, to: :attachment
+
+ validates :media_type, inclusion: { in: MEDIA_TYPES }
+ validates :attachment, attached: true, content_type: Rails.application.config.active_storage.web_image_content_types,
+ if: :image?
+ validates :attachment, attached: true, content_type: ->(_record) { Spree::Config.video_content_types },
+ size: { less_than_or_equal_to: ->(_record) { Spree::Config.max_video_upload_size } },
+ if: :video?
+ validates :poster, content_type: Rails.application.config.active_storage.web_image_content_types,
+ if: -> { poster.attached? }
+ validates :external_video_url, presence: true, if: :external_video?
+ validate :external_video_url_is_supported, if: -> { external_video? && external_video_url.present? }
+ validate :poster_signed_id_is_resolvable, if: -> { @poster_signed_id.present? }
+
+ WEBP_SAVER_OPTIONS = {
+ strip: true,
+ quality: 75,
+ lossless: false,
+ alpha_q: 85,
+ reduction_effort: 6,
+ smart_subsample: true
+ }.freeze
+
+ has_one_attached :attachment, service: Spree.public_storage_service_name do |attachable|
+ # Note: Key order matters for variation digest matching.
+ # Active Storage reorders keys alphabetically when calling variant(:name),
+ # so we must define them in alphabetical order: format, resize_to_fill, saver
+ #
+ # IMPORTANT: Use string values (not symbols) for format because the variation key
+ # is JSON-encoded in URLs. JSON converts symbols to strings, so "webp" != :webp
+ # after round-tripping, which causes digest mismatches.
+ Spree::Config.product_image_variant_sizes.each do |name, (width, height)|
+ attachable.variant name,
+ format: "webp",
+ resize_to_fill: [width, height],
+ saver: WEBP_SAVER_OPTIONS,
+ preprocessed: true
+ end
+ end
+
+ # Still frame shown wherever a video can't play — gallery tiles, emails,
+ # the admin grid. Optional: YouTube serves its own, and an uploaded video
+ # without one simply renders a placeholder.
+ has_one_attached :poster, service: Spree.public_storage_service_name do |attachable|
+ Spree::Config.product_image_variant_sizes.each do |name, (width, height)|
+ attachable.variant name,
+ format: "webp",
+ resize_to_fill: [width, height],
+ saver: WEBP_SAVER_OPTIONS,
+ preprocessed: true
+ end
+ end
+
+ # Both attachments load with the row — the serializer reads the poster for
+ # every video, so leaving it out costs a query per video in a listing.
+ default_scope { includes(attachment_attachment: :blob, poster_attachment: :blob) }
+
+ # `type` is a vestige of the old Spree::Image/Spree::Video STI —
+ # media_type is the discriminator now. The column drops in 6.1.
+ self.inheritance_column = nil
+
+ store_accessor :metadata, :session_uploaded_assets_uuid
+ scope :with_session_uploaded_assets_uuid, lambda { |uuid|
+ where(session_id: uuid)
+ }
+ scope :with_external_url, ->(url) { url.present? ? with_custom_field_key_value(EXTERNAL_URL_CUSTOM_FIELD_KEY, url.strip) : none }
+
+ after_commit :touch_product_variants, if: :should_touch_product_variants?, on: :update
+ after_commit :update_viewable_thumbnail_on_create, on: :create
+ after_commit :update_viewable_thumbnail_on_destroy, on: :destroy
+ after_commit :update_viewable_thumbnail_on_reorder, on: :update, if: :saved_change_to_position?
+ after_commit :update_viewable_thumbnail_on_viewable_change, on: :update, if: :saved_change_to_viewable?
+
+ after_save :apply_poster_signed_id, if: -> { defined?(@poster_signed_id) }
+ after_create :increment_viewable_media_count
+ after_destroy :decrement_viewable_media_count
+ after_update :move_viewable_media_count, if: :saved_change_to_viewable?
+
+ def image?
+ media_type == 'image'
+ end
+
+ def video?
+ media_type == 'video'
+ end
+
+ def external_video?
+ media_type == 'external_video'
+ end
+
+ # @return [Boolean] whether this row plays as video, hosted or embedded
+ def playable_video?
+ video? || external_video?
+ end
+
+ # Parsed form of external_video_url — provider, embed URL, watch URL.
+ # @return [Spree::ExternalVideo, nil]
+ def external_video
+ return nil unless external_video?
+
+ @external_video ||= Spree::ExternalVideo.parse(external_video_url)
+ end
+
+ # A plain writer so a poster rides mass-assignment like any other attribute,
+ # on every write path, instead of each caller reaching for the attachment.
+ #
+ # The attach is deferred to after_save: attaching on assignment uploads the
+ # blob even when the record then fails validation, orphaning it. A blank
+ # value removes the poster, so a merchant can undo a wrong one.
+ def poster_signed_id=(signed_id)
+ @poster_signed_id = signed_id
+ end
+
+ attr_reader :poster_signed_id
+
+ def external_video_url=(url)
+ @external_video = nil
+ super(url.is_a?(String) ? url.strip.presence : url)
+ end
+
+ # The one definition of "which image represents this row": an image is its
+ # own attachment, a video is its poster. Nil for a video with no poster —
+ # ask #provider_still_url for the provider's own thumbnail, which isn't an
+ # attachment and so can't be resized.
+ # @return [ActiveStorage::Attached::One, nil]
+ def still_image
+ source = playable_video? ? poster : attachment
+ source if source.attached?
+ end
+
+ # Provider-hosted still for an external video, when nothing was uploaded.
+ # @return [String, nil]
+ def provider_still_url
+ external_video&.thumbnail_url
+ end
+
+ # Whether this row can stand in as a thumbnail. A video qualifies only once
+ # it has a still — otherwise a gallery's first tile, and every listing that
+ # renders `thumbnail_url` in an <img>, would come back empty or with a raw
+ # video file.
+ # @return [Boolean]
+ def renderable_as_image?
+ still_image.present? || provider_still_url.present?
+ end
+
+ def product
+ @product ||= case viewable_type
+ when 'Spree::Variant' then viewable&.product
+ when 'Spree::Product' then viewable
+ end
+ end
+
+ # Accepts prefixed IDs ("variant_abc") or raw IDs from admin forms.
+ # Variants from a different product are silently dropped — the security
+ # boundary against form tampering.
+ def variant_ids=(ids)
+ return if viewable_type != 'Spree::Product' || product.blank?
+
+ super(Spree::VariantMedia.resolve_variant_ids(product, ids || []))
+ end
+
+ def focal_point
+ return nil if focal_point_x.nil? || focal_point_y.nil?
+
+ { x: focal_point_x, y: focal_point_y }
+ end
+
+ def focal_point=(point)
+ if point.nil?
+ self.focal_point_x = nil
+ self.focal_point_y = nil
+ else
+ self.focal_point_x = point[:x]
+ self.focal_point_y = point[:y]
+ end
+ end
+
+ def external_url
+ get_custom_field(EXTERNAL_URL_CUSTOM_FIELD_KEY)&.value
+ end
+
+ def external_url=(url)
+ set_custom_field(EXTERNAL_URL_CUSTOM_FIELD_KEY, url.strip)
+ end
+
+ def skip_import?
+ false
+ end
+
+ def event_prefix
+ 'media'
+ end
+
+ # Convention would resolve MediaSerializer — the full customer-facing
+ # payload with every image size. Events carry the lean shape instead.
+ def event_serializer_class
+ 'Spree::Api::V3::MediaEventSerializer'.safe_constantize
+ end
+
+ private
+
+ def apply_poster_signed_id
+ signed_id = @poster_signed_id
+ remove_instance_variable(:@poster_signed_id)
+
+ if signed_id.present?
+ poster.attach(signed_id)
+ elsif poster.attached?
+ # purge_later, not detach — detach leaves the blob behind in storage.
+ poster.purge_later
+ end
+ end
+
+ # A tampered or expired signed id raises deep inside `attach`, which would
+ # surface as a 500 after the row is already written. Resolve it up front so
+ # a bad one reads as a validation error on the field that carried it.
+ def poster_signed_id_is_resolvable
+ ActiveStorage::Blob.find_signed!(@poster_signed_id)
+ rescue ActiveSupport::MessageVerifier::InvalidSignature, ActiveRecord::RecordNotFound
+ errors.add(:poster, :invalid)
+ end
+
+ def external_video_url_is_supported
+ return if Spree::ExternalVideo.supported?(external_video_url)
+
+ errors.add(:external_video_url, :unsupported_video_provider)
+ end
+
+ def touch_product_variants
+ product = viewable.is_a?(Spree::Product) ? viewable : viewable.product
+ product.variants.touch_all
+ end
+
+ def should_touch_product_variants?
+ return false unless saved_change_to_position?
+
+ # Variants fall back to product-level media, so only reordering a
+ # product-level asset changes what the variants display.
+ viewable.is_a?(Spree::Product)
+ end
+
+ def increment_viewable_media_count
+ case viewable
+ when Spree::Variant
+ Spree::Variant.increment_counter(:media_count, viewable_id)
+ Spree::Product.increment_counter(:media_count, viewable.product_id)
+ when Spree::Product
+ Spree::Product.increment_counter(:media_count, viewable_id)
+ end
+ end
+
+ def decrement_viewable_media_count
+ case viewable
+ when Spree::Variant
+ Spree::Variant.decrement_counter(:media_count, viewable_id)
+ Spree::Product.decrement_counter(:media_count, viewable.product_id)
+ when Spree::Product
+ Spree::Product.decrement_counter(:media_count, viewable_id)
+ end
+ end
+
+ # A row that changes owner has already been counted against the old one.
+ # Without this the previous owner stays inflated and the new one short.
+ def move_viewable_media_count
+ adjust_media_count(*previous_owner, -1)
+ increment_viewable_media_count
+ end
+
+ # A move changes viewable_type, viewable_id, or both — read whichever
+ # actually changed, falling back to the current value for the other.
+ # @return [Array(String, Integer)] the owner this row was taken from
+ def previous_owner
+ [
+ saved_change_to_viewable_type&.first || viewable_type,
+ saved_change_to_viewable_id&.first || viewable_id
+ ]
+ end
+
+ def saved_change_to_viewable?
+ saved_change_to_viewable_id? || saved_change_to_viewable_type?
+ end
+
+ def adjust_media_count(type, id, by)
+ return if id.blank?
+
+ case type
+ when 'Spree::Variant'
+ variant = Spree::Variant.find_by(id: id) || return
+ Spree::Variant.update_counters(id, media_count: by)
+ Spree::Product.update_counters(variant.product_id, media_count: by)
+ when 'Spree::Product'
+ Spree::Product.update_counters(id, media_count: by) if Spree::Product.exists?(id: id)
+ end
+ end
+
+ def update_viewable_thumbnail
+ case viewable
+ when Spree::Variant
+ viewable.update_thumbnail!
+ viewable.product.update_thumbnail!
+ when Spree::Product
+ viewable.update_thumbnail!
+ # Linked variants resolve their own thumbnail through gallery_media,
+ # which sorts by this asset's product-level position. Reorders or
+ # destroys here can change a linked variant's first asset.
+ variants.find_each(&:update_thumbnail!)
+ end
+ end
+
+ # On a move, the owner left behind still points at this row through its
+ # primary_media_id — refresh it too, or it renders media it no longer has.
+ def update_viewable_thumbnail_on_viewable_change
+ type, id = previous_owner
+ previous = type&.safe_constantize&.find_by(id: id)
+
+ case previous
+ when Spree::Variant
+ previous.update_thumbnail!
+ previous.product&.update_thumbnail!
+ when Spree::Product
+ previous.update_thumbnail!
+ end
+
+ update_viewable_thumbnail
+ end
+
+ alias update_viewable_thumbnail_on_create update_viewable_thumbnail
+ alias update_viewable_thumbnail_on_destroy update_viewable_thumbnail
+ alias update_viewable_thumbnail_on_reorder update_viewable_thumbnail
+ end
+end
diff --git a/spree/core/app/models/spree/product.rb b/spree/core/app/models/spree/product.rb
index 5fcc405665..8f1696a5a3 100644
--- a/spree/core/app/models/spree/product.rb
+++ b/spree/core/app/models/spree/product.rb
@@ -178,11 +178,11 @@ module Spree
has_many :orders, through: :line_items
has_many :completed_orders, -> { reorder(nil).distinct.complete }, through: :line_items, source: :order
- has_many :media, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Asset'
+ has_many :media, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Media'
has_many :variant_images, -> { order(:position) }, source: :images, through: :variants
- belongs_to :primary_media, class_name: 'Spree::Asset', optional: true, foreign_key: :primary_media_id
+ belongs_to :primary_media, class_name: 'Spree::Media', optional: true, foreign_key: :primary_media_id
has_many :option_value_variants, class_name: 'Spree::OptionValueVariant', through: :variants
has_many :option_values, class_name: 'Spree::OptionValue', through: :variants
@@ -339,7 +339,7 @@ module Spree
# `[]` and trigger `dependent: :destroy` on every persisted asset.
# Explicit deletes go through the dedicated DELETE /media endpoint.
return if media_params.blank?
- return super if media_params.first.is_a?(Spree::Asset)
+ return super if media_params.first.is_a?(Spree::Media)
if new_record?
@pending_media_params = media_params
@@ -535,10 +535,13 @@ module Spree
@variant_for_images ||= find_variant_for_images
end
- # Returns secondary media for Product (for hover effects).
- # @return [Spree::Asset, nil]
+ # @deprecated Read #gallery_media directly; removed in 6.1. Nothing in
+ # Spree calls this — a hover image is a storefront presentation choice,
+ # not something core should name.
+ # @return [Spree::Media, nil]
def secondary_image
- variant_for_images&.secondary_image
+ Spree::Deprecation.warn('Spree::Product#secondary_image is deprecated and will be removed in Spree 6.1. Use #gallery_media instead.')
+ gallery_media.second
end
# @deprecated Use media_count instead
@@ -550,7 +553,14 @@ module Spree
# Checks product-level media first, then falls back to variant images.
# Called when media is added, removed, or reordered.
def update_thumbnail!
- first_media = media.order(:position).first || variant_images.order(:position).first
+ # Fresh scopes, never the cached associations — this runs from a media
+ # row's after_commit, where a loaded association is missing its siblings.
+ candidates = media.reload.order(:position).presence || variant_images.reload.order(:position)
+ # Only media that can draw as an image: `thumbnail_url` is rendered in an
+ # <img> everywhere it's used, so a video with no still leaves no
+ # thumbnail at all rather than a broken one.
+ first_media = candidates.find(&:renderable_as_image?)
+
update_column(:primary_media_id, first_media&.id)
end
@@ -844,35 +854,29 @@ module Spree
end
def apply_media(media_params)
- # Eager-load Asset descendants once so the type allowlist is stable across
- # the loop (and across requests once subclasses are referenced). Computed
- # per-call rather than at class-load to avoid forcing autoload of every
- # Asset subclass during boot.
- allowed_types = [Spree::Asset, *Spree::Asset.descendants].map(&:name).to_set
media_params.each do |raw|
attrs = raw.respond_to?(:to_h) ? raw.to_h : raw
attrs = attrs.with_indifferent_access
# Upsert path: entries with an `id` patch an existing asset (alt,
- # position, variant_ids). Entries with a `signed_id` create+attach.
+ # position, variant_ids, focal point, video URL). Entries with a
+ # `signed_id` create+attach; external videos create with neither.
# Omitting an entry leaves it alone — explicit DELETE on the dedicated
# media endpoint is still the only way to remove an asset.
asset_id = attrs.delete(:id)
if asset_id.present?
asset = media.find_by_param(asset_id) || next
- asset.update!(attrs.except(:signed_id, :type))
+ asset.update!(attrs.except(:signed_id))
next
end
signed_id = attrs.delete(:signed_id)
- next if signed_id.blank?
-
- media_type = attrs.delete(:type) || 'Spree::Image'
- next unless allowed_types.include?(media_type)
+ # An external video carries a URL instead of a file, so it's the one
+ # kind of new row that legitimately arrives without a signed id.
+ next if signed_id.blank? && attrs[:media_type] != 'external_video'
asset = media.build(attrs.except(:id))
- asset.type = media_type
- asset.attachment.attach(signed_id)
+ asset.attachment.attach(signed_id) if signed_id.present?
asset.save!
end
end
diff --git a/spree/core/app/models/spree/variant.rb b/spree/core/app/models/spree/variant.rb
index 76937b4318..36e5035e2f 100644
--- a/spree/core/app/models/spree/variant.rb
+++ b/spree/core/app/models/spree/variant.rb
@@ -58,17 +58,17 @@ module Spree
has_many :option_value_variants, class_name: 'Spree::OptionValueVariant'
has_many :option_values, through: :option_value_variants, dependent: :destroy, class_name: 'Spree::OptionValue'
- has_many :images, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Asset'
+ has_many :images, -> { order(:position) }, as: :viewable, dependent: :destroy, class_name: 'Spree::Media'
has_many :variant_media, class_name: 'Spree::VariantMedia', dependent: :destroy
# Order through the asset's product-level position so a variant's gallery
# follows whatever ordering the merchant set on the product. There's no
# per-variant reordering — link/unlink only.
has_many :associated_media,
- -> { order(Spree::Asset.arel_table[:position].asc) },
- through: :variant_media, source: :asset, class_name: 'Spree::Asset'
+ -> { order(Spree::Media.arel_table[:position].asc) },
+ through: :variant_media, source: :asset, class_name: 'Spree::Media'
- belongs_to :primary_media, class_name: 'Spree::Asset', optional: true, foreign_key: :primary_media_id
+ belongs_to :primary_media, class_name: 'Spree::Media', optional: true, foreign_key: :primary_media_id
has_many :prices,
class_name: 'Spree::Price',
@@ -446,20 +446,32 @@ module Spree
# Uses gallery_media so product-level assets linked via VariantMedia are
# considered alongside legacy variant-pinned images.
def update_thumbnail!
- first_media = gallery_media.first
+ # Read through a fresh scope, never the cached association — this runs
+ # from a media row's after_commit, and a loaded `images`/`associated_media`
+ # would be missing the sibling rows created after it.
+ candidates = gallery_media.reload.to_a
+ # See Product#update_thumbnail! — a video without a still can't be a thumbnail.
+ first_media = candidates.find(&:renderable_as_image?)
+
update_column(:primary_media_id, first_media&.id)
end
- # Returns second Image for Variant (for hover effects).
- # @return [Spree::Image, nil]
+ # @deprecated Read #gallery_media directly; removed in 6.1. Nothing in
+ # Spree calls this — a hover image is a storefront presentation choice,
+ # not something core should name.
+ # @return [Spree::Media, nil]
def secondary_image
- images.second
+ Spree::Deprecation.warn('Spree::Variant#secondary_image is deprecated and will be removed in Spree 6.1. Use #gallery_media instead.')
+ gallery_media.second
end
- # Returns all images except the primary media, combining variant and product images.
- # @return [Array<Spree::Image>]
+ # @deprecated Read #gallery_media directly; removed in 6.1. Nothing in
+ # Spree calls this, and which images to show beside the main one is a
+ # storefront presentation choice.
+ # @return [Array<Spree::Media>]
def additional_images
- @additional_images ||= (images + product.images).uniq.reject { |image| image.id == primary_media&.id }
+ Spree::Deprecation.warn('Spree::Variant#additional_images is deprecated and will be removed in Spree 6.1. Use #gallery_media instead.')
+ gallery_media.reject { |media| media.id == primary_media&.id }
end
# Returns an array of hashes with the option type name, value and presentation
diff --git a/spree/core/app/models/spree/variant_media.rb b/spree/core/app/models/spree/variant_media.rb
index e2ab45f180..4123c979f2 100644
--- a/spree/core/app/models/spree/variant_media.rb
+++ b/spree/core/app/models/spree/variant_media.rb
@@ -1,12 +1,11 @@
module Spree
- # FK column is `media_id` (not `asset_id`) to match the 6.0 rename
- # Spree::Asset → Spree::Media. The `:asset` association name follows the
- # current parent class; in 6.0 it renames to `:media` without a column change.
+ # FK column is `media_id`, matching Spree::Media and its table. The `:asset`
+ # association name stays readable for one release alongside `:media`.
class VariantMedia < Spree.base_class
self.table_name = 'spree_variant_media'
belongs_to :variant, class_name: 'Spree::Variant', touch: true
- belongs_to :asset, class_name: 'Spree::Asset', foreign_key: :media_id, inverse_of: :variant_media
+ belongs_to :asset, class_name: 'Spree::Media', foreign_key: :media_id, inverse_of: :variant_media
validates :variant, :asset, presence: true
validates :media_id, uniqueness: { scope: :variant_id }
@@ -17,7 +16,7 @@ module Spree
# Resolves an array of variant identifiers (prefixed ids or raw ids) to the
# numeric ids of variants that belong to `product`. Anything else — bad
# prefix, foreign product, garbage — is dropped. This is the security
- # boundary used by Spree::Asset#variant_ids=, so callers (forms, API params)
+ # boundary used by Spree::Media#variant_ids=, so callers (forms, API params)
# can't link assets to variants from another product.
def self.resolve_variant_ids(product, variant_ids)
ids = Array(variant_ids).reject(&:blank?)
diff --git a/spree/core/config/locales/en.yml b/spree/core/config/locales/en.yml
index 0194d63c07..b98f03392f 100644
--- a/spree/core/config/locales/en.yml
+++ b/spree/core/config/locales/en.yml
@@ -282,11 +282,6 @@ en:
attributes:
base:
cannot_destroy_used_gift_card: Can't delete a used gift card
- spree/image:
- attributes:
- attachment:
- attachment_must_be_present: must be present
- not_allowed_content_type: has not allowed content type
spree/import:
attributes:
attachment:
@@ -315,6 +310,13 @@ en:
country:
already_in_market: is already assigned to another market in this store
not_in_shipping_zone: is not covered by any shipping zone. Please set up a shipping zone first.
+ spree/media:
+ attributes:
+ attachment:
+ attachment_must_be_present: must be present
+ not_allowed_content_type: has not allowed content type
+ external_video_url:
+ unsupported_video_provider: must be a YouTube or Vimeo link
spree/payment:
attributes:
amount:
diff --git a/spree/core/db/migrate/20260315100000_add_product_media_support.rb b/spree/core/db/migrate/20260315100000_add_product_media_support.rb
index a2d428bb67..e4212e74c5 100644
--- a/spree/core/db/migrate/20260315100000_add_product_media_support.rb
+++ b/spree/core/db/migrate/20260315100000_add_product_media_support.rb
@@ -14,7 +14,10 @@ class AddProductMediaSupport < ActiveRecord::Migration[7.2]
reversible do |dir|
dir.up do
- Spree::Asset.unscoped.where(media_type: nil).update_all(media_type: 'image')
+ # Raw SQL against this migration's own table name — Spree::Asset became
+ # Spree::Media on a later migration, so reaching through the model here
+ # would look for a table that does not exist yet.
+ execute "UPDATE spree_assets SET media_type = 'image' WHERE media_type IS NULL"
end
end
end
diff --git a/spree/core/db/migrate/20260818090001_rename_assets_to_media.rb b/spree/core/db/migrate/20260818090001_rename_assets_to_media.rb
new file mode 100644
index 0000000000..56b4fc0d01
--- /dev/null
+++ b/spree/core/db/migrate/20260818090001_rename_assets_to_media.rb
@@ -0,0 +1,10 @@
+class RenameAssetsToMedia < ActiveRecord::Migration[8.1]
+ # The API, the prefixed id (`media_...`) and the join table have all said
+ # "media" since 5.4/5.5. This brings the table and model in line.
+ #
+ # `spree_variant_media.media_id` already points here under the right name, so
+ # no foreign-key column changes.
+ def change
+ rename_table :spree_assets, :spree_media
+ end
+end
diff --git a/spree/core/lib/spree/core/configuration.rb b/spree/core/lib/spree/core/configuration.rb
index 07e90551a8..fcb9ba2a9f 100644
--- a/spree/core/lib/spree/core/configuration.rb
+++ b/spree/core/lib/spree/core/configuration.rb
@@ -86,6 +86,18 @@ module Spree
og_image: [1200, 630]
}
end
+
+ # Content types accepted for uploaded product videos (media_type 'video').
+ # Kept deliberately narrow — these three play natively in every current
+ # browser, so a merchant never uploads a file their shoppers can't watch.
+ attr_writer :video_content_types
+
+ def video_content_types
+ @video_content_types ||= %w[video/mp4 video/webm video/quicktime]
+ end
+
+ # Maximum size of an uploaded product video, in bytes.
+ preference :max_video_upload_size, :integer, default: 524_288_000 # 500 MB
preference :layout, :string, deprecated: 'Please use Spree::Frontend::Config[:layout] instead'
preference :logo, :string, deprecated: true
preference :mailer_logo, :string, deprecated: true
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index b8da6c7101..66e15a9e77 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -438,14 +438,13 @@ module Spree
Rails.application.config.spree.custom_fields.enabled_resources = [
Spree::Address,
- Spree::Asset,
Spree::Claim,
Spree::Collection,
Spree::CreditCard,
Spree::Exchange,
Spree::GiftCard,
- Spree::Image,
Spree::LineItem,
+ Spree::Media,
Spree::NewsletterSubscriber,
Spree::OptionType,
Spree::OptionValue,
diff --git a/spree/core/lib/spree/core/permission_configuration.rb b/spree/core/lib/spree/core/permission_configuration.rb
index 792443c4e5..aefd7fe89d 100644
--- a/spree/core/lib/spree/core/permission_configuration.rb
+++ b/spree/core/lib/spree/core/permission_configuration.rb
@@ -293,7 +293,7 @@ module Spree
register_resource(:products, group: :catalog, audiences: %i[seller], subjects: -> {
[Spree::Product, Spree::ProductType, Spree::Variant, Spree::OptionType,
Spree::OptionValue, Spree::Price, Spree::PriceList, Spree::PriceRule,
- Spree::Asset, Spree::ProductPublication, Spree::CustomField]
+ Spree::Media, Spree::ProductPublication, Spree::CustomField]
})
register_resource(:categories, group: :catalog, subjects: -> {
[Spree::Category, Spree::ProductCategory]
diff --git a/spree/core/lib/spree/testing_support/factories/asset_factory.rb b/spree/core/lib/spree/testing_support/factories/asset_factory.rb
deleted file mode 100644
index c6b55f11d9..0000000000
--- a/spree/core/lib/spree/testing_support/factories/asset_factory.rb
+++ /dev/null
@@ -1,12 +0,0 @@
-FactoryBot.define do
- factory :asset, class: Spree::Asset do
- position { 1 }
- alt {}
-
- after(:build) do |asset|
- if asset.media_type == 'image' && !asset.attachment.attached?
- asset.attachment.attach(io: File.new(Spree::Core::Engine.root + 'spec/fixtures' + 'thinking-cat.jpg'), filename: 'thinking-cat.jpg')
- end
- end
- end
-end
diff --git a/spree/core/lib/spree/testing_support/factories/image_factory.rb b/spree/core/lib/spree/testing_support/factories/image_factory.rb
deleted file mode 100644
index 320ddcd0d8..0000000000
--- a/spree/core/lib/spree/testing_support/factories/image_factory.rb
+++ /dev/null
@@ -1,11 +0,0 @@
-FactoryBot.define do
- factory :image, class: Spree::Asset do
- media_type { 'image' }
-
- before(:create) do |image|
- if image.class.method_defined?(:attachment)
- image.attachment.attach(io: File.new(Spree::Core::Engine.root + 'spec/fixtures' + 'thinking-cat.jpg'), filename: 'thinking-cat.jpg')
- end
- end
- end
-end
diff --git a/spree/core/lib/spree/testing_support/factories/media_factory.rb b/spree/core/lib/spree/testing_support/factories/media_factory.rb
new file mode 100644
index 0000000000..a29c186818
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/media_factory.rb
@@ -0,0 +1,36 @@
+FactoryBot.define do
+ # `:asset` and `:image` are the pre-6.0 names, kept so existing suites and
+ # extensions keep building media without a rename.
+ factory :media, aliases: %i[asset image], class: Spree::Media do
+ position { 1 }
+ alt {}
+
+ after(:build) do |media|
+ if media.media_type == 'image' && !media.attachment.attached?
+ media.attachment.attach(
+ io: File.new(Spree::Core::Engine.root + 'spec/fixtures' + 'thinking-cat.jpg'),
+ filename: 'thinking-cat.jpg'
+ )
+ end
+ end
+
+ factory :video_media, aliases: [:video_asset] do
+ media_type { 'video' }
+
+ after(:build) do |media|
+ unless media.attachment.attached?
+ media.attachment.attach(
+ io: File.new(Spree::Core::Engine.root + 'spec/fixtures' + 'tiny-video.mp4'),
+ filename: 'tiny-video.mp4',
+ content_type: 'video/mp4'
+ )
+ end
+ end
+ end
+
+ factory :external_video_media, aliases: [:external_video_asset] do
+ media_type { 'external_video' }
+ external_video_url { 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' }
+ end
+ end
+end
diff --git a/spree/core/lib/spree/upgrades/5_4_to_5_5/manifest.yml b/spree/core/lib/spree/upgrades/5_4_to_5_5/manifest.yml
index 5bf06a79e5..a6fd39e285 100644
--- a/spree/core/lib/spree/upgrades/5_4_to_5_5/manifest.yml
+++ b/spree/core/lib/spree/upgrades/5_4_to_5_5/manifest.yml
@@ -24,7 +24,7 @@ steps:
name: "Migrate legacy variant-pinned images to product-level media"
task: "spree:media:migrate_master_images_to_product_media"
notes: |
- Enqueues one `Spree::Media::MigrateProductAssetsJob` per product onto
+ Enqueues one `Spree::Images::MigrateProductMediaJob` per product onto
the `images` queue — confirm your job runner is processing that queue.
Storefront keeps working while jobs drain (old assets stay variant-pinned
until each job finishes). For large catalogs, tune with BATCH_SIZE=1000.
diff --git a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
index 62d8b8aa56..17213efad7 100644
--- a/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
+++ b/spree/core/lib/spree/upgrades/5_6_to_6_0/manifest.yml
@@ -35,6 +35,34 @@ steps:
Idempotent, and a no-op on an already-consolidated schema.
+ - id: migrate_media_class_names
+ name: "Rewrite stored Spree::Asset and Spree::Image class names"
+ task: "spree:migrate_media_class_names"
+ notes: |
+ Spree::Asset and Spree::Image became Spree::Media in 6.0. The table rename
+ (spree_assets to spree_media) travels with db:migrate, but the old class
+ names are also written into data — custom field resource types, and any
+ polymorphic type column an extension points at media rows.
+
+ Run immediately after db:migrate. Spree::Asset stays readable as a
+ deprecated alias until 6.1, so code referencing it keeps working either
+ way; this step is about the stored strings.
+
+ Idempotent — rows already saying Spree::Media are left alone.
+
+ - id: migrate_master_images_to_product_media
+ name: "Re-home variant-pinned media onto the product"
+ task: "spree:media:migrate_master_images_to_product_media"
+ notes: |
+ Moves images pinned to a variant onto the product's own gallery, linking
+ them back to the variants that had them. Enqueues one background job per
+ affected product, so let the queue drain before the next step.
+
+ Run this BEFORE spree:remove_master_variant — deleting a ghost master
+ variant that still owns media would take the media with it.
+
+ Idempotent — re-running skips products that are already migrated.
+
- id: remove_master_variant
name: "Migrate products off the master variant"
task: "spree:remove_master_variant"
diff --git a/spree/core/lib/tasks/media.rake b/spree/core/lib/tasks/media.rake
index 4652926e3d..008dc7e048 100644
--- a/spree/core/lib/tasks/media.rake
+++ b/spree/core/lib/tasks/media.rake
@@ -17,7 +17,7 @@ namespace :spree do
puts 'Done!'
end
- # Enqueues Spree::Media::MigrateProductAssetsJob for every product that
+ # Enqueues Spree::Images::MigrateProductMediaJob for every product that
# still has at least one variant-pinned asset. The job is idempotent, so
# re-running this task is safe.
#
@@ -38,7 +38,7 @@ namespace :spree do
relation = Spree::Product.where(id: variant_product_ids)
relation.find_each(batch_size: batch_size) do |product|
- Spree::Media::MigrateProductAssetsJob.perform_later(product.id)
+ Spree::Images::MigrateProductMediaJob.perform_later(product.id)
end
puts "Enqueued migration jobs for #{relation.count} products on the #{Spree.queues.images} queue."
diff --git a/spree/core/lib/tasks/media_class_rename.rake b/spree/core/lib/tasks/media_class_rename.rake
new file mode 100644
index 0000000000..fac81a3436
--- /dev/null
+++ b/spree/core/lib/tasks/media_class_rename.rake
@@ -0,0 +1,56 @@
+namespace :spree do
+ # Spree::Asset and Spree::Image became Spree::Media in 6.0. The table rename
+ # travels with db:migrate, but the old class names are also written into data:
+ # Active Storage's polymorphic owner column, and custom field resource types.
+ #
+ # The Active Storage rows are the critical ones — every product image and
+ # video is attached through `record_type`, so without this step the files are
+ # orphaned from their media rows.
+ #
+ # Idempotent — rows already carrying 'Spree::Media' are left alone.
+ desc 'Rewrite stored Spree::Asset / Spree::Image class names to Spree::Media (6.0)'
+ task migrate_media_class_names: :environment do
+ legacy_names = %w[Spree::Asset Spree::Image]
+
+ # A definition for Spree::Image may already exist alongside one for
+ # Spree::Asset with the same namespace and key. Renaming both would violate
+ # the definition's uniqueness, so fold the duplicates into the survivor
+ # before the bulk rewrite below touches them.
+ # Group by what the uniqueness index covers. Any group holding more than one
+ # row collapses to a single survivor — including a group of only legacy rows
+ # (a Spree::Asset and a Spree::Image sharing a key), which would otherwise
+ # both rewrite to Spree::Media and collide.
+ puts 'Merging duplicate custom field definitions...'
+ Spree::CustomFieldDefinition.transaction do
+ Spree::CustomFieldDefinition.
+ where(resource_type: legacy_names + ['Spree::Media']).
+ group_by { |definition| [definition.namespace, definition.key] }.
+ each_value do |group|
+ next if group.one?
+
+ # Prefer a row already on the new name so its id keeps its custom fields.
+ survivor = group.find { |definition| definition.resource_type == 'Spree::Media' } || group.first
+
+ (group - [survivor]).each do |duplicate|
+ Spree::CustomField.where(custom_field_definition_id: duplicate.id).
+ update_all(custom_field_definition_id: survivor.id)
+ duplicate.delete
+ end
+ end
+ end
+
+ puts 'Rewriting renamed class-name strings...'
+ [
+ [ActiveStorage::Attachment, :record_type],
+ [Spree::CustomField, :resource_type],
+ [Spree::CustomFieldDefinition, :resource_type]
+ ].each do |model, column|
+ legacy_names.each do |legacy_name|
+ count = model.where(column => legacy_name).update_all(column => 'Spree::Media')
+ puts " #{model.table_name}.#{column}: #{count} rows #{legacy_name} -> Spree::Media"
+ end
+ end
+
+ puts 'Done!'
+ end
+end
diff --git a/spree/core/spec/fixtures/tiny-video.mp4 b/spree/core/spec/fixtures/tiny-video.mp4
new file mode 100644
index 0000000000..1f415278a8
Binary files /dev/null and b/spree/core/spec/fixtures/tiny-video.mp4 differ
diff --git a/spree/core/spec/jobs/spree/media/migrate_product_assets_job_spec.rb b/spree/core/spec/jobs/spree/images/migrate_product_media_job_spec.rb
similarity index 95%
rename from spree/core/spec/jobs/spree/media/migrate_product_assets_job_spec.rb
rename to spree/core/spec/jobs/spree/images/migrate_product_media_job_spec.rb
index b8a0636867..b03afde88b 100644
--- a/spree/core/spec/jobs/spree/media/migrate_product_assets_job_spec.rb
+++ b/spree/core/spec/jobs/spree/images/migrate_product_media_job_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-RSpec.describe Spree::Media::MigrateProductAssetsJob, type: :job do
+RSpec.describe Spree::Images::MigrateProductMediaJob, type: :job do
subject { described_class.perform_now(product.id) }
describe '#perform' do
@@ -64,7 +64,7 @@ RSpec.describe Spree::Media::MigrateProductAssetsJob, type: :job do
it 'does not duplicate assets even when historical line items exist' do
create(:line_item, variant: variant)
- expect { subject }.not_to change(Spree::Asset, :count)
+ expect { subject }.not_to change(Spree::Media, :count)
end
end
@@ -94,7 +94,7 @@ RSpec.describe Spree::Media::MigrateProductAssetsJob, type: :job do
described_class.perform_now(product.id)
expect { described_class.perform_now(product.id) }.not_to change(Spree::VariantMedia, :count)
- expect(Spree::Asset.count).to eq(1)
+ expect(Spree::Media.count).to eq(1)
end
end
@@ -102,7 +102,7 @@ RSpec.describe Spree::Media::MigrateProductAssetsJob, type: :job do
let!(:product) { create(:product) }
it 'is a no-op for asset counts' do
- expect { subject }.not_to change(Spree::Asset, :count)
+ expect { subject }.not_to change(Spree::Media, :count)
end
it 'is a no-op for VariantMedia counts' do
diff --git a/spree/core/spec/jobs/spree/images/save_from_url_job_spec.rb b/spree/core/spec/jobs/spree/images/save_from_url_job_spec.rb
index 75dae72c9f..9007bde0ba 100644
--- a/spree/core/spec/jobs/spree/images/save_from_url_job_spec.rb
+++ b/spree/core/spec/jobs/spree/images/save_from_url_job_spec.rb
@@ -33,7 +33,7 @@ RSpec.describe Spree::Images::SaveFromUrlJob, type: :job do
end
it "downloads and attaches image from the URL" do
- expect { subject }.to change(Spree::Image, :count).by(1)
+ expect { subject }.to change(Spree::Media, :count).by(1)
expect(image.attachment).to be_attached
expect(image.external_url).to eq(external_url.strip)
expect(image.position).to eq(1)
@@ -83,7 +83,7 @@ RSpec.describe Spree::Images::SaveFromUrlJob, type: :job do
end
it 'discards the job without downloading' do
- expect { subject }.not_to change(Spree::Image, :count)
+ expect { subject }.not_to change(Spree::Media, :count)
end
end
@@ -113,7 +113,7 @@ RSpec.describe Spree::Images::SaveFromUrlJob, type: :job do
link = Spree::VariantMedia.last
expect(link.variant_id).to eq(linked_variant.id)
- expect(link.media_id).to eq(Spree::Image.last.id)
+ expect(link.media_id).to eq(Spree::Media.last.id)
end
it 'is idempotent on repeat invocations' do
diff --git a/spree/core/spec/lib/tasks/media_class_rename_spec.rb b/spree/core/spec/lib/tasks/media_class_rename_spec.rb
new file mode 100644
index 0000000000..0b9b733a17
--- /dev/null
+++ b/spree/core/spec/lib/tasks/media_class_rename_spec.rb
@@ -0,0 +1,93 @@
+require 'spec_helper'
+require 'rake'
+
+describe 'spree:migrate_media_class_names' do
+ subject { Rake::Task[task_name] }
+
+ let(:task_name) { 'spree:migrate_media_class_names' }
+
+ before(:all) do
+ Rake::Task.define_task(:environment)
+ load Spree::Core::Engine.root.join('lib', 'tasks', 'media_class_rename.rake')
+ end
+
+ before { subject.reenable }
+
+ let!(:media) { create(:image) }
+
+ # Simulates a pre-6.0 install: the rows still name the class by its old name.
+ def name_rows_legacy!(legacy_name)
+ ActiveStorage::Attachment.where(record_id: media.id, record_type: 'Spree::Media').
+ update_all(record_type: legacy_name)
+ end
+
+ it 'reattaches files whose owner is still named Spree::Asset' do
+ name_rows_legacy!('Spree::Asset')
+
+ expect { subject.invoke }.to change {
+ ActiveStorage::Attachment.where(record_id: media.id, record_type: 'Spree::Media').count
+ }.from(0).to(1)
+
+ expect(media.reload.attachment).to be_attached
+ end
+
+ it 'reattaches files whose owner is still named Spree::Image' do
+ name_rows_legacy!('Spree::Image')
+
+ subject.invoke
+
+ expect(media.reload.attachment).to be_attached
+ end
+
+ it 'rewrites custom field resource types' do
+ definition = create(:custom_field_definition, resource_type: 'Spree::Media', key: 'legacy_key')
+ custom_field = create(:custom_field, custom_field_definition: definition, resource: media, value: 'x')
+ Spree::CustomField.where(id: custom_field.id).update_all(resource_type: 'Spree::Asset')
+
+ subject.invoke
+
+ expect(custom_field.reload.resource_type).to eq('Spree::Media')
+ end
+
+ it 'folds a legacy definition into the one that already uses the new name' do
+ survivor = create(:custom_field_definition, resource_type: 'Spree::Media', key: 'shared_key')
+ legacy = create(:custom_field_definition, resource_type: 'Spree::Media', key: 'shared_key_legacy')
+ Spree::CustomFieldDefinition.where(id: legacy.id).
+ update_all(resource_type: 'Spree::Asset', key: 'shared_key')
+ custom_field = create(:custom_field, custom_field_definition: legacy, resource: media, value: 'y')
+
+ subject.invoke
+
+ expect(Spree::CustomFieldDefinition.exists?(legacy.id)).to be(false)
+ expect(custom_field.reload.custom_field_definition_id).to eq(survivor.id)
+ end
+
+ it 'collapses two legacy definitions that share a key with no survivor' do
+ # Both rewrite to Spree::Media, so without a merge the second violates the
+ # uniqueness index and aborts the task partway through.
+ asset_def = create(:custom_field_definition, resource_type: 'Spree::Media', key: 'shared')
+ image_def = create(:custom_field_definition, resource_type: 'Spree::Media', key: 'shared_two')
+ Spree::CustomFieldDefinition.where(id: asset_def.id).
+ update_all(resource_type: 'Spree::Asset', key: 'shared')
+ Spree::CustomFieldDefinition.where(id: image_def.id).
+ update_all(resource_type: 'Spree::Image', key: 'shared')
+
+ expect { subject.invoke }.not_to raise_error
+
+ survivors = Spree::CustomFieldDefinition.where(key: 'shared')
+ expect(survivors.count).to eq(1)
+ expect(survivors.first.resource_type).to eq('Spree::Media')
+ end
+
+ it 'is idempotent' do
+ name_rows_legacy!('Spree::Asset')
+ subject.invoke
+ subject.reenable
+
+ expect { subject.invoke }.not_to change {
+ ActiveStorage::Attachment.where(record_id: media.id, record_type: 'Spree::Media').count
+ }
+
+ expect(media.reload.attachment).to be_attached
+ end
+end
diff --git a/spree/core/spec/lib/tasks/media_spec.rb b/spree/core/spec/lib/tasks/media_spec.rb
index f297d56e89..8a9b8b8e5c 100644
--- a/spree/core/spec/lib/tasks/media_spec.rb
+++ b/spree/core/spec/lib/tasks/media_spec.rb
@@ -25,9 +25,9 @@ describe 'spree:media:migrate_master_images_to_product_media' do
let!(:variant_image) { create(:image, viewable: variant) }
it 'enqueues a job for each product with variant-pinned assets' do
- expect { subject.invoke }.to have_enqueued_job(Spree::Media::MigrateProductAssetsJob)
+ expect { subject.invoke }.to have_enqueued_job(Spree::Images::MigrateProductMediaJob)
.with(product_with_master_image.id)
- .and have_enqueued_job(Spree::Media::MigrateProductAssetsJob)
+ .and have_enqueued_job(Spree::Images::MigrateProductMediaJob)
.with(product_with_variant_image.id)
end
@@ -43,7 +43,7 @@ describe 'spree:media:migrate_master_images_to_product_media' do
let!(:product) { create(:product) }
it 'enqueues nothing' do
- expect { subject.invoke }.not_to have_enqueued_job(Spree::Media::MigrateProductAssetsJob)
+ expect { subject.invoke }.not_to have_enqueued_job(Spree::Images::MigrateProductMediaJob)
end
end
@@ -59,7 +59,7 @@ describe 'spree:media:migrate_master_images_to_product_media' do
subject.invoke
subject.reenable
- expect { subject.invoke }.to have_enqueued_job(Spree::Media::MigrateProductAssetsJob)
+ expect { subject.invoke }.to have_enqueued_job(Spree::Images::MigrateProductMediaJob)
.with(product.id)
end
end
diff --git a/spree/core/spec/models/spree/custom_field_spec.rb b/spree/core/spec/models/spree/custom_field_spec.rb
index 83f1340ad6..abb044aa55 100644
--- a/spree/core/spec/models/spree/custom_field_spec.rb
+++ b/spree/core/spec/models/spree/custom_field_spec.rb
@@ -117,11 +117,18 @@ RSpec.describe Spree::CustomField, type: :model do
end
it 'accepts a definition naming an STI subclass of the resource' do
- # Images store `Spree::Asset` in the polymorphic column, while the
- # definition names the concrete `Spree::Image`.
- image_definition = create(:custom_field_definition, resource_type: 'Spree::Image', key: 'sti_key')
- custom_field = build(:custom_field, custom_field_definition: image_definition, value: 'x')
- custom_field.resource_type = 'Spree::Asset'
+ # An STI row stores its base class in the polymorphic column while the
+ # definition names the subclass, so the two still have to match up.
+ subclass = Class.new(Spree::Variant) do
+ def self.name = 'Spree::TestVariantSubclass'
+ end
+ stub_const('Spree::TestVariantSubclass', subclass)
+ allow(Spree::CustomFieldDefinition).to receive(:available_resources).
+ and_return(Spree::CustomFieldDefinition.available_resources + [subclass])
+
+ definition = create(:custom_field_definition, resource_type: 'Spree::TestVariantSubclass', key: 'sti_key')
+ custom_field = build(:custom_field, custom_field_definition: definition, value: 'x')
+ custom_field.resource_type = 'Spree::Variant'
custom_field.valid?
expect(custom_field.errors[:resource_type]).to be_empty
diff --git a/spree/core/spec/models/spree/external_video_spec.rb b/spree/core/spec/models/spree/external_video_spec.rb
new file mode 100644
index 0000000000..2ac209403c
--- /dev/null
+++ b/spree/core/spec/models/spree/external_video_spec.rb
@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+RSpec.describe Spree::ExternalVideo do
+ describe '.parse' do
+ context 'YouTube' do
+ {
+ 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' => 'dQw4w9WgXcQ',
+ 'https://m.youtube.com/watch?v=dQw4w9WgXcQ&t=42' => 'dQw4w9WgXcQ',
+ 'https://youtu.be/dQw4w9WgXcQ' => 'dQw4w9WgXcQ',
+ 'https://www.youtube.com/embed/dQw4w9WgXcQ' => 'dQw4w9WgXcQ',
+ 'https://www.youtube.com/shorts/dQw4w9WgXcQ' => 'dQw4w9WgXcQ'
+ }.each do |url, video_id|
+ it "reads #{url}" do
+ video = described_class.parse(url)
+
+ expect(video.provider).to eq('youtube')
+ expect(video.video_id).to eq(video_id)
+ expect(video.embed_url).to eq("https://www.youtube.com/embed/#{video_id}")
+ expect(video.watch_url).to eq("https://www.youtube.com/watch?v=#{video_id}")
+ expect(video.thumbnail_url).to eq("https://img.youtube.com/vi/#{video_id}/hqdefault.jpg")
+ end
+ end
+ end
+
+ context 'Vimeo' do
+ {
+ 'https://vimeo.com/123456789' => '123456789',
+ 'https://player.vimeo.com/video/123456789' => '123456789',
+ 'https://vimeo.com/channels/staffpicks/123456789' => '123456789'
+ }.each do |url, video_id|
+ it "reads #{url}" do
+ video = described_class.parse(url)
+
+ expect(video.provider).to eq('vimeo')
+ expect(video.video_id).to eq(video_id)
+ expect(video.embed_url).to eq("https://player.vimeo.com/video/#{video_id}")
+ expect(video.watch_url).to eq("https://vimeo.com/#{video_id}")
+ end
+ end
+
+ it 'has no provider thumbnail' do
+ expect(described_class.parse('https://vimeo.com/123456789').thumbnail_url).to be_nil
+ end
+ end
+
+ # The dashboard mirrors this parser to validate as the merchant types. If
+ # the two disagree, the dialog accepts a link the server then rejects —
+ # failing the whole product save.
+ it 'accepts a trailing slash, as an address-bar copy carries' do
+ expect(described_class.parse('https://youtu.be/dQw4w9WgXcQ/')&.video_id).to eq('dQw4w9WgXcQ')
+ expect(described_class.parse('https://vimeo.com/123456789/')&.video_id).to eq('123456789')
+ expect(described_class.parse('https://www.youtube.com/watch/?v=dQw4w9WgXcQ')&.video_id).
+ to eq('dQw4w9WgXcQ')
+ end
+
+ it 'ignores surrounding whitespace' do
+ expect(described_class.parse(' https://vimeo.com/123456789 ').video_id).to eq('123456789')
+ end
+
+ [
+ # Not videos: a channel, an arbitrary nested path, or a short link with
+ # anything after the id.
+ 'https://www.youtube.com/c/dQw4w9WgXcQ',
+ 'https://www.youtube.com/not-a-video/ABCDEFGHIJK',
+ 'https://youtu.be/dQw4w9WgXcQ/extra',
+ 'https://example.com/video.mp4',
+ 'https://www.youtube.com/watch?v=short',
+ 'https://vimeo.com/not-a-number',
+ 'javascript:alert(1)',
+ 'not a url',
+ '',
+ nil
+ ].each do |url|
+ it "returns nil for #{url.inspect}" do
+ expect(described_class.parse(url)).to be_nil
+ end
+ end
+ end
+
+ describe '.supported?' do
+ it 'is true for a link Spree can embed' do
+ expect(described_class).to be_supported('https://vimeo.com/123456789')
+ end
+
+ it 'is false for anything else' do
+ expect(described_class).not_to be_supported('https://example.com/clip.mp4')
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/image_spec.rb b/spree/core/spec/models/spree/media_counters_spec.rb
similarity index 58%
rename from spree/core/spec/models/spree/image_spec.rb
rename to spree/core/spec/models/spree/media_counters_spec.rb
index 6f8ae9e410..dc27398d2c 100644
--- a/spree/core/spec/models/spree/image_spec.rb
+++ b/spree/core/spec/models/spree/media_counters_spec.rb
@@ -1,29 +1,29 @@
require 'spec_helper'
-describe Spree::Image, type: :model do
- let(:spree_image) { described_class.new }
+describe Spree::Media, type: :model do
+ let(:media) { described_class.new }
let(:image_file) { File.open("#{Spree::Core::Engine.root}/spec/fixtures/thinking-cat.jpg") }
let(:text_file) { File.open("#{Spree::Core::Engine.root}/spec/fixtures/text-file.txt") }
context 'validation' do
it 'has attachment present' do
- spree_image.attachment.attach(io: image_file, filename: 'thinking-cat.jpg')
- expect(spree_image).to be_valid
+ media.attachment.attach(io: image_file, filename: 'thinking-cat.jpg')
+ expect(media).to be_valid
end
it 'has attachment absent' do
- spree_image.attachment.attach(nil)
- expect(spree_image).not_to be_valid
+ media.attachment.attach(nil)
+ expect(media).not_to be_valid
end
it 'allows only web image content types' do
- spree_image.attachment.attach(io: image_file, filename: 'thinking-cat.jpg', content_type: 'image/jpeg')
- expect(spree_image).to be_valid
+ media.attachment.attach(io: image_file, filename: 'thinking-cat.jpg', content_type: 'image/jpeg')
+ expect(media).to be_valid
end
it 'does not allow non-web image content types' do
- spree_image.attachment.attach(io: text_file, filename: 'text-file.txt', content_type: 'text/plain')
- expect(spree_image).not_to be_valid
+ media.attachment.attach(io: text_file, filename: 'text-file.txt', content_type: 'text/plain')
+ expect(media).not_to be_valid
end
end
@@ -102,6 +102,87 @@ describe Spree::Image, type: :model do
end
end
+ describe 'thumbnail choice with video in the gallery' do
+ let(:product) { create(:product) }
+
+ it 'skips a leading video that has no still' do
+ video = create(:video_asset, viewable: product, position: 1)
+ image = create(:image, viewable: product, position: 2)
+
+ product.update_thumbnail!
+
+ expect(product.reload.primary_media_id).to eq(image.id)
+ expect(video.renderable_as_image?).to be(false)
+ end
+
+ it 'leaves no thumbnail when every row is a video without a still' do
+ create(:video_asset, viewable: product, position: 1)
+
+ product.update_thumbnail!
+
+ # Better none than one that renders as a broken image.
+ expect(product.reload.primary_media_id).to be_nil
+ end
+
+ it 'leaves a variant without a thumbnail on the same terms' do
+ variant = create(:variant, product: product)
+ create(:video_asset, viewable: variant, position: 1)
+
+ variant.update_thumbnail!
+
+ expect(variant.reload.primary_media_id).to be_nil
+ end
+
+ it 'uses a leading video once it has a still' do
+ video = create(:external_video_asset, viewable: product, position: 1)
+ create(:image, viewable: product, position: 2)
+
+ product.update_thumbnail!
+
+ # A YouTube link carries the provider's own thumbnail, so it can lead.
+ expect(product.reload.primary_media_id).to eq(video.id)
+ end
+ end
+
+ describe 'media_count when a row changes owner' do
+ let(:product) { create(:product) }
+ let(:other_product) { create(:product) }
+
+ it 'clears the old owner thumbnail, which still pointed at the moved row' do
+ media = create(:image, viewable: product)
+ expect(product.reload.primary_media_id).to eq(media.id)
+
+ media.update!(viewable: other_product)
+
+ expect(product.reload.primary_media_id).to be_nil
+ expect(other_product.reload.primary_media_id).to eq(media.id)
+ end
+
+ it 'treats a type-only change as a move' do
+ variant = create(:variant, product: product)
+ media = create(:image, viewable: variant)
+
+ # Same numeric id on both sides, so only viewable_type changes. Watching
+ # viewable_id alone would sit this move out and leave both owners wrong.
+ Spree::Media.where(id: media.id).update_all(viewable_id: product.id)
+ media.reload
+ media.update!(viewable_type: 'Spree::Product')
+
+ expect(media.send(:saved_change_to_viewable?)).to be(true)
+ expect(media.reload.viewable).to eq(product)
+ end
+
+ it 'moves the count from the old owner to the new one' do
+ media = create(:image, viewable: product)
+ expect(product.reload.media_count).to eq(1)
+
+ media.update!(viewable: other_product)
+
+ expect(product.reload.media_count).to eq(0)
+ expect(other_product.reload.media_count).to eq(1)
+ end
+ end
+
describe 'primary_media_id updates' do
let(:product) { create(:product) }
let(:variant) { product.default_variant }
diff --git a/spree/core/spec/models/spree/asset_spec.rb b/spree/core/spec/models/spree/media_spec.rb
similarity index 57%
rename from spree/core/spec/models/spree/asset_spec.rb
rename to spree/core/spec/models/spree/media_spec.rb
index 9a4cda1851..02bc099349 100644
--- a/spree/core/spec/models/spree/asset_spec.rb
+++ b/spree/core/spec/models/spree/media_spec.rb
@@ -1,6 +1,6 @@
require 'spec_helper'
-describe Spree::Asset, type: :model do
+describe Spree::Media, type: :model do
it_behaves_like 'metadata'
it_behaves_like 'lifecycle events', event_prefix: 'media'
@@ -83,14 +83,158 @@ describe Spree::Asset, type: :model do
end
it 'defaults to image' do
- asset = Spree::Asset.new
+ asset = Spree::Media.new
expect(asset.media_type).to eq('image')
end
- it 'defaults to image for Spree::Image subclass' do
- image = Spree::Image.new
+ it 'defaults to image for Spree::Media subclass' do
+ image = Spree::Media.new
expect(image.media_type).to eq('image')
end
+
+ it 'answers a predicate per media type' do
+ expect(build(:asset)).to be_image
+ expect(build(:video_asset)).to be_video
+ expect(build(:external_video_asset)).to be_external_video
+ end
+ end
+
+ describe 'video' do
+ it 'accepts an uploaded video file' do
+ expect(build(:video_asset)).to be_valid
+ end
+
+ it 'requires a file, not a URL' do
+ asset = build(:asset, media_type: 'video')
+ asset.attachment.detach
+
+ expect(asset).not_to be_valid
+ expect(asset.errors[:attachment]).to be_present
+ end
+
+ it 'rejects a file type browsers cannot play' do
+ asset = build(:asset, media_type: 'video')
+ asset.attachment.attach(
+ io: File.new(Spree::Core::Engine.root + 'spec/fixtures' + 'text-file.txt'),
+ filename: 'text-file.txt',
+ content_type: 'text/plain'
+ )
+
+ expect(asset).not_to be_valid
+ expect(asset.errors[:attachment]).to be_present
+ end
+
+ it 'reports as playable' do
+ expect(build(:video_asset).playable_video?).to be(true)
+ expect(build(:external_video_asset).playable_video?).to be(true)
+ expect(build(:asset).playable_video?).to be(false)
+ end
+ end
+
+ describe 'external video' do
+ it 'accepts a YouTube link' do
+ expect(build(:external_video_asset)).to be_valid
+ end
+
+ it 'accepts a Vimeo link' do
+ expect(build(:external_video_asset, external_video_url: 'https://vimeo.com/123456789')).to be_valid
+ end
+
+ it 'requires a URL' do
+ asset = build(:external_video_asset, external_video_url: nil)
+
+ expect(asset).not_to be_valid
+ expect(asset.errors[:external_video_url]).to be_present
+ end
+
+ it 'rejects a link Spree cannot embed' do
+ asset = build(:external_video_asset, external_video_url: 'https://example.com/clip.mp4')
+
+ expect(asset).not_to be_valid
+ expect(asset.errors[:external_video_url]).to include('must be a YouTube or Vimeo link')
+ end
+
+ it 'needs no attachment' do
+ asset = build(:external_video_asset)
+
+ expect(asset.attachment).not_to be_attached
+ expect(asset).to be_valid
+ end
+
+ it 'exposes the parsed video' do
+ asset = build(:external_video_asset)
+
+ expect(asset.external_video.provider).to eq('youtube')
+ expect(asset.external_video.embed_url).to eq('https://www.youtube.com/embed/dQw4w9WgXcQ')
+ end
+
+ it 'strips whitespace around the URL' do
+ asset = build(:external_video_asset, external_video_url: ' https://vimeo.com/123456789 ')
+
+ expect(asset.external_video_url).to eq('https://vimeo.com/123456789')
+ end
+
+ it 're-parses after the URL changes' do
+ asset = build(:external_video_asset)
+ expect(asset.external_video.provider).to eq('youtube')
+
+ asset.external_video_url = 'https://vimeo.com/123456789'
+ expect(asset.external_video.provider).to eq('vimeo')
+ end
+
+ it 'attaches a poster only once the record saves' do
+ poster = ActiveStorage::Blob.create_and_upload!(
+ io: File.open(Spree::Core::Engine.root + 'spec/fixtures' + 'thinking-cat.jpg'),
+ filename: 'poster.jpg', content_type: 'image/jpeg'
+ )
+ asset = build(:external_video_asset, external_video_url: 'https://example.com/nope')
+ asset.poster_signed_id = poster.signed_id
+
+ # The record is invalid, so nothing should reach storage.
+ expect(asset.save).to be(false)
+ expect(asset.poster).not_to be_attached
+ end
+
+ it 'removes the poster when the signed id is blank' do
+ poster = ActiveStorage::Blob.create_and_upload!(
+ io: File.open(Spree::Core::Engine.root + 'spec/fixtures' + 'thinking-cat.jpg'),
+ filename: 'poster.jpg', content_type: 'image/jpeg'
+ )
+ asset = create(:external_video_asset)
+ asset.update!(poster_signed_id: poster.signed_id)
+ expect(asset.reload.poster).to be_attached
+
+ asset.update!(poster_signed_id: '')
+
+ expect(asset.reload.poster).not_to be_attached
+ end
+
+ it 'rejects a signed id it cannot resolve' do
+ asset = build(:external_video_asset, poster_signed_id: 'not-a-real-signed-id')
+
+ # A tampered id raises inside attach, which would be a 500 after the row
+ # was already written — it has to fail as a validation instead.
+ expect(asset).not_to be_valid
+ expect(asset.errors[:poster]).to be_present
+ end
+
+ it 'rejects a poster that is not a web image' do
+ asset = build(:external_video_asset)
+ asset.poster.attach(
+ io: File.open(Spree::Core::Engine.root + 'spec/fixtures' + 'text-file.txt'),
+ filename: 'notes.txt', content_type: 'text/plain'
+ )
+
+ expect(asset).not_to be_valid
+ expect(asset.errors[:poster]).to be_present
+ end
+
+ it 'falls back to the provider thumbnail when no poster was uploaded' do
+ video = build(:external_video_asset)
+
+ expect(video.still_image).to be_nil
+ expect(video.provider_still_url).to eq('https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg')
+ end
end
describe 'counter caches with product viewable' do
@@ -188,7 +332,7 @@ describe Spree::Asset, type: :model do
context 'external URL' do
before do
- create(:custom_field_definition, namespace: 'external', key: 'url', resource_type: 'Spree::Asset')
+ create(:custom_field_definition, namespace: 'external', key: 'url', resource_type: 'Spree::Media')
end
describe '.with_external_url' do
diff --git a/spree/core/spec/models/spree/product_spec.rb b/spree/core/spec/models/spree/product_spec.rb
index 342469049e..47da7bc844 100644
--- a/spree/core/spec/models/spree/product_spec.rb
+++ b/spree/core/spec/models/spree/product_spec.rb
@@ -640,9 +640,9 @@ describe Spree::Product, type: :model do
before do
images = [
- Spree::Image.new(params),
- Spree::Image.new(params.merge(alt: 'position 1', position: 1)),
- Spree::Image.new(params.merge(viewable_type: 'ThirdParty::Extension', alt: 'position 1', position: 2))
+ Spree::Media.new(params),
+ Spree::Media.new(params.merge(alt: 'position 1', position: 1)),
+ Spree::Media.new(params.merge(viewable_type: 'ThirdParty::Extension', alt: 'position 1', position: 2))
]
images.each_with_index do |image, index|
image.attachment.attach(io: file, filename: "thinking-cat-#{index + 1}.jpg", content_type: 'image/jpeg')
@@ -2108,12 +2108,12 @@ describe Spree::Product, type: :model do
image = product.media.find_by(alt: 'A cat')
expect(image).to be_present
expect(image.attachment).to be_attached
- expect(image.type).to eq('Spree::Image')
+ expect(image.media_type).to eq('image')
expect(image.position).to eq(1)
end
it 'patches an existing media item by id (alt, position)' do
- existing = product.media.build(alt: 'Old', position: 1, type: 'Spree::Image')
+ existing = product.media.build(alt: 'Old', position: 1)
existing.attachment.attach(io: File.open(fixture_path), filename: 'cat.jpg', content_type: 'image/jpeg')
existing.save!
@@ -2124,7 +2124,7 @@ describe Spree::Product, type: :model do
end
it 'patches variant_ids on an existing media item' do
- existing = product.media.build(alt: 'Photo', position: 1, type: 'Spree::Image')
+ existing = product.media.build(alt: 'Photo', position: 1)
existing.attachment.attach(io: File.open(fixture_path), filename: 'cat.jpg', content_type: 'image/jpeg')
existing.save!
@@ -2136,10 +2136,58 @@ describe Spree::Product, type: :model do
expect(existing.reload.variants).to include(variant)
end
- it 'silently skips an unknown media type' do
+ it 'rejects an unknown media type' do
expect {
- product.media = [{ signed_id: blob.signed_id, type: 'NotAClass' }]
- }.not_to change(product.media, :count)
+ product.media = [{ signed_id: blob.signed_id, media_type: 'audio' }]
+ }.to raise_error(ActiveRecord::RecordInvalid)
+ end
+
+ it 'adds an external video without a file' do
+ expect {
+ product.media = [
+ { media_type: 'external_video', external_video_url: 'https://vimeo.com/123456789', position: 1 }
+ ]
+ }.to change(product.media, :count).by(1)
+
+ video = product.media.find_by(media_type: 'external_video')
+ expect(video.attachment).not_to be_attached
+ expect(video.external_video.provider).to eq('vimeo')
+ end
+
+ it 'rejects an external video Spree cannot embed' do
+ expect {
+ product.media = [
+ { media_type: 'external_video', external_video_url: 'https://example.com/clip.mp4' }
+ ]
+ }.to raise_error(ActiveRecord::RecordInvalid)
+ end
+
+ it 'attaches a poster to a video through the inline path' do
+ poster = ActiveStorage::Blob.create_and_upload!(
+ io: File.open(fixture_path), filename: 'poster.jpg', content_type: 'image/jpeg'
+ )
+
+ product.media = [
+ {
+ media_type: 'external_video',
+ external_video_url: 'https://vimeo.com/123456789',
+ poster_signed_id: poster.signed_id
+ }
+ ]
+
+ video = product.media.find_by(media_type: 'external_video')
+ expect(video.poster).to be_attached
+ expect(video.still_image).to eq(video.poster)
+ end
+
+ it 'patches the focal point on an existing media item' do
+ existing = product.media.build(alt: 'Photo', position: 1)
+ existing.attachment.attach(io: File.open(fixture_path), filename: 'cat.jpg', content_type: 'image/jpeg')
+ existing.save!
+
+ product.media = [{ id: existing.prefixed_id, focal_point_x: 0.25, focal_point_y: 0.75 }]
+
+ expect(existing.reload.focal_point).to eq({ x: 0.25, y: 0.75 })
end
it 'silently skips entries with neither id nor signed_id' do
@@ -2155,7 +2203,7 @@ describe Spree::Product, type: :model do
end
it 'preserves an existing media item omitted from the array (no implicit delete)' do
- existing = product.media.build(alt: 'Keep me', position: 1, type: 'Spree::Image')
+ existing = product.media.build(alt: 'Keep me', position: 1, type: 'Spree::Media')
existing.attachment.attach(io: File.open(fixture_path), filename: 'cat.jpg', content_type: 'image/jpeg')
existing.save!
@@ -2177,7 +2225,7 @@ describe Spree::Product, type: :model do
expect {
new_product.save!
- }.to change(Spree::Asset, :count).by(1)
+ }.to change(Spree::Media, :count).by(1)
image = new_product.media.find_by(alt: 'Pending')
expect(image).to be_present
diff --git a/spree/core/spec/models/spree/variant_media_spec.rb b/spree/core/spec/models/spree/variant_media_spec.rb
index 9df861f8a6..82b0b111f0 100644
--- a/spree/core/spec/models/spree/variant_media_spec.rb
+++ b/spree/core/spec/models/spree/variant_media_spec.rb
@@ -68,7 +68,7 @@ RSpec.describe Spree::VariantMedia, type: :model do
end
-RSpec.describe Spree::Asset, type: :model do
+RSpec.describe Spree::Media, type: :model do
describe '#variant_ids=' do
let(:product) { create(:product) }
let(:product_asset) { create(:image, viewable: product) }
diff --git a/spree/core/spec/models/spree/variant_spec.rb b/spree/core/spec/models/spree/variant_spec.rb
index 3537873348..90745066f8 100644
--- a/spree/core/spec/models/spree/variant_spec.rb
+++ b/spree/core/spec/models/spree/variant_spec.rb
@@ -1363,11 +1363,25 @@ describe Spree::Variant, type: :model do
describe '#secondary_image' do
let(:variant) { create(:variant) }
- let!(:image1) { create(:image, position: 1, viewable: variant) }
- let!(:image2) { create(:image, position: 2, viewable: variant) }
- it 'returns the second image' do
- expect(variant.secondary_image).to eq(image2)
+ context 'with images pinned to the variant' do
+ let!(:image1) { create(:image, position: 1, viewable: variant) }
+ let!(:image2) { create(:image, position: 2, viewable: variant) }
+
+ it 'returns the second image' do
+ expect(variant.secondary_image).to eq(image2)
+ end
+ end
+
+ context 'with product-level media linked to the variant' do
+ let!(:image1) { create(:image, position: 1, viewable: variant.product) }
+ let!(:image2) { create(:image, position: 2, viewable: variant.product) }
+
+ before { variant.associated_media = [image1, image2] }
+
+ it 'reads the gallery rather than variant-pinned images only' do
+ expect(variant.reload.secondary_image).to eq(image2)
+ end
end
end
diff --git a/spree/core/spec/services/spree/products/duplicator_spec.rb b/spree/core/spec/services/spree/products/duplicator_spec.rb
index 2d786c7b0f..202ffbcd54 100644
--- a/spree/core/spec/services/spree/products/duplicator_spec.rb
+++ b/spree/core/spec/services/spree/products/duplicator_spec.rb
@@ -19,7 +19,7 @@ RSpec.describe Spree::Products::Duplicator do
before do
file = File.open(filepath)
- new_image = Spree::Image.new(default_variant_image_params)
+ new_image = Spree::Media.new(default_variant_image_params)
new_image.attachment.attach(io: file, filename: File.basename(file))
new_image.save!
@@ -41,14 +41,14 @@ RSpec.describe Spree::Products::Duplicator do
describe 'image duplication' do
it 'clones images by default' do
- expect { duplicate }.to change { Spree::Image.count }.by(1)
+ expect { duplicate }.to change { Spree::Media.count }.by(1)
end
context 'when excluding images from cloning' do
subject(:duplicate) { described_class.call(product: product, include_images: false) }
it 'doesn\'t clone images' do
- expect { duplicate }.not_to change(Spree::Image, :count)
+ expect { duplicate }.not_to change(Spree::Media, :count)
end
end
end
@@ -168,25 +168,25 @@ RSpec.describe Spree::Products::Duplicator do
before do
file = File.open(filepath)
- variant1_image = Spree::Image.new(variant1_image_params)
+ variant1_image = Spree::Media.new(variant1_image_params)
variant1_image.attachment.attach(io: file, filename: File.basename(file))
variant1_image.save!
file = File.open(filepath)
- variant2_image = Spree::Image.new(variant2_image_params)
+ variant2_image = Spree::Media.new(variant2_image_params)
variant2_image.attachment.attach(io: file, filename: File.basename(file))
variant2_image.save!
end
it 'clones images by default' do
- expect { duplicate }.to change(Spree::Image, :count).by(3)
+ expect { duplicate }.to change(Spree::Media, :count).by(3)
end
context 'when excluding images from cloning' do
subject(:duplicate) { described_class.call(product: product, include_images: false) }
it 'doesn\'t clone images' do
- expect { duplicate }.not_to change(Spree::Image, :count)
+ expect { duplicate }.not_to change(Spree::Media, :count)
end
end
end