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.

Charge sellers commission on what they sell

Damian Legawiece5f5556f7498
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index dd493c84ae..9553457899 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -92,16 +92,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjI4M2MxNzBlLWU5MmMtNDFlNi05MDQ2LWM1ZmJhZjZkNzMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTA0MDMzfQ.w79yai78pvtJb0KLskIar-BDbGWvUQIYjSvLi7-98G8
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImRmZTNkNTk0LWM4ZTYtNDhiNi04ZTNlLWI1NTQ0YTc0OGNkYyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTA4NzE5fQ._xD9WamtkwMj4NRWgBlqI8S6wrM_mB1fwSXQpEVLnCI
user:
id: adm_UkLWZg9DAJ
- first_name: Mignon
- last_name: Reynolds
- full_name: Mignon Reynolds
+ first_name: Indira
+ last_name: Gerlach
+ full_name: Indira Gerlach
selected_locale:
- created_at: '2026-08-16T18:08:53.378Z'
- updated_at: '2026-08-16T18:08:53.378Z'
+ created_at: '2026-08-16T19:26:59.520Z'
+ updated_at: '2026-08-16T19:26:59.520Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -204,16 +204,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjdkZTEwNmQzLTYxOTItNDEzNC04MjExLTgxNDIzMTUwMzU5NyIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTA0MDMzfQ.9F4EmygBof8EEw_egB0CaGoVVn9X02JGQbCUn3pZdAA
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjIzNmY5MTAwLTBiYmYtNDg0Mi05ZTRkLTJmMWRjZGJmYWY0MiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTA4NzE5fQ.e8m74vCczB8lBKw_Ao2E9p4hiPKx_GCDvKpd8LPwcwQ
user:
id: adm_UkLWZg9DAJ
- first_name: Lesley
- last_name: Hand
- full_name: Lesley Hand
+ first_name: Renate
+ last_name: Hoppe
+ full_name: Renate Hoppe
selected_locale:
- created_at: '2026-08-16T18:08:53.445Z'
- updated_at: '2026-08-16T18:08:53.445Z'
+ created_at: '2026-08-16T19:26:59.584Z'
+ updated_at: '2026-08-16T19:26:59.584Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -315,13 +315,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Jacqueline
- last_name: Koepp
- full_name: Jacqueline Koepp
+ first_name: Kristy
+ last_name: Dach
+ full_name: Kristy Dach
selected_locale:
- created_at: '2026-08-16T18:08:59.810Z'
- updated_at: '2026-08-16T18:08:59.810Z'
+ created_at: '2026-08-16T19:27:06.513Z'
+ updated_at: '2026-08-16T19:27:06.513Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -374,6 +374,8 @@ paths:
- write_staff
- read_vendors
- write_vendors
+ - read_commissions
+ - write_commissions
- read_vendor_profile
- write_vendor_profile
- read_dashboard
@@ -436,13 +438,13 @@ paths:
example:
user:
id: adm_UkLWZg9DAJ
- first_name: Bonita
- last_name: Schuster
- full_name: Bonita Schuster
+ first_name: Felipe
+ last_name: Hodkiewicz
+ full_name: Felipe Hodkiewicz
selected_locale: de
- created_at: '2026-08-16T18:08:59.853Z'
- updated_at: '2026-08-16T18:08:59.868Z'
+ created_at: '2026-08-16T19:27:06.552Z'
+ updated_at: '2026-08-16T19:27:06.563Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -495,6 +497,8 @@ paths:
- write_staff
- read_vendors
- write_vendors
+ - read_commissions
+ - write_commissions
- read_vendor_profile
- write_vendor_profile
- read_dashboard
@@ -634,16 +638,16 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjU3ZTFmOWI5LTI4YjAtNGI0Mi04NjFjLWRjZGRmZDVjZWZiOSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTA3MzQ5fQ.Cu5Cc4mTkdTK2tvzFniZlLEnupSkD5BiO94ePm-9g2k
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjY0NjIxZWQ3LWNhNTQtNGYxMy05NWMyLWRmYzA0ZjE4M2UxMSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTEyMDM0fQ.QLAshuY-oWRtYw2G7dsdNPR-XeV3nuUsYKzwGrGRYkU
user:
id: adm_UkLWZg9DAJ
- first_name: Maryetta
- last_name: Hammes
- full_name: Maryetta Hammes
+ first_name: Fausto
+ last_name: O'Keefe
+ full_name: Fausto O'Keefe
selected_locale:
- created_at: '2026-08-16T18:09:09.154Z'
- updated_at: '2026-08-16T18:09:09.170Z'
+ created_at: '2026-08-16T19:27:14.511Z'
+ updated_at: '2026-08-16T19:27:14.527Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -712,7 +716,7 @@ paths:
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjFkZjA3Y2ZhLWYzNzQtNDkxMS04NTI1LWU1NTlmYTJkYjJjYiIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTA0MDU1fQ.cj1KEDUEV1LRRIjBjGLKd-diOZhF8MYCqFt0lYArRAw
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImZhNzE4NGMzLWViOGMtNDJmNy1hMmNkLTI4Y2Y1Yzc3NTRiNSIsImlzcyI6InNwcmVlIiwiYXVkIjoiYWRtaW5fYXBpIiwiZXhwIjoxNzg2OTA4NzQwfQ.qhFnmgrXsnApAEbeSos1iUQsXyym5NDzD9jWJcfUpnU
user:
id: adm_UkLWZg9DAJ
@@ -720,8 +724,8 @@ paths:
last_name: Owner
full_name: Olivia Owner
selected_locale:
- created_at: '2026-08-16T18:09:15.333Z'
- updated_at: '2026-08-16T18:09:15.333Z'
+ created_at: '2026-08-16T19:27:19.987Z'
+ updated_at: '2026-08-16T19:27:19.987Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -2198,8 +2202,8 @@ paths:
data:
- id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-16T18:08:52.840Z'
- updated_at: '2026-08-16T18:08:52.840Z'
+ created_at: '2026-08-16T19:26:59.067Z'
+ updated_at: '2026-08-16T19:26:59.067Z'
meta:
page: 1
limit: 25
@@ -2283,8 +2287,8 @@ paths:
example:
id: ao_gbHJdmfrXB
origin: https://admin.example.com
- created_at: '2026-08-16T18:08:52.966Z'
- updated_at: '2026-08-16T18:08:52.966Z'
+ created_at: '2026-08-16T19:26:59.131Z'
+ updated_at: '2026-08-16T19:26:59.131Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -2371,8 +2375,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://shop.example.com
- created_at: '2026-08-16T18:08:53.002Z'
- updated_at: '2026-08-16T18:08:53.002Z'
+ created_at: '2026-08-16T19:26:59.168Z'
+ updated_at: '2026-08-16T19:26:59.168Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'404':
@@ -2433,8 +2437,8 @@ paths:
example:
id: ao_UkLWZg9DAJ
origin: https://www.example.com
- created_at: '2026-08-16T18:08:53.053Z'
- updated_at: '2026-08-16T18:08:53.072Z'
+ created_at: '2026-08-16T19:26:59.219Z'
+ updated_at: '2026-08-16T19:26:59.238Z'
schema:
"$ref": "#/components/schemas/AllowedOrigin"
'422':
@@ -2554,34 +2558,34 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-16T18:08:53.144Z'
- updated_at: '2026-08-16T18:08:53.144Z'
+ created_at: '2026-08-16T19:26:59.331Z'
+ updated_at: '2026-08-16T19:26:59.331Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_2eUyU1X5HZ3FMq9AdQRPvhSk
+ plaintext_token: pk_91STbU9ADSXAmQz5Gcv6vFVG
created_by_email:
- id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_nU62UCMov
+ token_prefix: sk_8grWKWnyo
scopes:
- write_all
- created_at: '2026-08-16T18:08:53.146Z'
- updated_at: '2026-08-16T18:08:53.146Z'
+ created_at: '2026-08-16T19:26:59.332Z'
+ updated_at: '2026-08-16T19:26:59.332Z'
revoked_at:
last_used_at:
channel_id:
plaintext_token:
created_by_email:
- id: key_EfhxLZ9ck8
- name: mollitia
+ name: officia
key_type: secret
- token_prefix: sk_KgUs3mmMX
+ token_prefix: sk_ZqSJjDp7m
scopes:
- write_all
- created_at: '2026-08-16T18:08:53.147Z'
- updated_at: '2026-08-16T18:08:53.147Z'
+ created_at: '2026-08-16T19:26:59.333Z'
+ updated_at: '2026-08-16T19:26:59.333Z'
revoked_at:
last_used_at:
channel_id:
@@ -2648,16 +2652,16 @@ paths:
id: key_VqXmZF31wY
name: CI key
key_type: secret
- token_prefix: sk_9PYvhaovs
+ token_prefix: sk_NDs776fvv
scopes:
- read_orders
- created_at: '2026-08-16T18:08:53.228Z'
- updated_at: '2026-08-16T18:08:53.228Z'
+ created_at: '2026-08-16T19:26:59.377Z'
+ updated_at: '2026-08-16T19:26:59.377Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: sk_9PYvhaovsS3wcK6KJYvWrdRD
- created_by_email: [email protected]
+ plaintext_token: sk_NDs776fvvRoEp3LHVMfwosXk
+ created_by_email: [email protected]
'422':
description: validation error
content:
@@ -2746,12 +2750,12 @@ paths:
key_type: publishable
token_prefix:
scopes: []
- created_at: '2026-08-16T18:08:53.267Z'
- updated_at: '2026-08-16T18:08:53.267Z'
+ created_at: '2026-08-16T19:26:59.410Z'
+ updated_at: '2026-08-16T19:26:59.410Z'
revoked_at:
last_used_at:
channel_id:
- plaintext_token: pk_2KyZUYsNoRnT7pSRUPAMWatG
+ plaintext_token: pk_RcAZbAMC6zcve5FwBSzZVyVB
created_by_email:
patch:
summary: Update an API key
@@ -2805,11 +2809,11 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration (renamed)
key_type: secret
- token_prefix: sk_HnVJC6Xu5
+ token_prefix: sk_Mh1SpkXQU
scopes:
- write_all
- created_at: '2026-08-16T18:08:53.293Z'
- updated_at: '2026-08-16T18:08:53.312Z'
+ created_at: '2026-08-16T19:26:59.435Z'
+ updated_at: '2026-08-16T19:26:59.453Z'
revoked_at:
last_used_at:
channel_id:
@@ -2906,13 +2910,13 @@ paths:
application/json:
example:
id: key_EfhxLZ9ck8
- name: maiores
+ name: dignissimos
key_type: secret
- token_prefix: sk_n3cxPUE29
+ token_prefix: sk_Leyv7o9u5
scopes:
- write_all
- created_at: '2026-08-16T18:08:53.341Z'
- updated_at: '2026-08-16T18:08:53.341Z'
+ created_at: '2026-08-16T19:26:59.485Z'
+ updated_at: '2026-08-16T19:26:59.485Z'
revoked_at:
last_used_at:
channel_id:
@@ -2970,12 +2974,12 @@ paths:
id: key_gbHJdmfrXB
name: Backend integration
key_type: secret
- token_prefix: sk_ehZLvhu5t
+ token_prefix: sk_nP5ZDYLDV
scopes:
- write_all
- created_at: '2026-08-16T18:08:53.352Z'
- updated_at: '2026-08-16T18:08:53.368Z'
- revoked_at: '2026-08-16T18:08:53.367Z'
+ created_at: '2026-08-16T19:26:59.495Z'
+ updated_at: '2026-08-16T19:26:59.511Z'
+ revoked_at: '2026-08-16T19:26:59.510Z'
last_used_at:
channel_id:
plaintext_token:
@@ -3052,8 +3056,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-16T18:08:53.548Z'
- updated_at: '2026-08-16T18:08:53.548Z'
+ created_at: '2026-08-16T19:26:59.665Z'
+ updated_at: '2026-08-16T19:26:59.665Z'
meta:
page: 1
limit: 25
@@ -3127,8 +3131,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-16T18:08:53.609Z'
- updated_at: '2026-08-16T18:08:53.617Z'
+ created_at: '2026-08-16T19:26:59.724Z'
+ updated_at: '2026-08-16T19:26:59.732Z'
schema:
"$ref": "#/components/schemas/Category"
'422':
@@ -3234,8 +3238,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-16T18:08:53.664Z'
- updated_at: '2026-08-16T18:08:53.664Z'
+ created_at: '2026-08-16T19:26:59.799Z'
+ updated_at: '2026-08-16T19:26:59.799Z'
schema:
"$ref": "#/components/schemas/Category"
'404':
@@ -3305,8 +3309,8 @@ paths:
lft: 1
rgt: 2
products_count: 0
- created_at: '2026-08-16T18:08:53.726Z'
- updated_at: '2026-08-16T18:08:53.761Z'
+ created_at: '2026-08-16T19:26:59.878Z'
+ updated_at: '2026-08-16T19:26:59.909Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -3421,8 +3425,8 @@ paths:
lft: 2
rgt: 3
products_count: 0
- created_at: '2026-08-16T18:08:53.817Z'
- updated_at: '2026-08-16T18:08:53.841Z'
+ created_at: '2026-08-16T19:26:59.966Z'
+ updated_at: '2026-08-16T19:26:59.993Z'
schema:
"$ref": "#/components/schemas/Category"
requestBody:
@@ -3534,8 +3538,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 11627
- slug: product-11627
+ name: Product 15337
+ slug: product-15337
meta_title:
meta_description:
meta_keywords:
@@ -3547,14 +3551,25 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Facilis dolore ullam eveniet neque impedit explicabo
- sunt. Omnis similique ea quia sequi ullam enim quis vel. Ad perspiciatis
- nam ut deserunt beatae ipsa. Ipsum a tempora dignissimos at cum
- corrupti autem consectetur.
- description_html: Facilis dolore ullam eveniet neque impedit explicabo
- sunt. Omnis similique ea quia sequi ullam enim quis vel. Ad perspiciatis
- nam ut deserunt beatae ipsa. Ipsum a tempora dignissimos at cum
- corrupti autem consectetur.
+ description: Cupiditate enim quasi commodi sapiente numquam distinctio
+ voluptatum debitis. Dolorum rem adipisci sit minima deleniti vero
+ architecto. Tempora optio mollitia nihil asperiores magni. Mollitia
+ repudiandae porro animi accusantium provident. Minima architecto
+ praesentium distinctio ipsum sunt nihil. Quae repellat alias quod
+ fugiat voluptas exercitationem vel dolorum. Vero explicabo laudantium
+ odio neque non harum eaque. Id rerum error quas possimus voluptatem
+ distinctio quaerat exercitationem. Voluptate tenetur necessitatibus
+ voluptates vero ipsum. Cum asperiores ex cumque pariatur vero placeat.
+ Iusto repellendus voluptatum tenetur debitis ullam saepe. Earum
+ cum praesentium dicta reiciendis. Minus facere quia nostrum ratione
+ repellat at quasi. Inventore maxime id quisquam a animi. Alias placeat
+ odio incidunt harum velit. Ipsa nesciunt laudantium eaque perspiciatis
+ quidem tenetur illum. Consequatur sed maiores maxime atque rem.
+ description_html: |-
+ Cupiditate enim quasi commodi sapiente numquam distinctio voluptatum debitis. Dolorum rem adipisci sit minima deleniti vero architecto. Tempora optio mollitia nihil asperiores magni. Mollitia repudiandae porro animi accusantium provident. Minima architecto praesentium distinctio ipsum sunt nihil.
+ Quae repellat alias quod fugiat voluptas exercitationem vel dolorum. Vero explicabo laudantium odio neque non harum eaque. Id rerum error quas possimus voluptatem distinctio quaerat exercitationem.
+ Voluptate tenetur necessitatibus voluptates vero ipsum. Cum asperiores ex cumque pariatur vero placeat. Iusto repellendus voluptatum tenetur debitis ullam saepe. Earum cum praesentium dicta reiciendis.
+ Minus facere quia nostrum ratione repellat at quasi. Inventore maxime id quisquam a animi. Alias placeat odio incidunt harum velit. Ipsa nesciunt laudantium eaque perspiciatis quidem tenetur illum. Consequatur sed maiores maxime atque rem.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -3569,15 +3584,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-16T18:08:53.990Z'
- updated_at: '2026-08-16T18:08:53.990Z'
+ created_at: '2026-08-16T19:27:00.131Z'
+ updated_at: '2026-08-16T19:27:00.131Z'
original_price:
vendor_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-16T18:08:53.961Z'
- updated_at: '2026-08-16T18:08:54.005Z'
+ created_at: '2026-08-16T19:27:00.107Z'
+ updated_at: '2026-08-16T19:27:00.147Z'
delivery_profile_id: fp_UkLWZg9DAJ
vendor_name:
product_type_id:
@@ -3749,8 +3764,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-16T18:08:52.424Z'
- updated_at: '2026-08-16T18:08:52.424Z'
+ created_at: '2026-08-16T19:26:58.732Z'
+ updated_at: '2026-08-16T19:26:58.732Z'
stock_location_ids: []
- id: ch_gbHJdmfrXB
name: Wholesale
@@ -3762,8 +3777,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-16T18:08:54.309Z'
- updated_at: '2026-08-16T18:08:54.309Z'
+ created_at: '2026-08-16T19:27:00.390Z'
+ updated_at: '2026-08-16T19:27:00.390Z'
stock_location_ids: []
meta:
page: 1
@@ -3849,8 +3864,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-16T18:08:54.375Z'
- updated_at: '2026-08-16T18:08:54.375Z'
+ created_at: '2026-08-16T19:27:00.462Z'
+ updated_at: '2026-08-16T19:27:00.462Z'
stock_location_ids: []
requestBody:
content:
@@ -3949,8 +3964,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access:
preferred_guest_checkout:
- created_at: '2026-08-16T18:08:54.388Z'
- updated_at: '2026-08-16T18:08:54.388Z'
+ created_at: '2026-08-16T19:27:00.478Z'
+ updated_at: '2026-08-16T19:27:00.478Z'
stock_location_ids: []
patch:
summary: Update a channel
@@ -4005,8 +4020,8 @@ paths:
preferred_order_routing_strategy:
preferred_storefront_access: login_required
preferred_guest_checkout: false
- created_at: '2026-08-16T18:08:54.420Z'
- updated_at: '2026-08-16T18:08:54.448Z'
+ created_at: '2026-08-16T19:27:00.514Z'
+ updated_at: '2026-08-16T19:27:00.541Z'
stock_location_ids: []
requestBody:
content:
@@ -4289,8 +4304,8 @@ paths:
- id: orule_UkLWZg9DAJ
position: 1
active: true
- created_at: '2026-08-16T18:08:52.429Z'
- updated_at: '2026-08-16T18:08:52.429Z'
+ created_at: '2026-08-16T19:26:58.761Z'
+ updated_at: '2026-08-16T19:26:58.761Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4301,8 +4316,8 @@ paths:
- id: orule_gbHJdmfrXB
position: 2
active: true
- created_at: '2026-08-16T18:08:52.433Z'
- updated_at: '2026-08-16T18:08:52.433Z'
+ created_at: '2026-08-16T19:26:58.765Z'
+ updated_at: '2026-08-16T19:26:58.765Z'
type: minimize_splits
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4313,8 +4328,8 @@ paths:
- id: orule_EfhxLZ9ck8
position: 3
active: true
- created_at: '2026-08-16T18:08:52.436Z'
- updated_at: '2026-08-16T18:08:52.436Z'
+ created_at: '2026-08-16T19:26:58.770Z'
+ updated_at: '2026-08-16T19:26:58.770Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4379,8 +4394,8 @@ paths:
id: orule_VqXmZF31wY
position: 3
active: true
- created_at: '2026-08-16T18:09:01.241Z'
- updated_at: '2026-08-16T18:09:01.241Z'
+ created_at: '2026-08-16T19:27:07.733Z'
+ updated_at: '2026-08-16T19:27:07.733Z'
type: default_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4475,8 +4490,8 @@ paths:
id: orule_UkLWZg9DAJ
position: 2
active: false
- created_at: '2026-08-16T18:08:52.429Z'
- updated_at: '2026-08-16T18:09:01.317Z'
+ created_at: '2026-08-16T19:26:58.761Z'
+ updated_at: '2026-08-16T19:27:07.794Z'
type: preferred_location
channel_id: ch_UkLWZg9DAJ
preferences: {}
@@ -4664,8 +4679,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-16T18:08:56.028Z'
- updated_at: '2026-08-16T18:08:56.028Z'
+ created_at: '2026-08-16T19:27:02.890Z'
+ updated_at: '2026-08-16T19:27:02.890Z'
- id: cfdef_gbHJdmfrXB
namespace: custom
key: order_notes
@@ -4676,8 +4691,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_custom_order_notes
- created_at: '2026-08-16T18:08:56.029Z'
- updated_at: '2026-08-16T18:08:56.029Z'
+ created_at: '2026-08-16T19:27:02.891Z'
+ updated_at: '2026-08-16T19:27:02.891Z'
meta:
page: 1
limit: 25
@@ -4746,8 +4761,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_origin
- created_at: '2026-08-16T18:08:56.071Z'
- updated_at: '2026-08-16T18:08:56.071Z'
+ created_at: '2026-08-16T19:27:02.936Z'
+ updated_at: '2026-08-16T19:27:02.936Z'
requestBody:
content:
application/json:
@@ -4855,8 +4870,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-16T18:08:56.078Z'
- updated_at: '2026-08-16T18:08:56.078Z'
+ created_at: '2026-08-16T19:27:02.944Z'
+ updated_at: '2026-08-16T19:27:02.944Z'
patch:
summary: Update a custom field definition
tags:
@@ -4916,8 +4931,8 @@ paths:
searchable: false
sortable: false
filter_key: cf_specs_fabric
- created_at: '2026-08-16T18:08:56.099Z'
- updated_at: '2026-08-16T18:08:56.114Z'
+ created_at: '2026-08-16T19:27:02.969Z'
+ updated_at: '2026-08-16T19:27:02.988Z'
requestBody:
content:
application/json:
@@ -5063,14 +5078,14 @@ paths:
name: VIPs
description: Top spenders
customers_count: 0
- created_at: '2026-08-16T18:08:56.146Z'
- updated_at: '2026-08-16T18:08:56.146Z'
+ created_at: '2026-08-16T19:27:03.031Z'
+ updated_at: '2026-08-16T19:27:03.031Z'
- id: cg_gbHJdmfrXB
name: Wholesale
description:
customers_count: 0
- created_at: '2026-08-16T18:08:56.147Z'
- updated_at: '2026-08-16T18:08:56.147Z'
+ created_at: '2026-08-16T19:27:03.032Z'
+ updated_at: '2026-08-16T19:27:03.032Z'
meta:
page: 1
limit: 25
@@ -5159,8 +5174,8 @@ paths:
name: Wholesale 2
description: B2B accounts
customers_count: 1
- created_at: '2026-08-16T18:08:56.233Z'
- updated_at: '2026-08-16T18:08:56.233Z'
+ created_at: '2026-08-16T19:27:03.107Z'
+ updated_at: '2026-08-16T19:27:03.107Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -5269,22 +5284,22 @@ paths:
name: VIPs
description: Top spenders
customers_count: 1
- created_at: '2026-08-16T18:08:56.327Z'
- updated_at: '2026-08-16T18:08:56.327Z'
+ created_at: '2026-08-16T19:27:03.175Z'
+ updated_at: '2026-08-16T19:27:03.175Z'
customers:
- id: cust_UkLWZg9DAJ
- first_name: Jason
- last_name: Mosciski
+ first_name: Shirleen
+ last_name: Gottlieb
phone:
accepts_email_marketing: false
- full_name: Jason Mosciski
+ full_name: Shirleen Gottlieb
available_store_credit_total: '0'
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-16T18:08:56.331Z'
- updated_at: '2026-08-16T18:08:56.331Z'
+ created_at: '2026-08-16T19:27:03.178Z'
+ updated_at: '2026-08-16T19:27:03.178Z'
tags: []
internal_note:
internal_note_html:
@@ -5364,8 +5379,8 @@ paths:
name: VIP customers (Q1)
description: Top spenders
customers_count: 0
- created_at: '2026-08-16T18:08:56.393Z'
- updated_at: '2026-08-16T18:08:56.412Z'
+ created_at: '2026-08-16T19:27:03.256Z'
+ updated_at: '2026-08-16T19:27:03.274Z'
schema:
"$ref": "#/components/schemas/CustomerGroup"
'422':
@@ -5508,7 +5523,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 1 Lovely Street
+ address1: 5 Lovely Street
address2: Northwest
postal_code: '10118'
city: New York
@@ -5526,8 +5541,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-08-16T18:08:56.502Z'
- updated_at: '2026-08-16T18:08:56.502Z'
+ created_at: '2026-08-16T19:27:03.347Z'
+ updated_at: '2026-08-16T19:27:03.347Z'
customer_id: cust_UkLWZg9DAJ
meta:
page: 1
@@ -5622,8 +5637,8 @@ paths:
state_name: New York
label: Office
metadata: {}
- created_at: '2026-08-16T18:08:56.571Z'
- updated_at: '2026-08-16T18:08:56.571Z'
+ created_at: '2026-08-16T19:27:03.417Z'
+ updated_at: '2026-08-16T19:27:03.417Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -5721,7 +5736,7 @@ paths:
first_name: John
last_name: Doe
full_name: John Doe
- address1: 3 Lovely Street
+ address1: 7 Lovely Street
address2: Northwest
postal_code: '10118'
city: Manhattan
@@ -5739,8 +5754,8 @@ paths:
state_name: New York
label:
metadata: {}
- created_at: '2026-08-16T18:08:56.589Z'
- updated_at: '2026-08-16T18:08:56.609Z'
+ created_at: '2026-08-16T19:27:03.435Z'
+ updated_at: '2026-08-16T19:27:03.457Z'
customer_id: cust_UkLWZg9DAJ
requestBody:
content:
@@ -5879,8 +5894,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-16T18:08:56.684Z'
- updated_at: '2026-08-16T18:08:56.684Z'
+ created_at: '2026-08-16T19:27:03.536Z'
+ updated_at: '2026-08-16T19:27:03.536Z'
meta:
page: 1
limit: 25
@@ -5970,8 +5985,8 @@ paths:
customer_id: cust_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
metadata: {}
- created_at: '2026-08-16T18:08:56.721Z'
- updated_at: '2026-08-16T18:08:56.721Z'
+ created_at: '2026-08-16T19:27:03.579Z'
+ updated_at: '2026-08-16T19:27:03.579Z'
delete:
summary: Delete a customer credit card
tags:
@@ -6096,8 +6111,8 @@ paths:
currency: USD
memo:
metadata: {}
- created_at: '2026-08-16T18:08:56.806Z'
- updated_at: '2026-08-16T18:08:56.806Z'
+ created_at: '2026-08-16T19:27:03.674Z'
+ updated_at: '2026-08-16T19:27:03.674Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -6176,8 +6191,8 @@ paths:
currency: USD
memo: Goodwill
metadata: {}
- created_at: '2026-08-16T18:08:56.885Z'
- updated_at: '2026-08-16T18:08:56.885Z'
+ created_at: '2026-08-16T19:27:03.742Z'
+ updated_at: '2026-08-16T19:27:03.742Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_gbHJdmfrXB
category_id: sccat_UkLWZg9DAJ
@@ -6272,8 +6287,8 @@ paths:
currency: USD
memo: Updated
metadata: {}
- created_at: '2026-08-16T18:08:56.914Z'
- updated_at: '2026-08-16T18:08:56.941Z'
+ created_at: '2026-08-16T19:27:03.771Z'
+ updated_at: '2026-08-16T19:27:03.793Z'
customer_id: cust_UkLWZg9DAJ
created_by_id: adm_UkLWZg9DAJ
category_id: sccat_UkLWZg9DAJ
@@ -6432,8 +6447,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-16T18:08:56.998Z'
- updated_at: '2026-08-16T18:08:56.998Z'
+ created_at: '2026-08-16T19:27:03.851Z'
+ updated_at: '2026-08-16T19:27:03.851Z'
tags: []
internal_note:
internal_note_html:
@@ -6516,8 +6531,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-16T18:08:57.049Z'
- updated_at: '2026-08-16T18:08:57.049Z'
+ created_at: '2026-08-16T19:27:03.901Z'
+ updated_at: '2026-08-16T19:27:03.901Z'
tags: []
internal_note:
internal_note_html:
@@ -6632,8 +6647,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-16T18:08:57.061Z'
- updated_at: '2026-08-16T18:08:57.061Z'
+ created_at: '2026-08-16T19:27:03.913Z'
+ updated_at: '2026-08-16T19:27:03.913Z'
tags: []
internal_note:
internal_note_html:
@@ -6706,8 +6721,8 @@ paths:
display_available_store_credit_total: "$0.00"
failed_attempts: 0
metadata: {}
- created_at: '2026-08-16T18:08:57.088Z'
- updated_at: '2026-08-16T18:08:57.106Z'
+ created_at: '2026-08-16T19:27:03.950Z'
+ updated_at: '2026-08-16T19:27:03.972Z'
tags: []
internal_note:
internal_note_html:
@@ -7155,8 +7170,8 @@ paths:
- id: exp_UkLWZg9DAJ
number: EF1001
format: csv
- created_at: '2026-08-16T18:08:57.728Z'
- updated_at: '2026-08-16T18:08:57.728Z'
+ created_at: '2026-08-16T19:27:04.658Z'
+ updated_at: '2026-08-16T19:27:04.658Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -7229,8 +7244,8 @@ paths:
id: exp_gbHJdmfrXB
number: EF1002
format: csv
- created_at: '2026-08-16T18:08:57.769Z'
- updated_at: '2026-08-16T18:08:57.769Z'
+ created_at: '2026-08-16T19:27:04.699Z'
+ updated_at: '2026-08-16T19:27:04.699Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -7329,8 +7344,8 @@ paths:
id: exp_UkLWZg9DAJ
number: EF1001
format: csv
- created_at: '2026-08-16T18:08:57.786Z'
- updated_at: '2026-08-16T18:08:57.786Z'
+ created_at: '2026-08-16T19:27:04.718Z'
+ updated_at: '2026-08-16T19:27:04.718Z'
type: products
user_id: adm_UkLWZg9DAJ
done: false
@@ -7546,8 +7561,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:01.451Z'
- updated_at: '2026-08-16T18:09:01.464Z'
+ created_at: '2026-08-16T19:27:07.919Z'
+ updated_at: '2026-08-16T19:27:07.930Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7640,7 +7655,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-16T18:09:01.759Z'
+ fulfilled_at: '2026-08-16T19:27:08.183Z'
tracking_status:
estimated_delivery_at:
delivered_at:
@@ -7652,8 +7667,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-16T18:09:01.738Z'
- updated_at: '2026-08-16T18:09:01.760Z'
+ created_at: '2026-08-16T19:27:08.164Z'
+ updated_at: '2026-08-16T19:27:08.184Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7828,8 +7843,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:02.117Z'
- updated_at: '2026-08-16T18:09:02.129Z'
+ created_at: '2026-08-16T19:27:08.635Z'
+ updated_at: '2026-08-16T19:27:08.647Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -7926,8 +7941,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:02.280Z'
- updated_at: '2026-08-16T18:09:02.362Z'
+ created_at: '2026-08-16T19:27:08.778Z'
+ updated_at: '2026-08-16T19:27:08.847Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8026,7 +8041,7 @@ paths:
display_tax_total: "$0.00"
status: fulfilled
fulfillment_type: shipping
- fulfilled_at: '2026-08-16T18:09:02.533Z'
+ fulfilled_at: '2026-08-16T19:27:09.007Z'
tracking_status:
estimated_delivery_at:
delivered_at:
@@ -8038,8 +8053,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:02.435Z'
- updated_at: '2026-08-16T18:09:02.533Z'
+ created_at: '2026-08-16T19:27:08.923Z'
+ updated_at: '2026-08-16T19:27:09.008Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8142,8 +8157,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:02.638Z'
- updated_at: '2026-08-16T18:09:02.715Z'
+ created_at: '2026-08-16T19:27:09.096Z'
+ updated_at: '2026-08-16T19:27:09.168Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents:
@@ -8242,10 +8257,10 @@ paths:
display_tax_total: "$0.00"
status: delivered
fulfillment_type: shipping
- fulfilled_at: '2026-08-16T18:09:03.062Z'
+ fulfilled_at: '2026-08-16T19:27:09.444Z'
tracking_status:
estimated_delivery_at:
- delivered_at: '2026-08-16T18:09:03.110Z'
+ delivered_at: '2026-08-16T19:27:09.469Z'
items:
- item_id: li_UkLWZg9DAJ
variant_id: variant_UkLWZg9DAJ
@@ -8254,8 +8269,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:02.995Z'
- updated_at: '2026-08-16T18:09:03.112Z'
+ created_at: '2026-08-16T19:27:09.381Z'
+ updated_at: '2026-08-16T19:27:09.470Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8374,8 +8389,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:03.469Z'
- updated_at: '2026-08-16T18:09:03.571Z'
+ created_at: '2026-08-16T19:27:09.686Z'
+ updated_at: '2026-08-16T19:27:09.767Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8472,8 +8487,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '100.0'
- created_at: '2026-08-16T18:09:03.674Z'
- updated_at: '2026-08-16T18:09:03.774Z'
+ created_at: '2026-08-16T19:27:09.848Z'
+ updated_at: '2026-08-16T19:27:09.933Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_UkLWZg9DAJ
documents: []
@@ -8581,8 +8596,8 @@ paths:
tracking_details:
adjustment_total: '0.0'
pre_tax_amount: '0.0'
- created_at: '2026-08-16T18:09:03.964Z'
- updated_at: '2026-08-16T18:09:04.022Z'
+ created_at: '2026-08-16T19:27:10.103Z'
+ updated_at: '2026-08-16T19:27:10.143Z'
order_id: or_UkLWZg9DAJ
stock_location_id: sloc_gbHJdmfrXB
documents: []
@@ -8683,8 +8698,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-16T18:08:57.863Z'
- updated_at: '2026-08-16T18:08:57.863Z'
+ created_at: '2026-08-16T19:27:04.796Z'
+ updated_at: '2026-08-16T19:27:04.796Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -8768,8 +8783,8 @@ paths:
codes_count: 5
currency: USD
prefix: NEWCAMP
- created_at: '2026-08-16T18:08:57.908Z'
- updated_at: '2026-08-16T18:08:57.908Z'
+ created_at: '2026-08-16T19:27:04.844Z'
+ updated_at: '2026-08-16T19:27:04.844Z'
amount: '25.0'
expires_at: '2030-12-31'
created_by_id: adm_UkLWZg9DAJ
@@ -8873,8 +8888,8 @@ paths:
codes_count: 2
currency: USD
prefix: WELCOME
- created_at: '2026-08-16T18:08:57.947Z'
- updated_at: '2026-08-16T18:08:57.947Z'
+ created_at: '2026-08-16T19:27:04.880Z'
+ updated_at: '2026-08-16T19:27:04.880Z'
amount: '50.0'
expires_at:
created_by_id:
@@ -8980,7 +8995,7 @@ paths:
example:
data:
- id: gc_UkLWZg9DAJ
- code: 2234171717224CB8
+ code: D88630E9D16BE3FC
status: active
currency: USD
amount: '50.0'
@@ -8994,12 +9009,12 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-16T18:08:58.031Z'
- updated_at: '2026-08-16T18:08:58.031Z'
+ created_at: '2026-08-16T19:27:04.940Z'
+ updated_at: '2026-08-16T19:27:04.940Z'
customer_id:
created_by_id:
- id: gc_gbHJdmfrXB
- code: 6026379DA4809C78
+ code: 53CC46E5AD2F56A6
status: active
currency: USD
amount: '25.0'
@@ -9013,8 +9028,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-16T18:08:58.032Z'
- updated_at: '2026-08-16T18:08:58.032Z'
+ created_at: '2026-08-16T19:27:04.942Z'
+ updated_at: '2026-08-16T19:27:04.942Z'
customer_id:
created_by_id:
meta:
@@ -9102,7 +9117,7 @@ paths:
application/json:
example:
id: gc_EfhxLZ9ck8
- code: 3C21DBC6B44E1A3A
+ code: A6401F636CF944C3
status: active
currency: USD
amount: '25.0'
@@ -9116,8 +9131,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-16T18:08:58.096Z'
- updated_at: '2026-08-16T18:08:58.096Z'
+ created_at: '2026-08-16T19:27:05.016Z'
+ updated_at: '2026-08-16T19:27:05.016Z'
customer_id:
created_by_id: adm_UkLWZg9DAJ
schema:
@@ -9226,7 +9241,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: EFD0B82842D38FA5
+ code: 14835F2E85350266
status: active
currency: USD
amount: '50.0'
@@ -9240,8 +9255,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-16T18:08:58.134Z'
- updated_at: '2026-08-16T18:08:58.134Z'
+ created_at: '2026-08-16T19:27:05.057Z'
+ updated_at: '2026-08-16T19:27:05.057Z'
customer_id:
created_by_id:
schema:
@@ -9304,7 +9319,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 962C11A226DAC82E
+ code: 17CE3E074691E955
status: active
currency: USD
amount: '75.0'
@@ -9318,8 +9333,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-16T18:08:58.195Z'
- updated_at: '2026-08-16T18:08:58.217Z'
+ created_at: '2026-08-16T19:27:05.111Z'
+ updated_at: '2026-08-16T19:27:05.131Z'
customer_id:
created_by_id:
schema:
@@ -9424,8 +9439,8 @@ paths:
- id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
- created_at: '2026-08-16T18:08:58.304Z'
- updated_at: '2026-08-16T18:08:58.314Z'
+ created_at: '2026-08-16T19:27:05.212Z'
+ updated_at: '2026-08-16T19:27:05.220Z'
type: products
status: pending
owner_type: store
@@ -9612,8 +9627,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
- created_at: '2026-08-16T18:08:58.367Z'
- updated_at: '2026-08-16T18:08:58.424Z'
+ created_at: '2026-08-16T19:27:05.286Z'
+ updated_at: '2026-08-16T19:27:05.334Z'
type: products
status: mapping
owner_type: store
@@ -10071,8 +10086,8 @@ paths:
id: imp_UkLWZg9DAJ
number: IM1001
rows_count: 0
- created_at: '2026-08-16T18:08:58.578Z'
- updated_at: '2026-08-16T18:08:58.586Z'
+ created_at: '2026-08-16T19:27:05.466Z'
+ updated_at: '2026-08-16T19:27:05.480Z'
type: products
status: pending
owner_type: store
@@ -10317,8 +10332,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 0
- created_at: '2026-08-16T18:08:58.738Z'
- updated_at: '2026-08-16T18:08:58.845Z'
+ created_at: '2026-08-16T19:27:05.597Z'
+ updated_at: '2026-08-16T19:27:05.668Z'
type: products
status: completed_mapping
owner_type: store
@@ -10674,8 +10689,8 @@ paths:
id: imp_gbHJdmfrXB
number: IM1002
rows_count: 1
- created_at: '2026-08-16T18:08:58.889Z'
- updated_at: '2026-08-16T18:08:58.917Z'
+ created_at: '2026-08-16T19:27:05.709Z'
+ updated_at: '2026-08-16T19:27:05.731Z'
type: products
status: processing
owner_type: store
@@ -10857,8 +10872,8 @@ paths:
row_number: 2
status: failed
validation_errors: boom
- created_at: '2026-08-16T18:08:58.958Z'
- updated_at: '2026-08-16T18:08:58.958Z'
+ created_at: '2026-08-16T19:27:05.770Z'
+ updated_at: '2026-08-16T19:27:05.770Z'
import_id: imp_UkLWZg9DAJ
item_type:
item_id:
@@ -10961,8 +10976,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
- id: mkt_gbHJdmfrXB
name: EU
currency: USD
@@ -10974,8 +10989,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:59.414Z'
- updated_at: '2026-08-16T18:08:59.414Z'
+ created_at: '2026-08-16T19:27:06.166Z'
+ updated_at: '2026-08-16T19:27:06.166Z'
meta:
page: 1
limit: 25
@@ -11069,8 +11084,8 @@ paths:
- en
- fr
tax_provider:
- created_at: '2026-08-16T18:08:59.489Z'
- updated_at: '2026-08-16T18:08:59.489Z'
+ created_at: '2026-08-16T19:27:06.225Z'
+ updated_at: '2026-08-16T19:27:06.225Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -11207,8 +11222,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:59.556Z'
- updated_at: '2026-08-16T18:08:59.556Z'
+ created_at: '2026-08-16T19:27:06.280Z'
+ updated_at: '2026-08-16T19:27:06.280Z'
schema:
"$ref": "#/components/schemas/Market"
'404':
@@ -11288,8 +11303,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:59.628Z'
- updated_at: '2026-08-16T18:08:59.648Z'
+ created_at: '2026-08-16T19:27:06.355Z'
+ updated_at: '2026-08-16T19:27:06.376Z'
schema:
"$ref": "#/components/schemas/Market"
'422':
@@ -11469,8 +11484,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-16T18:08:59.888Z'
- updated_at: '2026-08-16T18:08:59.888Z'
+ created_at: '2026-08-16T19:27:06.580Z'
+ updated_at: '2026-08-16T19:27:06.580Z'
meta:
page: 1
limit: 25
@@ -11564,8 +11579,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-16T18:08:59.961Z'
- updated_at: '2026-08-16T18:08:59.961Z'
+ created_at: '2026-08-16T19:27:06.640Z'
+ updated_at: '2026-08-16T19:27:06.640Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -11689,8 +11704,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-16T18:08:59.999Z'
- updated_at: '2026-08-16T18:08:59.999Z'
+ created_at: '2026-08-16T19:27:06.691Z'
+ updated_at: '2026-08-16T19:27:06.691Z'
schema:
"$ref": "#/components/schemas/OptionType"
'404':
@@ -11763,8 +11778,8 @@ paths:
kind: dropdown
metadata: {}
filterable: true
- created_at: '2026-08-16T18:09:00.054Z'
- updated_at: '2026-08-16T18:09:00.075Z'
+ created_at: '2026-08-16T19:27:06.741Z'
+ updated_at: '2026-08-16T19:27:06.758Z'
schema:
"$ref": "#/components/schemas/OptionType"
'422':
@@ -11928,8 +11943,8 @@ paths:
country_code:
state_code:
data: {}
- created_at: '2026-08-16T18:09:00.364Z'
- updated_at: '2026-08-16T18:09:00.364Z'
+ created_at: '2026-08-16T19:27:06.973Z'
+ updated_at: '2026-08-16T19:27:06.973Z'
meta:
page: 1
limit: 25
@@ -12003,8 +12018,8 @@ paths:
amount: "-2.0"
display_amount: "-$2.00"
metadata: {}
- created_at: '2026-08-16T18:09:00.532Z'
- updated_at: '2026-08-16T18:09:00.532Z'
+ created_at: '2026-08-16T19:27:07.118Z'
+ updated_at: '2026-08-16T19:27:07.118Z'
meta:
page: 1
limit: 25
@@ -12084,8 +12099,8 @@ paths:
amount: "-3.0"
display_amount: "-$3.00"
metadata: {}
- created_at: '2026-08-16T18:09:00.697Z'
- updated_at: '2026-08-16T18:09:00.697Z'
+ created_at: '2026-08-16T19:27:07.271Z'
+ updated_at: '2026-08-16T19:27:07.271Z'
'422':
description: invalid discount
content:
@@ -12182,8 +12197,8 @@ paths:
amount: '4.0'
display_amount: "$4.00"
metadata: {}
- created_at: '2026-08-16T18:09:01.036Z'
- updated_at: '2026-08-16T18:09:01.036Z'
+ created_at: '2026-08-16T19:27:07.529Z'
+ updated_at: '2026-08-16T19:27:07.529Z'
'422':
description: invalid fee
content:
@@ -12281,7 +12296,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 511CAD4745FAC7EE
+ code: 4F55D6D8EC0A7CE1
status: active
currency: USD
amount: '10.0'
@@ -12295,8 +12310,8 @@ paths:
redeemed_at:
expired: false
active: true
- created_at: '2026-08-16T18:09:04.148Z'
- updated_at: '2026-08-16T18:09:04.188Z'
+ created_at: '2026-08-16T19:27:10.254Z'
+ updated_at: '2026-08-16T19:27:10.293Z'
customer_id:
created_by_id:
requestBody:
@@ -12438,8 +12453,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 318462
- slug: product-318462
+ name: Product 35892
+ slug: product-35892
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -12471,12 +12486,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:04.438Z'
- updated_at: '2026-08-16T18:09:04.438Z'
+ created_at: '2026-08-16T19:27:10.503Z'
+ updated_at: '2026-08-16T19:27:10.503Z'
digital_links: []
metadata: {}
- created_at: '2026-08-16T18:09:04.471Z'
- updated_at: '2026-08-16T18:09:04.471Z'
+ created_at: '2026-08-16T19:27:10.535Z'
+ updated_at: '2026-08-16T19:27:10.535Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -12549,8 +12564,8 @@ paths:
preorder_ships_at:
quantity: 3
currency: USD
- name: Product 338246
- slug: product-338246
+ name: Product 37359
+ slug: product-37359
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -12582,12 +12597,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:04.673Z'
- updated_at: '2026-08-16T18:09:04.673Z'
+ created_at: '2026-08-16T19:27:10.695Z'
+ updated_at: '2026-08-16T19:27:10.695Z'
digital_links: []
metadata: {}
- created_at: '2026-08-16T18:09:04.706Z'
- updated_at: '2026-08-16T18:09:04.706Z'
+ created_at: '2026-08-16T19:27:10.728Z'
+ updated_at: '2026-08-16T19:27:10.728Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -12682,8 +12697,8 @@ paths:
preorder_ships_at:
quantity: 2
currency: USD
- name: Product 34623
- slug: product-34623
+ name: Product 387511
+ slug: product-387511
options_text: 'Size: S'
price: '10.0'
display_price: "$10.00"
@@ -12715,12 +12730,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:04.826Z'
- updated_at: '2026-08-16T18:09:04.826Z'
+ created_at: '2026-08-16T19:27:10.821Z'
+ updated_at: '2026-08-16T19:27:10.821Z'
digital_links: []
metadata: {}
- created_at: '2026-08-16T18:09:04.860Z'
- updated_at: '2026-08-16T18:09:04.860Z'
+ created_at: '2026-08-16T19:27:10.850Z'
+ updated_at: '2026-08-16T19:27:10.850Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -12788,8 +12803,8 @@ paths:
preorder_ships_at:
quantity: 5
currency: USD
- name: Product 357254
- slug: product-357254
+ name: Product 394595
+ slug: product-394595
options_text: 'Size: S'
price: '19.99'
display_price: "$19.99"
@@ -12821,12 +12836,12 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:04.946Z'
- updated_at: '2026-08-16T18:09:04.946Z'
+ created_at: '2026-08-16T19:27:10.925Z'
+ updated_at: '2026-08-16T19:27:10.925Z'
digital_links: []
metadata: {}
- created_at: '2026-08-16T18:09:04.981Z'
- updated_at: '2026-08-16T18:09:05.026Z'
+ created_at: '2026-08-16T19:27:10.953Z'
+ updated_at: '2026-08-16T19:27:10.984Z'
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -12948,7 +12963,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -12995,8 +13010,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13007,8 +13022,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-16T18:09:06.931Z'
- updated_at: '2026-08-16T18:09:07.000Z'
+ created_at: '2026-08-16T19:27:12.593Z'
+ updated_at: '2026-08-16T19:27:12.655Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -13190,7 +13205,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -13237,8 +13252,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13249,8 +13264,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-16T18:09:07.260Z'
- updated_at: '2026-08-16T18:09:07.260Z'
+ created_at: '2026-08-16T19:27:12.879Z'
+ updated_at: '2026-08-16T19:27:12.879Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -13456,8 +13471,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13468,8 +13483,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-16T18:09:07.467Z'
- updated_at: '2026-08-16T18:09:07.472Z'
+ created_at: '2026-08-16T19:27:13.034Z'
+ updated_at: '2026-08-16T19:27:13.040Z'
preferred_stock_location_id: sloc_UkLWZg9DAJ
company_location_id:
company_id:
@@ -13661,7 +13676,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -13708,8 +13723,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13720,8 +13735,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-16T18:09:07.532Z'
- updated_at: '2026-08-16T18:09:07.532Z'
+ created_at: '2026-08-16T19:27:13.071Z'
+ updated_at: '2026-08-16T19:27:13.071Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -13848,8 +13863,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: draft
last_ip_address:
considered_risky: false
@@ -13860,8 +13875,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-16T18:09:07.741Z'
- updated_at: '2026-08-16T18:09:07.782Z'
+ created_at: '2026-08-16T19:27:13.158Z'
+ updated_at: '2026-08-16T19:27:13.189Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14053,7 +14068,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14061,7 +14076,7 @@ paths:
coupon_code:
fulfillment_status: unfulfilled
payment_status: paid
- completed_at: '2026-08-16T18:09:07.989Z'
+ completed_at: '2026-08-16T19:27:13.344Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14100,8 +14115,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14112,8 +14127,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-16T18:09:07.904Z'
- updated_at: '2026-08-16T18:09:08.055Z'
+ created_at: '2026-08-16T19:27:13.284Z'
+ updated_at: '2026-08-16T19:27:13.370Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14205,7 +14220,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14213,7 +14228,7 @@ paths:
coupon_code:
fulfillment_status: canceled
payment_status: none
- completed_at: '2026-08-16T18:09:08.443Z'
+ completed_at: '2026-08-16T19:27:13.661Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14252,8 +14267,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: canceled
last_ip_address:
considered_risky: false
@@ -14262,10 +14277,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-16T18:09:08.483Z'
+ canceled_at: '2026-08-16T19:27:13.714Z'
approved_at:
- created_at: '2026-08-16T18:09:08.374Z'
- updated_at: '2026-08-16T18:09:08.510Z'
+ created_at: '2026-08-16T19:27:13.586Z'
+ updated_at: '2026-08-16T19:27:13.739Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14341,7 +14356,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14349,7 +14364,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-16T18:09:08.666Z'
+ completed_at: '2026-08-16T19:27:14.041Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14388,8 +14403,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14399,9 +14414,9 @@ paths:
display_payment_total: "$0.00"
metadata: {}
canceled_at:
- approved_at: '2026-08-16T18:09:08.705Z'
- created_at: '2026-08-16T18:09:08.583Z'
- updated_at: '2026-08-16T18:09:08.665Z'
+ approved_at: '2026-08-16T19:27:14.115Z'
+ created_at: '2026-08-16T19:27:13.824Z'
+ updated_at: '2026-08-16T19:27:14.040Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14468,7 +14483,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14476,7 +14491,7 @@ paths:
coupon_code:
fulfillment_status: unfulfilled
payment_status: none
- completed_at: '2026-08-16T18:09:08.834Z'
+ completed_at: '2026-08-16T19:27:14.230Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14515,8 +14530,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14525,10 +14540,10 @@ paths:
payment_total: '0.0'
display_payment_total: "$0.00"
metadata: {}
- canceled_at: '2026-08-16T18:09:08.870Z'
+ canceled_at: '2026-08-16T19:27:14.260Z'
approved_at:
- created_at: '2026-08-16T18:09:08.752Z'
- updated_at: '2026-08-16T18:09:08.927Z'
+ created_at: '2026-08-16T19:27:14.161Z'
+ updated_at: '2026-08-16T19:27:14.315Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14595,7 +14610,7 @@ paths:
cart_id:
channel_id: ch_UkLWZg9DAJ
number: R1001
customer_note:
currency: USD
locale: en
@@ -14603,7 +14618,7 @@ paths:
coupon_code:
fulfillment_status:
payment_status:
- completed_at: '2026-08-16T18:09:09.061Z'
+ completed_at: '2026-08-16T19:27:14.430Z'
item_total: '10.0'
display_item_total: "$10.00"
adjustment_total: '0.0'
@@ -14642,8 +14657,8 @@ paths:
supported_locales:
- en
tax_provider:
- created_at: '2026-08-16T18:08:52.419Z'
- updated_at: '2026-08-16T18:08:52.419Z'
+ created_at: '2026-08-16T19:26:58.726Z'
+ updated_at: '2026-08-16T19:26:58.726Z'
status: placed
last_ip_address:
considered_risky: false
@@ -14654,8 +14669,8 @@ paths:
metadata: {}
canceled_at:
approved_at:
- created_at: '2026-08-16T18:09:08.968Z'
- updated_at: '2026-08-16T18:09:09.061Z'
+ created_at: '2026-08-16T19:27:14.358Z'
+ updated_at: '2026-08-16T19:27:14.429Z'
preferred_stock_location_id:
company_location_id:
company_id:
@@ -14738,8 +14753,8 @@ paths:
resolved_capture_method: checkout
storefront_visible: true
position: 1
- created_at: '2026-08-16T18:09:09.213Z'
- updated_at: '2026-08-16T18:09:09.213Z'
+ created_at: '2026-08-16T19:27:14.578Z'
+ updated_at: '2026-08-16T19:27:14.578Z'
preferences: {}
preference_schema: []
meta:
@@ -14801,12 +14816,12 @@ paths:
label: Bogus
description:
preference_schema:
- - key: dummy_secret_key
- type: password
- default:
- key: dummy_key
type: string
default: PUBLICKEY123
+ - key: dummy_secret_key
+ type: password
+ default:
- type: custom_payment_source_method
label: Custom Payment Source Method
description:
@@ -14887,8 +14902,8 @@ paths:
resolved_capture_method: checkout
storefront_visible: true
position: 1
- created_at: '2026-08-16T18:09:09.282Z'
- updated_at: '2026-08-16T18:09:09.282Z'
+ created_at: '2026-08-16T19:27:14.648Z'
+ updated_at: '2026-08-16T19:27:14.648Z'
preferences: {}
preference_schema: []
"/api/v3/admin/orders/{order_id}/payments":
@@ -14959,7 +14974,7 @@ paths:
data:
- id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-9a9fd1334038
+ response_code: BGS-ceabb5813a42
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -14978,14 +14993,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-16T18:09:05.327Z'
- updated_at: '2026-08-16T18:09:05.330Z'
+ created_at: '2026-08-16T19:27:11.235Z'
+ updated_at: '2026-08-16T19:27:11.237Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-16T18:09:05.329Z'
- updated_at: '2026-08-16T18:09:05.329Z'
+ created_at: '2026-08-16T19:27:11.236Z'
+ updated_at: '2026-08-16T19:27:11.236Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
meta:
@@ -15066,8 +15081,8 @@ paths:
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-16T18:09:05.668Z'
- updated_at: '2026-08-16T18:09:05.668Z'
+ created_at: '2026-08-16T19:27:11.569Z'
+ updated_at: '2026-08-16T19:27:11.569Z'
captured_amount: '0.0'
order_id: or_gbHJdmfrXB
requestBody:
@@ -15160,7 +15175,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-671b123ac7c4
+ response_code: BGS-edb493db2c8a
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -15179,14 +15194,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-16T18:09:05.882Z'
- updated_at: '2026-08-16T18:09:05.888Z'
+ created_at: '2026-08-16T19:27:11.748Z'
+ updated_at: '2026-08-16T19:27:11.750Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-16T18:09:05.885Z'
- updated_at: '2026-08-16T18:09:05.885Z'
+ created_at: '2026-08-16T19:27:11.749Z'
+ updated_at: '2026-08-16T19:27:11.749Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/orders/{order_id}/payments/{id}/capture":
@@ -15249,7 +15264,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: BGS-83528eaf2dfa
+ response_code: BGS-44466c9adf62
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -15268,14 +15283,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-16T18:09:06.098Z'
- updated_at: '2026-08-16T18:09:06.101Z'
+ created_at: '2026-08-16T19:27:11.886Z'
+ updated_at: '2026-08-16T19:27:11.889Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-16T18:09:06.100Z'
- updated_at: '2026-08-16T18:09:06.140Z'
+ created_at: '2026-08-16T19:27:11.888Z'
+ updated_at: '2026-08-16T19:27:11.924Z'
captured_amount: '110.0'
order_id: or_UkLWZg9DAJ
'422':
@@ -15347,7 +15362,7 @@ paths:
example:
id: py_UkLWZg9DAJ
payment_method_id: pm_UkLWZg9DAJ
- response_code: void-BGS-4c84f289de24
+ response_code: void-BGS-1499f0ab8dec
number: R1001-P1
amount: '110.0'
display_amount: "$110.00"
@@ -15366,14 +15381,14 @@ paths:
customer_id:
payment_method_id: pm_gbHJdmfrXB
metadata: {}
- created_at: '2026-08-16T18:09:06.481Z'
- updated_at: '2026-08-16T18:09:06.484Z'
+ created_at: '2026-08-16T19:27:12.221Z'
+ updated_at: '2026-08-16T19:27:12.223Z'
metadata: {}
avs_response:
cvv_response_code:
cvv_response_message:
- created_at: '2026-08-16T18:09:06.483Z'
- updated_at: '2026-08-16T18:09:06.522Z'
+ created_at: '2026-08-16T19:27:12.222Z'
+ updated_at: '2026-08-16T19:27:12.250Z'
captured_amount: '0.0'
order_id: or_UkLWZg9DAJ
"/api/v3/admin/price_lists":
@@ -15461,8 +15476,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-16T18:09:09.343Z'
- updated_at: '2026-08-16T18:09:09.343Z'
+ created_at: '2026-08-16T19:27:14.703Z'
+ updated_at: '2026-08-16T19:27:14.703Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -15476,8 +15491,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-16T18:09:09.344Z'
- updated_at: '2026-08-16T18:09:09.344Z'
+ created_at: '2026-08-16T19:27:14.705Z'
+ updated_at: '2026-08-16T19:27:14.705Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -15591,8 +15606,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-16T18:09:09.612Z'
- updated_at: '2026-08-16T18:09:09.614Z'
+ created_at: '2026-08-16T19:27:14.930Z'
+ updated_at: '2026-08-16T19:27:14.933Z'
currently_active: false
products_count: 1
prices_count: 2
@@ -15755,8 +15770,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-16T18:09:09.708Z'
- updated_at: '2026-08-16T18:09:09.708Z'
+ created_at: '2026-08-16T19:27:14.978Z'
+ updated_at: '2026-08-16T19:27:14.978Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -15831,8 +15846,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-16T18:09:10.122Z'
- updated_at: '2026-08-16T18:09:10.142Z'
+ created_at: '2026-08-16T19:27:15.331Z'
+ updated_at: '2026-08-16T19:27:15.350Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -16020,8 +16035,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-16T18:09:10.184Z'
- updated_at: '2026-08-16T18:09:10.205Z'
+ created_at: '2026-08-16T19:27:15.400Z'
+ updated_at: '2026-08-16T19:27:15.421Z'
currently_active: true
products_count: 0
prices_count: 0
@@ -16084,8 +16099,8 @@ paths:
starts_at:
ends_at:
deleted_at:
- created_at: '2026-08-16T18:09:10.218Z'
- updated_at: '2026-08-16T18:09:10.242Z'
+ created_at: '2026-08-16T19:27:15.434Z'
+ updated_at: '2026-08-16T19:27:15.454Z'
currently_active: false
products_count: 0
prices_count: 0
@@ -16199,8 +16214,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:10.302Z'
- updated_at: '2026-08-16T18:09:10.302Z'
+ created_at: '2026-08-16T19:27:15.498Z'
+ updated_at: '2026-08-16T19:27:15.498Z'
- id: price_gbHJdmfrXB
amount: '19.99'
amount_in_cents: 1999
@@ -16211,8 +16226,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-16T18:09:10.340Z'
- updated_at: '2026-08-16T18:09:10.340Z'
+ created_at: '2026-08-16T19:27:15.524Z'
+ updated_at: '2026-08-16T19:27:15.524Z'
- id: price_EfhxLZ9ck8
amount: '5.0'
amount_in_cents: 500
@@ -16223,8 +16238,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-16T18:09:10.346Z'
- updated_at: '2026-08-16T18:09:10.346Z'
+ created_at: '2026-08-16T19:27:15.528Z'
+ updated_at: '2026-08-16T19:27:15.528Z'
meta:
page: 1
limit: 25
@@ -16306,8 +16321,8 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_EfhxLZ9ck8
- created_at: '2026-08-16T18:09:10.509Z'
- updated_at: '2026-08-16T18:09:10.509Z'
+ created_at: '2026-08-16T19:27:15.656Z'
+ updated_at: '2026-08-16T19:27:15.656Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -16394,8 +16409,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-16T18:09:10.593Z'
- updated_at: '2026-08-16T18:09:10.593Z'
+ created_at: '2026-08-16T19:27:15.738Z'
+ updated_at: '2026-08-16T19:27:15.738Z'
schema:
"$ref": "#/components/schemas/Price"
'404':
@@ -16460,8 +16475,8 @@ paths:
display_compare_at_amount:
price_list_id: pl_UkLWZg9DAJ
variant_id: variant_gbHJdmfrXB
- created_at: '2026-08-16T18:09:10.775Z'
- updated_at: '2026-08-16T18:09:10.792Z'
+ created_at: '2026-08-16T19:27:15.915Z'
+ updated_at: '2026-08-16T19:27:15.933Z'
schema:
"$ref": "#/components/schemas/Price"
requestBody:
@@ -16773,8 +16788,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-16T18:09:11.606Z'
- updated_at: '2026-08-16T18:09:11.606Z'
+ created_at: '2026-08-16T19:27:16.750Z'
+ updated_at: '2026-08-16T19:27:16.750Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
meta:
@@ -16844,8 +16859,8 @@ paths:
field_type: long_text
key: custom.description
value: A longer description
- created_at: '2026-08-16T18:09:11.710Z'
- updated_at: '2026-08-16T18:09:11.710Z'
+ created_at: '2026-08-16T19:27:16.834Z'
+ updated_at: '2026-08-16T19:27:16.834Z'
storefront_visible: true
custom_field_definition_id: cfdef_gbHJdmfrXB
'422':
@@ -16944,8 +16959,8 @@ paths:
field_type: short_text
key: custom.title
value: wool
- created_at: '2026-08-16T18:09:11.852Z'
- updated_at: '2026-08-16T18:09:11.852Z'
+ created_at: '2026-08-16T19:27:16.940Z'
+ updated_at: '2026-08-16T19:27:16.940Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
patch:
@@ -17009,8 +17024,8 @@ paths:
field_type: short_text
key: custom.title
value: cotton
- created_at: '2026-08-16T18:09:11.924Z'
- updated_at: '2026-08-16T18:09:11.946Z'
+ created_at: '2026-08-16T19:27:17.009Z'
+ updated_at: '2026-08-16T19:27:17.030Z'
storefront_visible: true
custom_field_definition_id: cfdef_UkLWZg9DAJ
requestBody:
@@ -17129,8 +17144,8 @@ paths:
- key: description
type: html
source: |-
- Exercitationem illo quasi possimus magnam. Magni explicabo adipisci fugiat cumque sint nostrum. Optio officia sunt ipsum fuga corporis cumque alias. Doloremque enim impedit consectetur reiciendis.
- Fugit provident quisquam inventore praesentium aliquam consequatur corrupti. Est asperiores eveniet velit eum cumque ex. Voluptatibus atque nisi eveniet cum at inventore repudiandae reiciendis. Numquam velit ex debitis illo. Doloribus incidunt ipsam tempore alias atque quod.
+ Et eligendi eius voluptate sit nisi nemo dolorum. Illum occaecati dolores aliquam repellendus veniam odit possimus expedita. Occaecati amet aliquam reprehenderit dolorum tempora sapiente.
+ Sapiente facilis explicabo at quibusdam. Reprehenderit temporibus corrupti voluptate sint a mollitia quam. Reprehenderit itaque quaerat minus quisquam incidunt vero. Hic recusandae dolorem in aliquam iure accusamus.
- key: slug
type: string
source: espresso-machine
@@ -17241,8 +17256,8 @@ paths:
example:
data:
- id: prod_UkLWZg9DAJ
- name: Product 763307
- slug: product-763307
+ name: Product 808868
+ slug: product-808868
meta_title:
meta_description:
meta_keywords:
@@ -17254,24 +17269,28 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Minima sapiente deserunt distinctio id amet quaerat.
- Nisi soluta sed iure exercitationem eius culpa aliquam. Sed adipisci
- voluptate aspernatur repudiandae. Voluptate eum facere laudantium
- non assumenda architecto. Tempora illo impedit rem reprehenderit
- molestiae. Doloribus expedita inventore iusto dolorum quasi accusantium
- quo. Autem vero temporibus dolor dignissimos nam nihil. Non ducimus
- numquam earum dignissimos. Ducimus eligendi veniam a impedit beatae
- ipsam consequatur libero. Molestias perferendis mollitia doloribus
- eveniet aspernatur deleniti amet iure. Reprehenderit vero ipsam
- non consequuntur. Ipsa earum tempora dolorum quae. Impedit incidunt
- quia enim ea perferendis earum. Culpa eos cumque ullam voluptates
- quam necessitatibus minima commodi. Voluptatum quo saepe id voluptate.
- Blanditiis quasi repellat earum alias qui in architecto.
+ description: Minima nobis alias non facere quo possimus laborum
+ dolorem. Libero non vitae vero deserunt magni accusamus quo at.
+ Velit officia fugit necessitatibus consequuntur eius neque. Nihil
+ repellendus nesciunt cupiditate illo. Assumenda blanditiis consequatur
+ esse illo a. Vitae ex quam soluta enim cum fugiat ipsam eligendi.
+ Animi perferendis asperiores quidem totam ab dolores repellat
+ magnam. Est harum vel dicta quo quasi laudantium eius labore.
+ Eius voluptatibus dicta aliquam culpa tempora quo deleniti sunt.
+ Provident eius nobis soluta excepturi. Alias temporibus eligendi
+ iure est assumenda. Veniam incidunt explicabo error reprehenderit
+ veritatis blanditiis maiores temporibus. Velit perferendis quod
+ eius expedita ratione error quos in. Neque rem officiis doloremque
+ cupiditate. Vero aliquam amet distinctio libero in enim quia culpa.
+ Adipisci pariatur facere voluptatibus magni perferendis odio.
+ Laboriosam occaecati exercitationem ut facere. At distinctio iusto
+ possimus est quae molestias earum. Rerum alias inventore sed cupiditate
+ dignissimos deserunt aut saepe.
description_html: |-
- Minima sapiente deserunt distinctio id amet quaerat. Nisi soluta sed iure exercitationem eius culpa aliquam. Sed adipisci voluptate aspernatur repudiandae.
- Voluptate eum facere laudantium non assumenda architecto. Tempora illo impedit rem reprehenderit molestiae. Doloribus expedita inventore iusto dolorum quasi accusantium quo. Autem vero temporibus dolor dignissimos nam nihil. Non ducimus numquam earum dignissimos.
- Ducimus eligendi veniam a impedit beatae ipsam consequatur libero. Molestias perferendis mollitia doloribus eveniet aspernatur deleniti amet iure. Reprehenderit vero ipsam non consequuntur. Ipsa earum tempora dolorum quae.
- Impedit incidunt quia enim ea perferendis earum. Culpa eos cumque ullam voluptates quam necessitatibus minima commodi. Voluptatum quo saepe id voluptate. Blanditiis quasi repellat earum alias qui in architecto.
+ Minima nobis alias non facere quo possimus laborum dolorem. Libero non vitae vero deserunt magni accusamus quo at. Velit officia fugit necessitatibus consequuntur eius neque. Nihil repellendus nesciunt cupiditate illo. Assumenda blanditiis consequatur esse illo a.
+ Vitae ex quam soluta enim cum fugiat ipsam eligendi. Animi perferendis asperiores quidem totam ab dolores repellat magnam. Est harum vel dicta quo quasi laudantium eius labore. Eius voluptatibus dicta aliquam culpa tempora quo deleniti sunt.
+ Provident eius nobis soluta excepturi. Alias temporibus eligendi iure est assumenda. Veniam incidunt explicabo error reprehenderit veritatis blanditiis maiores temporibus. Velit perferendis quod eius expedita ratione error quos in. Neque rem officiis doloremque cupiditate.
+ Vero aliquam amet distinctio libero in enim quia culpa. Adipisci pariatur facere voluptatibus magni perferendis odio. Laboriosam occaecati exercitationem ut facere. At distinctio iusto possimus est quae molestias earum. Rerum alias inventore sed cupiditate dignissimos deserunt aut saepe.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -17286,15 +17305,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:12.149Z'
- updated_at: '2026-08-16T18:09:12.149Z'
+ created_at: '2026-08-16T19:27:17.208Z'
+ updated_at: '2026-08-16T19:27:17.208Z'
original_price:
vendor_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-16T18:09:12.135Z'
- updated_at: '2026-08-16T18:09:12.157Z'
+ created_at: '2026-08-16T19:27:17.198Z'
+ updated_at: '2026-08-16T19:27:17.216Z'
delivery_profile_id: fp_UkLWZg9DAJ
vendor_name:
product_type_id:
@@ -17434,8 +17453,8 @@ paths:
status: draft
metadata: {}
deleted_at:
- created_at: '2026-08-16T18:09:12.353Z'
- updated_at: '2026-08-16T18:09:12.359Z'
+ created_at: '2026-08-16T19:27:17.363Z'
+ updated_at: '2026-08-16T19:27:17.369Z'
delivery_profile_id: fp_UkLWZg9DAJ
vendor_name:
product_type_id:
@@ -17643,8 +17662,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 804336
- slug: product-804336
+ name: Product 843464
+ slug: product-843464
meta_title:
meta_description:
meta_keywords:
@@ -17656,31 +17675,16 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Molestias velit voluptatum totam eius laborum rerum amet
- facilis. Ipsum earum necessitatibus possimus itaque veritatis amet
- placeat facere. Ratione tenetur rerum blanditiis fugit magnam eveniet
- et nam. Culpa consequuntur possimus et neque laudantium corporis
- dolore. Minus fugiat ut iure tenetur distinctio quo eius. Laboriosam
- delectus commodi eos dicta atque vel illum. Voluptatum neque est
- vel optio sapiente ea. Aut ipsa iure tenetur dolore provident occaecati
- itaque. Exercitationem explicabo fuga labore quasi atque impedit
- possimus. Earum voluptatibus repellendus ullam aliquam perferendis
- eligendi. Vel nesciunt suscipit rerum laboriosam at aspernatur totam.
- Dolor quis rem reiciendis accusamus saepe similique praesentium
- laboriosam. Mollitia culpa ab fuga doloribus. Ducimus in perspiciatis
- odio consequatur dignissimos repellendus voluptatum. Et non inventore
- impedit quasi vel. Eos autem voluptates tempora iusto exercitationem
- officia quo architecto. Delectus placeat fugiat magni culpa voluptatem
- tempora unde. Accusantium recusandae assumenda facere quod non dolores
- cumque sint. Ratione minus dolorem voluptatum blanditiis ipsa. Provident
- consectetur suscipit inventore sequi aperiam nobis tempora repellendus.
- Magnam in vel magni saepe quis inventore perferendis dicta.
+ description: Voluptatum soluta non repellendus voluptas rerum harum.
+ Adipisci nihil rerum possimus neque quam incidunt enim minima. Atque
+ quasi voluptas animi nobis expedita. Reiciendis voluptas commodi
+ totam illum neque quibusdam est sapiente. Voluptate recusandae quam
+ animi eveniet. Nostrum tenetur occaecati reprehenderit laborum harum
+ vitae numquam odit. Dignissimos necessitatibus quidem suscipit eligendi.
+ Repellendus eaque cum suscipit sint voluptate saepe deleniti.
description_html: |-
- Molestias velit voluptatum totam eius laborum rerum amet facilis. Ipsum earum necessitatibus possimus itaque veritatis amet placeat facere. Ratione tenetur rerum blanditiis fugit magnam eveniet et nam. Culpa consequuntur possimus et neque laudantium corporis dolore. Minus fugiat ut iure tenetur distinctio quo eius.
- Laboriosam delectus commodi eos dicta atque vel illum. Voluptatum neque est vel optio sapiente ea. Aut ipsa iure tenetur dolore provident occaecati itaque. Exercitationem explicabo fuga labore quasi atque impedit possimus.
- Earum voluptatibus repellendus ullam aliquam perferendis eligendi. Vel nesciunt suscipit rerum laboriosam at aspernatur totam. Dolor quis rem reiciendis accusamus saepe similique praesentium laboriosam.
- Mollitia culpa ab fuga doloribus. Ducimus in perspiciatis odio consequatur dignissimos repellendus voluptatum. Et non inventore impedit quasi vel. Eos autem voluptates tempora iusto exercitationem officia quo architecto.
- Delectus placeat fugiat magni culpa voluptatem tempora unde. Accusantium recusandae assumenda facere quod non dolores cumque sint. Ratione minus dolorem voluptatum blanditiis ipsa. Provident consectetur suscipit inventore sequi aperiam nobis tempora repellendus. Magnam in vel magni saepe quis inventore perferendis dicta.
+ Voluptatum soluta non repellendus voluptas rerum harum. Adipisci nihil rerum possimus neque quam incidunt enim minima. Atque quasi voluptas animi nobis expedita. Reiciendis voluptas commodi totam illum neque quibusdam est sapiente. Voluptate recusandae quam animi eveniet.
+ Nostrum tenetur occaecati reprehenderit laborum harum vitae numquam odit. Dignissimos necessitatibus quidem suscipit eligendi. Repellendus eaque cum suscipit sint voluptate saepe deleniti.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -17695,15 +17699,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:12.497Z'
- updated_at: '2026-08-16T18:09:12.497Z'
+ created_at: '2026-08-16T19:27:17.499Z'
+ updated_at: '2026-08-16T19:27:17.499Z'
original_price:
vendor_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-16T18:09:12.481Z'
- updated_at: '2026-08-16T18:09:12.506Z'
+ created_at: '2026-08-16T19:27:17.488Z'
+ updated_at: '2026-08-16T19:27:17.508Z'
delivery_profile_id: fp_UkLWZg9DAJ
vendor_name:
product_type_id:
@@ -17776,7 +17780,7 @@ paths:
example:
id: prod_UkLWZg9DAJ
name: Updated Name
- slug: product-827972
+ slug: product-8669
meta_title:
meta_description:
meta_keywords:
@@ -17788,26 +17792,21 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Harum dolore officiis ducimus temporibus. Expedita occaecati
- ad quas adipisci nostrum deleniti. Earum eveniet sapiente nesciunt
- illo. Quisquam tempora autem ut distinctio. Soluta accusamus quis
- quasi aperiam. Itaque atque fuga nostrum voluptate quos facere sed
- voluptas. Debitis cumque quod ipsam nihil impedit at recusandae
- repellat. Beatae harum pariatur eum mollitia non doloremque. Ab
- quasi deserunt asperiores quis sint magni nobis. Praesentium explicabo
- laborum omnis incidunt deleniti mollitia est. Deleniti accusamus
- nobis quasi quae nisi alias. Atque expedita animi culpa natus inventore
- repudiandae rerum consectetur. Recusandae suscipit animi necessitatibus
- similique id commodi fuga. Nisi hic rerum deleniti error vel. Nisi
- ducimus harum nobis recusandae est. Error unde est asperiores id
- sapiente aliquam. Autem cupiditate qui accusamus beatae reiciendis
- eius minima.
+ description: Esse harum veritatis ab vero voluptatibus tempora molestias.
+ Dolor iure rerum eaque dolores nihil. Maxime harum ad blanditiis
+ commodi laudantium assumenda. Id non necessitatibus placeat eos
+ quidem sapiente ratione tenetur. Molestiae deserunt eaque voluptate
+ alias animi dolore iure. Veritatis quaerat corrupti laudantium dignissimos
+ ullam tempora. Libero delectus ad et a maiores incidunt aut. Esse
+ ut tenetur necessitatibus laudantium. Illo est dignissimos nemo
+ harum ea. Cumque ipsam magni praesentium esse consequatur. Officiis
+ in maiores quod id vero itaque enim doloremque. Commodi libero ratione
+ accusamus beatae est. Eligendi ratione recusandae cum culpa quibusdam
+ porro laboriosam.
description_html: |-
- Harum dolore officiis ducimus temporibus. Expedita occaecati ad quas adipisci nostrum deleniti. Earum eveniet sapiente nesciunt illo. Quisquam tempora autem ut distinctio.
- Soluta accusamus quis quasi aperiam. Itaque atque fuga nostrum voluptate quos facere sed voluptas. Debitis cumque quod ipsam nihil impedit at recusandae repellat. Beatae harum pariatur eum mollitia non doloremque.
- Ab quasi deserunt asperiores quis sint magni nobis. Praesentium explicabo laborum omnis incidunt deleniti mollitia est. Deleniti accusamus nobis quasi quae nisi alias.
- Atque expedita animi culpa natus inventore repudiandae rerum consectetur. Recusandae suscipit animi necessitatibus similique id commodi fuga. Nisi hic rerum deleniti error vel.
- Nisi ducimus harum nobis recusandae est. Error unde est asperiores id sapiente aliquam. Autem cupiditate qui accusamus beatae reiciendis eius minima.
+ Esse harum veritatis ab vero voluptatibus tempora molestias. Dolor iure rerum eaque dolores nihil. Maxime harum ad blanditiis commodi laudantium assumenda. Id non necessitatibus placeat eos quidem sapiente ratione tenetur.
+ Molestiae deserunt eaque voluptate alias animi dolore iure. Veritatis quaerat corrupti laudantium dignissimos ullam tempora. Libero delectus ad et a maiores incidunt aut. Esse ut tenetur necessitatibus laudantium. Illo est dignissimos nemo harum ea.
+ Cumque ipsam magni praesentium esse consequatur. Officiis in maiores quod id vero itaque enim doloremque. Commodi libero ratione accusamus beatae est. Eligendi ratione recusandae cum culpa quibusdam porro laboriosam.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -17822,15 +17821,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:12.666Z'
- updated_at: '2026-08-16T18:09:12.666Z'
+ created_at: '2026-08-16T19:27:17.639Z'
+ updated_at: '2026-08-16T19:27:17.639Z'
original_price:
vendor_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-16T18:09:12.651Z'
- updated_at: '2026-08-16T18:09:12.704Z'
+ created_at: '2026-08-16T19:27:17.628Z'
+ updated_at: '2026-08-16T19:27:17.673Z'
delivery_profile_id: fp_UkLWZg9DAJ
vendor_name:
product_type_id:
@@ -18776,15 +18775,15 @@ paths:
- id: coupon_UkLWZg9DAJ
code: AAA111
state: unused
- created_at: '2026-08-16T18:08:55.993Z'
- updated_at: '2026-08-16T18:08:55.993Z'
+ created_at: '2026-08-16T19:27:02.831Z'
+ updated_at: '2026-08-16T19:27:02.831Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
- id: coupon_gbHJdmfrXB
code: BBB222
state: unused
- created_at: '2026-08-16T18:08:55.994Z'
- updated_at: '2026-08-16T18:08:55.994Z'
+ created_at: '2026-08-16T19:27:02.841Z'
+ updated_at: '2026-08-16T19:27:02.841Z'
promotion_id: promo_UkLWZg9DAJ
order_id:
meta:
@@ -18846,8 +18845,8 @@ paths:
example:
data:
- id: pact_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:14.377Z'
- updated_at: '2026-08-16T18:09:14.377Z'
+ created_at: '2026-08-16T19:27:18.911Z'
+ updated_at: '2026-08-16T19:27:18.911Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -18911,8 +18910,8 @@ paths:
application/json:
example:
id: pact_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:14.433Z'
- updated_at: '2026-08-16T18:09:14.433Z'
+ created_at: '2026-08-16T19:27:18.977Z'
+ updated_at: '2026-08-16T19:27:18.977Z'
type: free_shipping
promotion_id: promo_UkLWZg9DAJ
preferences: {}
@@ -19040,8 +19039,8 @@ paths:
example:
data:
- id: prorule_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:14.500Z'
- updated_at: '2026-08-16T18:09:14.500Z'
+ created_at: '2026-08-16T19:27:19.122Z'
+ updated_at: '2026-08-16T19:27:19.122Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -19111,8 +19110,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:14.548Z'
- updated_at: '2026-08-16T18:09:14.548Z'
+ created_at: '2026-08-16T19:27:19.209Z'
+ updated_at: '2026-08-16T19:27:19.209Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -19203,8 +19202,8 @@ paths:
application/json:
example:
id: prorule_UkLWZg9DAJ
- created_at: '2026-08-16T18:09:14.587Z'
- updated_at: '2026-08-16T18:09:14.606Z'
+ created_at: '2026-08-16T19:27:19.276Z'
+ updated_at: '2026-08-16T19:27:19.300Z'
type: currency
promotion_id: promo_UkLWZg9DAJ
preferences:
@@ -19312,7 +19311,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-16T18:09:14.651Z'
+ starts_at: '2026-08-16T19:27:19.341Z'
expires_at:
usage_limit:
match_policy: all
@@ -19323,8 +19322,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-16T18:09:14.651Z'
- updated_at: '2026-08-16T18:09:14.651Z'
+ created_at: '2026-08-16T19:27:19.341Z'
+ updated_at: '2026-08-16T19:27:19.341Z'
action_ids: []
rule_ids: []
meta:
@@ -19431,7 +19430,7 @@ paths:
name: Black Friday
description:
code: blackfriday-os
- starts_at: '2026-08-16T18:09:14.816Z'
+ starts_at: '2026-08-16T19:27:19.482Z'
expires_at:
usage_limit:
match_policy: all
@@ -19442,8 +19441,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-16T18:09:14.816Z'
- updated_at: '2026-08-16T18:09:14.842Z'
+ created_at: '2026-08-16T19:27:19.483Z'
+ updated_at: '2026-08-16T19:27:19.505Z'
action_ids:
- pact_UkLWZg9DAJ
- pact_gbHJdmfrXB
@@ -19609,7 +19608,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-16T18:09:14.887Z'
+ starts_at: '2026-08-16T19:27:19.544Z'
expires_at:
usage_limit:
match_policy: all
@@ -19620,8 +19619,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-16T18:09:14.887Z'
- updated_at: '2026-08-16T18:09:14.887Z'
+ created_at: '2026-08-16T19:27:19.544Z'
+ updated_at: '2026-08-16T19:27:19.544Z'
action_ids: []
rule_ids: []
patch:
@@ -19718,7 +19717,7 @@ paths:
name: Summer Sale
description:
code: summer
- starts_at: '2026-08-16T18:09:15.006Z'
+ starts_at: '2026-08-16T19:27:19.698Z'
expires_at:
usage_limit:
match_policy: all
@@ -19729,8 +19728,8 @@ paths:
code_prefix:
promotion_category_id:
metadata: {}
- created_at: '2026-08-16T18:09:15.007Z'
- updated_at: '2026-08-16T18:09:15.029Z'
+ created_at: '2026-08-16T19:27:19.698Z'
+ updated_at: '2026-08-16T19:27:19.717Z'
action_ids: []
rule_ids: []
requestBody:
@@ -19992,15 +19991,15 @@ paths:
label: Country
description:
preference_schema:
- - key: country_code
- type: string
- default:
- key: country_codes
type: array
default: []
- key: country_id
type: integer
default:
+ - key: country_code
+ type: string
+ default:
- type: currency
label: Currency
description:
@@ -20027,9 +20026,6 @@ paths:
label: Item total
description:
preference_schema:
- - key: amount_min
- type: decimal
- default: 100.0
- key: operator_min
type: string
default: ">"
@@ -20039,6 +20035,9 @@ paths:
- key: operator_max
type: string
default: "<"
+ - key: amount_min
+ type: decimal
+ default: 100.0
- type: market
label: Market(s)
description:
@@ -20058,12 +20057,12 @@ paths:
label: Option Value(s)
description:
preference_schema:
- - key: match_policy
- type: string
- default: any
- key: eligible_values
type: array
default: []
+ - key: match_policy
+ type: string
+ default: any
- type: product
label: Product(s)
description:
@@ -20202,15 +20201,15 @@ paths:
application/json:
example:
id: re_UkLWZg9DAJ
- transaction_id: BGS-36d61661e24a
+ transaction_id: BGS-b0ef45121eb9
amount: '5.0'
payment_id: py_UkLWZg9DAJ
refund_reason_id: rr_UkLWZg9DAJ
originator_id:
originator_type:
metadata: {}
- created_at: '2026-08-16T18:09:06.894Z'
- updated_at: '2026-08-16T18:09:06.894Z'
+ created_at: '2026-08-16T19:27:12.547Z'
+ updated_at: '2026-08-16T19:27:12.547Z'
requestBody:
content:
application/json:
@@ -20354,8 +20353,8 @@ paths:
data:
- id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-16T18:09:15.719Z'
- updated_at: '2026-08-16T18:09:15.719Z'
+ created_at: '2026-08-16T19:27:20.304Z'
+ updated_at: '2026-08-16T19:27:20.304Z'
non_expiring: false
meta:
page: 1
@@ -20449,8 +20448,8 @@ paths:
example:
id: sccat_UkLWZg9DAJ
name: Goodwill
- created_at: '2026-08-16T18:09:15.784Z'
- updated_at: '2026-08-16T18:09:15.784Z'
+ created_at: '2026-08-16T19:27:20.343Z'
+ updated_at: '2026-08-16T19:27:20.343Z'
non_expiring: false
schema:
"$ref": "#/components/schemas/StoreCreditCategory"
@@ -20544,8 +20543,8 @@ paths:
preferred_order_number_prefix: R
preferred_order_number_suffix: ''
preferred_order_number_sequence_start: 1001
- created_at: '2026-08-16T18:08:52.402Z'
- updated_at: '2026-08-16T18:09:15.852Z'
+ created_at: '2026-08-16T19:26:58.713Z'
+ updated_at: '2026-08-16T19:27:20.399Z'
order_number_sequence_started: false
url: http://www.example.com:3000
api_url: http://www.example.com:3000
@@ -20860,8 +20859,8 @@ paths:
preferred_order_number_prefix: R
preferred_order_number_suffix: ''
preferred_order_number_sequence_start: 1001
- created_at: '2026-08-16T18:08:52.402Z'
- updated_at: '2026-08-16T18:09:15.950Z'
+ created_at: '2026-08-16T19:26:58.713Z'
+ updated_at: '2026-08-16T19:27:20.477Z'
order_number_sequence_started: false
url: http://www.example.com:3000
api_url: http://www.example.com:3000
@@ -21258,12 +21257,12 @@ paths:
example:
data:
- id: tax_UkLWZg9DAJ
- name: TaxRate - 300773
+ name: TaxRate - 955817
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-16T18:09:16.073Z'
- updated_at: '2026-08-16T18:09:16.073Z'
+ created_at: '2026-08-16T19:27:20.597Z'
+ updated_at: '2026-08-16T19:27:20.597Z'
deleted_at:
amount: '0.19'
amount_percentage: 19.0
@@ -21345,8 +21344,8 @@ paths:
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-16T18:09:16.162Z'
- updated_at: '2026-08-16T18:09:16.162Z'
+ created_at: '2026-08-16T19:27:20.664Z'
+ updated_at: '2026-08-16T19:27:20.664Z'
deleted_at:
amount: '0.19'
amount_percentage: 19.0
@@ -21437,12 +21436,12 @@ paths:
application/json:
example:
id: tax_UkLWZg9DAJ
- name: TaxRate - 261838
+ name: TaxRate - 974985
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-16T18:09:16.214Z'
- updated_at: '2026-08-16T18:09:16.214Z'
+ created_at: '2026-08-16T19:27:20.706Z'
+ updated_at: '2026-08-16T19:27:20.706Z'
deleted_at:
amount: '0.19'
amount_percentage: 19.0
@@ -21479,12 +21478,12 @@ paths:
application/json:
example:
id: tax_UkLWZg9DAJ
- name: TaxRate - 481380
+ name: TaxRate - 115304
included_in_price: true
show_rate_in_label: true
metadata: {}
- created_at: '2026-08-16T18:09:16.252Z'
- updated_at: '2026-08-16T18:09:16.275Z'
+ created_at: '2026-08-16T19:27:20.737Z'
+ updated_at: '2026-08-16T19:27:20.754Z'
deleted_at:
amount: '0.07'
amount_percentage: 7.0
@@ -21797,13 +21796,13 @@ paths:
example:
data:
- id: adm_UkLWZg9DAJ
- first_name: Christine
- last_name: Batz
- full_name: Christine Batz
+ first_name: Shaquana
+ last_name: Quigley
+ full_name: Shaquana Quigley
selected_locale:
- created_at: '2026-08-16T18:08:52.551Z'
- updated_at: '2026-08-16T18:08:52.551Z'
+ created_at: '2026-08-16T19:26:58.835Z'
+ updated_at: '2026-08-16T19:26:58.835Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -21869,13 +21868,13 @@ paths:
application/json:
example:
id: adm_UkLWZg9DAJ
- first_name: Alona
- last_name: Davis
- full_name: Alona Davis
+ first_name: Nan
+ last_name: Wiza
+ full_name: Nan Wiza
selected_locale:
- created_at: '2026-08-16T18:08:52.708Z'
- updated_at: '2026-08-16T18:08:52.708Z'
+ created_at: '2026-08-16T19:26:58.977Z'
+ updated_at: '2026-08-16T19:26:58.977Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -21936,13 +21935,13 @@ paths:
application/json:
example:
id: adm_UkLWZg9DAJ
first_name: Renamed
- last_name: Torphy
- full_name: Renamed Torphy
+ last_name: Heidenreich
+ full_name: Renamed Heidenreich
selected_locale:
- created_at: '2026-08-16T18:08:52.745Z'
- updated_at: '2026-08-16T18:08:52.760Z'
+ created_at: '2026-08-16T19:26:59.005Z'
+ updated_at: '2026-08-16T19:26:59.023Z'
avatar_url:
roles:
- id: role_UkLWZg9DAJ
@@ -22058,15 +22057,15 @@ paths:
example:
data:
- id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-08-16T18:08:59.209Z'
- updated_at: '2026-08-16T18:08:59.209Z'
- expires_at: '2026-08-30T18:08:59.206Z'
+ created_at: '2026-08-16T19:27:06.029Z'
+ updated_at: '2026-08-16T19:27:06.029Z'
+ expires_at: '2026-08-30T19:27:06.028Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=sXuRmwQ81fmtoiRqQtMTiNTF"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=25JVFgnWH1zSYZWT6JeugABq"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -22130,13 +22129,13 @@ paths:
id: inv_gbHJdmfrXB
status: pending
- created_at: '2026-08-16T18:08:59.295Z'
- updated_at: '2026-08-16T18:08:59.295Z'
- expires_at: '2026-08-30T18:08:59.290Z'
+ created_at: '2026-08-16T19:27:06.071Z'
+ updated_at: '2026-08-16T19:27:06.071Z'
+ expires_at: '2026-08-30T19:27:06.067Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=dbNepiqHT1ttmCYZXHeUi6At"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=uWqyTJo8uQgbS4CVNfUknDdz"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -22249,15 +22248,15 @@ paths:
application/json:
example:
id: inv_UkLWZg9DAJ
status: pending
- created_at: '2026-08-16T18:08:59.354Z'
- updated_at: '2026-08-16T18:08:59.354Z'
- expires_at: '2026-08-30T18:08:59.352Z'
+ created_at: '2026-08-16T19:27:06.113Z'
+ updated_at: '2026-08-16T19:27:06.113Z'
+ expires_at: '2026-08-30T19:27:06.112Z'
role_id: role_UkLWZg9DAJ
role_name: admin
- inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=8bA1ibzZqEscQvET3bNJcWqv"
+ inviter_email: [email protected]
+ acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=CzABL9TxG2UVaZqFNVQ3Q454"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -22559,6 +22558,20 @@ paths:
group_label: Access
label: Vendors
description: ''
+ - key: read_commissions
+ resource: commissions
+ kind: read
+ group: access
+ group_label: Access
+ label: Commissions
+ description: ''
+ - key: write_commissions
+ resource: commissions
+ kind: write
+ group: access
+ group_label: Access
+ label: Commissions
+ description: ''
- key: read_vendor_profile
resource: vendor_profile
kind: read
@@ -22581,7 +22594,7 @@ paths:
label: Analytics dashboard
description: Sales and performance analytics
meta:
- count: 39
+ count: 41
"/api/v3/admin/roles":
get:
summary: List roles
@@ -22630,8 +22643,8 @@ paths:
- id: role_UkLWZg9DAJ
name: admin
description:
- created_at: '2026-08-16T18:09:15.146Z'
- updated_at: '2026-08-16T18:09:15.146Z'
+ created_at: '2026-08-16T19:27:19.816Z'
+ updated_at: '2026-08-16T19:27:19.816Z'
permissions:
- read_orders
- write_orders
@@ -22669,6 +22682,8 @@ paths:
- write_staff
- read_vendors
- write_vendors
+ - read_commissions
+ - write_commissions
- read_vendor_profile
- write_vendor_profile
- read_dashboard
@@ -22735,8 +22750,8 @@ paths:
id: role_gbHJdmfrXB
name: order_manager
description: Handles daily orders
- created_at: '2026-08-16T18:09:15.194Z'
- updated_at: '2026-08-16T18:09:15.194Z'
+ created_at: '2026-08-16T19:27:19.865Z'
+ updated_at: '2026-08-16T19:27:19.865Z'
permissions:
- write_orders
- read_customers
@@ -22830,8 +22845,8 @@ paths:
id: role_gbHJdmfrXB
name: support
description:
- created_at: '2026-08-16T18:09:15.234Z'
- updated_at: '2026-08-16T18:09:15.252Z'
+ created_at: '2026-08-16T19:27:19.901Z'
+ updated_at: '2026-08-16T19:27:19.914Z'
permissions:
- read_orders
- read_customers
@@ -23027,8 +23042,8 @@ paths:
kind: warehouse
pickup_enabled: false
pickup_stock_policy: local
- created_at: '2026-08-16T18:09:15.457Z'
- updated_at: '2026-08-16T18:09:15.457Z'
+ created_at: '2026-08-16T19:27:20.069Z'
+ updated_at: '2026-08-16T19:27:20.069Z'
meta:
page: 1
limit: 25
@@ -23142,8 +23157,8 @@ paths:
kind: store
pickup_enabled: true
pickup_stock_policy: local
- created_at: '2026-08-16T18:09:15.530Z'
- updated_at: '2026-08-16T18:09:15.530Z'
+ created_at: '2026-08-16T19:27:20.126Z'
+ updated_at: '2026-08-16T19:27:20.126Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -23320,8 +23335,8 @@ paths:
kind: warehouse
pickup_enabled: false
pickup_stock_policy: local
- created_at: '2026-08-16T18:09:15.573Z'
- updated_at: '2026-08-16T18:09:15.573Z'
+ created_at: '2026-08-16T19:27:20.162Z'
+ updated_at: '2026-08-16T19:27:20.162Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'404':
@@ -23410,8 +23425,8 @@ paths:
kind: warehouse
pickup_enabled: true
pickup_stock_policy: local
- created_at: '2026-08-16T18:09:15.629Z'
- updated_at: '2026-08-16T18:09:15.647Z'
+ created_at: '2026-08-16T19:27:20.211Z'
+ updated_at: '2026-08-16T19:27:20.227Z'
schema:
"$ref": "#/components/schemas/StockLocation"
'422':
@@ -23619,7 +23634,7 @@ paths:
data:
- id: variant_UkLWZg9DAJ
product_id: prod_UkLWZg9DAJ
- sku: SKU-120
+ sku: SKU-124
options_text: ''
track_inventory: true
media_count: 0
@@ -23657,17 +23672,17 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-16T18:09:16.562Z'
- updated_at: '2026-08-16T18:09:16.589Z'
+ created_at: '2026-08-16T19:27:21.048Z'
+ updated_at: '2026-08-16T19:27:21.069Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 101419
+ product_name: Product 1052144
- id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-121
+ sku: SKU-125
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -23677,10 +23692,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 111.3
- height: 75.83
- width: 166.58
- depth: 196.49
+ weight: 64.7
+ height: 18.66
+ width: 62.44
+ depth: 195.64
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -23703,8 +23718,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:16.628Z'
- updated_at: '2026-08-16T18:09:16.628Z'
+ created_at: '2026-08-16T19:27:21.087Z'
+ updated_at: '2026-08-16T19:27:21.087Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -23717,14 +23732,14 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-16T18:09:16.623Z'
- updated_at: '2026-08-16T18:09:16.640Z'
+ created_at: '2026-08-16T19:27:21.085Z'
+ updated_at: '2026-08-16T19:27:21.096Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 101419
+ product_name: Product 1052144
meta:
page: 1
limit: 25
@@ -23838,8 +23853,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:16.788Z'
- updated_at: '2026-08-16T18:09:16.788Z'
+ created_at: '2026-08-16T19:27:21.211Z'
+ updated_at: '2026-08-16T19:27:21.211Z'
metadata: {}
position: 3
cost_price:
@@ -23852,14 +23867,14 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-16T18:09:16.793Z'
- updated_at: '2026-08-16T18:09:16.795Z'
+ created_at: '2026-08-16T19:27:21.215Z'
+ updated_at: '2026-08-16T19:27:21.217Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1021933
+ product_name: Product 1062636
'422':
description: validation error
content:
@@ -24036,7 +24051,7 @@ paths:
example:
id: variant_gbHJdmfrXB
product_id: prod_UkLWZg9DAJ
- sku: SKU-127
+ sku: SKU-131
options_text: 'Size: S'
track_inventory: true
media_count: 0
@@ -24046,10 +24061,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 47.17
- height: 187.56
- width: 105.27
- depth: 65.41
+ weight: 131.69
+ height: 90.64
+ width: 140.62
+ depth: 42.73
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -24072,8 +24087,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:16.969Z'
- updated_at: '2026-08-16T18:09:16.969Z'
+ created_at: '2026-08-16T19:27:21.364Z'
+ updated_at: '2026-08-16T19:27:21.364Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -24086,14 +24101,14 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-16T18:09:16.967Z'
- updated_at: '2026-08-16T18:09:16.980Z'
+ created_at: '2026-08-16T19:27:21.361Z'
+ updated_at: '2026-08-16T19:27:21.371Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1048582
+ product_name: Product 1086799
'404':
description: variant not found
content:
@@ -24177,10 +24192,10 @@ paths:
in_stock: false
backorderable: true
preorder: false
- weight: 177.32
- height: 88.48
- width: 181.93
- depth: 165.33
+ weight: 63.37
+ height: 81.6
+ width: 116.83
+ depth: 120.78
price:
id: price_gbHJdmfrXB
amount: '19.99'
@@ -24203,8 +24218,8 @@ paths:
option_type_label: Size
image_url:
metadata: {}
- created_at: '2026-08-16T18:09:17.160Z'
- updated_at: '2026-08-16T18:09:17.160Z'
+ created_at: '2026-08-16T19:27:21.521Z'
+ updated_at: '2026-08-16T19:27:21.521Z'
metadata: {}
position: 2
cost_price: '17.0'
@@ -24217,14 +24232,14 @@ paths:
country_of_origin:
customs_description:
deleted_at:
- created_at: '2026-08-16T18:09:17.157Z'
- updated_at: '2026-08-16T18:09:17.202Z'
+ created_at: '2026-08-16T19:27:21.518Z'
+ updated_at: '2026-08-16T19:27:21.549Z'
preorderable: false
tax_category_id: taxcat_UkLWZg9DAJ
available_stock: 0
reserved_quantity: 0
total_on_hand: 0
- product_name: Product 1063564
+ product_name: Product 1102173
requestBody:
content:
application/json:
@@ -24469,9 +24484,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-16T18:09:17.922Z'
- updated_at: '2026-08-16T18:09:17.922Z'
- delivered_at: '2026-08-16T18:09:17.922Z'
+ created_at: '2026-08-16T19:27:22.102Z'
+ updated_at: '2026-08-16T19:27:22.102Z'
+ delivered_at: '2026-08-16T19:27:22.102Z'
payload:
event: order.created
data:
@@ -24487,9 +24502,9 @@ paths:
request_errors:
response_body:
success: true
- created_at: '2026-08-16T18:09:17.921Z'
- updated_at: '2026-08-16T18:09:17.921Z'
- delivered_at: '2026-08-16T18:09:17.921Z'
+ created_at: '2026-08-16T19:27:22.101Z'
+ updated_at: '2026-08-16T19:27:22.101Z'
+ delivered_at: '2026-08-16T19:27:22.101Z'
payload:
event: order.created
data:
@@ -24592,9 +24607,9 @@ paths:
request_errors:
response_body:
success: false
- created_at: '2026-08-16T18:09:18.032Z'
- updated_at: '2026-08-16T18:09:18.032Z'
- delivered_at: '2026-08-16T18:09:18.032Z'
+ created_at: '2026-08-16T19:27:22.194Z'
+ updated_at: '2026-08-16T19:27:22.194Z'
+ delivered_at: '2026-08-16T19:27:22.194Z'
payload:
event: order.created
data:
@@ -24683,8 +24698,8 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-16T18:09:18.276Z'
- updated_at: '2026-08-16T18:09:18.276Z'
+ created_at: '2026-08-16T19:27:22.310Z'
+ updated_at: '2026-08-16T19:27:22.310Z'
delivered_at:
payload:
event: order.created
@@ -24787,8 +24802,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-16T18:09:18.404Z'
- updated_at: '2026-08-16T18:09:18.404Z'
+ created_at: '2026-08-16T19:27:22.337Z'
+ updated_at: '2026-08-16T19:27:22.337Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -24883,10 +24898,10 @@ paths:
subscriptions:
- order.placed
disabled_reason:
- created_at: '2026-08-16T18:09:18.532Z'
- updated_at: '2026-08-16T18:09:18.532Z'
+ created_at: '2026-08-16T19:27:22.459Z'
+ updated_at: '2026-08-16T19:27:22.459Z'
disabled_at:
- secret_key: 1e835ba9a73a476d28448faecf70a4b31e93d952a7bf4c490ba38fef0006c7f6
+ secret_key: f2872cccfe7be32d6aaafda044c78c2c17d68642ce8c99d7e641912f7fffac4d
last_delivery_at:
recent_delivery_count: 0
recent_failure_count: 0
@@ -25009,8 +25024,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-16T18:09:18.634Z'
- updated_at: '2026-08-16T18:09:18.634Z'
+ created_at: '2026-08-16T19:27:22.549Z'
+ updated_at: '2026-08-16T19:27:22.549Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -25089,8 +25104,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-16T18:09:18.737Z'
- updated_at: '2026-08-16T18:09:18.755Z'
+ created_at: '2026-08-16T19:27:22.678Z'
+ updated_at: '2026-08-16T19:27:22.692Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -25247,13 +25262,13 @@ paths:
request_errors:
response_body:
success:
- created_at: '2026-08-16T18:09:18.999Z'
- updated_at: '2026-08-16T18:09:18.999Z'
+ created_at: '2026-08-16T19:27:22.830Z'
+ updated_at: '2026-08-16T19:27:22.830Z'
delivered_at:
payload:
- id: 3a351236-c3bb-4d8c-a627-fce55fb7895d
+ id: c1ff013d-4906-4f09-b8d4-2f3f7bee220b
name: webhook.test
- created_at: '2026-08-16T18:09:18Z'
+ created_at: '2026-08-16T19:27:22Z'
data:
message: This is a test webhook from Spree.
metadata:
@@ -25322,8 +25337,8 @@ paths:
- order.completed
- product.created
disabled_reason:
- created_at: '2026-08-16T18:09:19.023Z'
- updated_at: '2026-08-16T18:09:19.044Z'
+ created_at: '2026-08-16T19:27:22.855Z'
+ updated_at: '2026-08-16T19:27:22.871Z'
disabled_at:
secret_key:
last_delivery_at:
@@ -25400,9 +25415,9 @@ paths:
- order.completed
- product.created
disabled_reason: Investigating
- created_at: '2026-08-16T18:09:19.074Z'
- updated_at: '2026-08-16T18:09:19.094Z'
- disabled_at: '2026-08-16T18:09:19.093Z'
+ created_at: '2026-08-16T19:27:22.894Z'
+ updated_at: '2026-08-16T19:27:22.909Z'
+ disabled_at: '2026-08-16T19:27:22.909Z'
secret_key:
last_delivery_at:
recent_delivery_count: 0
@@ -25485,8 +25500,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-16T18:08:54.658Z'
- updated_at: '2026-08-16T18:08:54.658Z'
+ created_at: '2026-08-16T19:27:00.756Z'
+ updated_at: '2026-08-16T19:27:00.756Z'
meta:
page: 1
limit: 25
@@ -25554,8 +25569,8 @@ paths:
automatic: true
rules_match_policy: any
metadata: {}
- created_at: '2026-08-16T18:08:54.721Z'
- updated_at: '2026-08-16T18:08:54.724Z'
+ created_at: '2026-08-16T19:27:00.823Z'
+ updated_at: '2026-08-16T19:27:00.825Z'
schema:
"$ref": "#/components/schemas/Collection"
'422':
@@ -25682,8 +25697,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-16T18:08:54.772Z'
- updated_at: '2026-08-16T18:08:54.772Z'
+ created_at: '2026-08-16T19:27:00.883Z'
+ updated_at: '2026-08-16T19:27:00.883Z'
schema:
"$ref": "#/components/schemas/Collection"
'404':
@@ -25747,8 +25762,8 @@ paths:
automatic: false
rules_match_policy: all
metadata: {}
- created_at: '2026-08-16T18:08:54.830Z'
- updated_at: '2026-08-16T18:08:54.863Z'
+ created_at: '2026-08-16T19:27:00.942Z'
+ updated_at: '2026-08-16T19:27:00.964Z'
schema:
"$ref": "#/components/schemas/Collection"
requestBody:
@@ -25923,8 +25938,8 @@ paths:
application/json:
example:
id: prod_UkLWZg9DAJ
- name: Product 67503
- slug: product-67503
+ name: Product 66739
+ slug: product-66739
meta_title:
meta_description:
meta_keywords:
@@ -25936,12 +25951,26 @@ paths:
in_stock: false
backorderable: true
available: true
- description: Eius et delectus nesciunt doloribus ullam. Nesciunt ratione
- rem labore earum atque. Vel doloribus a quisquam quasi excepturi
- aperiam eos. Similique libero nam sit quam exercitationem saepe.
- description_html: Eius et delectus nesciunt doloribus ullam. Nesciunt
- ratione rem labore earum atque. Vel doloribus a quisquam quasi excepturi
- aperiam eos. Similique libero nam sit quam exercitationem saepe.
+ description: Eos eum reprehenderit sequi non. Maxime quos similique
+ ratione aut amet consectetur. Illum voluptas ea tenetur asperiores.
+ Totam ratione quidem et amet. Doloremque eius numquam quod deserunt.
+ Ut ipsam assumenda quia sunt dolorem corporis. Nam fuga distinctio
+ aut animi in. Distinctio doloremque ad reiciendis molestiae similique
+ repudiandae ducimus nulla. Consectetur aperiam amet vero sequi incidunt
+ nostrum. Ducimus sapiente a perspiciatis atque deserunt porro autem
+ nisi. Eveniet quibusdam deserunt est tempora consequuntur molestias
+ placeat dolores. Vitae laudantium aut veniam distinctio iusto atque.
+ Corrupti assumenda dolore delectus esse libero ipsum. Quidem tenetur
+ laudantium quis enim sequi et dolore. Autem in officia sapiente
+ magni ad. Omnis amet aliquid repudiandae saepe officia illo nesciunt.
+ Repellat temporibus mollitia natus adipisci. Libero dicta id minus
+ repellat. Autem vel nisi officiis omnis eligendi magni ipsam quo.
+ description_html: |-
+ Eos eum reprehenderit sequi non. Maxime quos similique ratione aut amet consectetur. Illum voluptas ea tenetur asperiores.
+ Totam ratione quidem et amet. Doloremque eius numquam quod deserunt. Ut ipsam assumenda quia sunt dolorem corporis. Nam fuga distinctio aut animi in.
+ Distinctio doloremque ad reiciendis molestiae similique repudiandae ducimus nulla. Consectetur aperiam amet vero sequi incidunt nostrum. Ducimus sapiente a perspiciatis atque deserunt porro autem nisi. Eveniet quibusdam deserunt est tempora consequuntur molestias placeat dolores. Vitae laudantium aut veniam distinctio iusto atque.
+ Corrupti assumenda dolore delectus esse libero ipsum. Quidem tenetur laudantium quis enim sequi et dolore. Autem in officia sapiente magni ad.
+ Omnis amet aliquid repudiandae saepe officia illo nesciunt. Repellat temporibus mollitia natus adipisci. Libero dicta id minus repellat. Autem vel nisi officiis omnis eligendi magni ipsam quo.
default_variant_id: variant_UkLWZg9DAJ
thumbnail_url:
tags: []
@@ -25956,15 +25985,15 @@ paths:
display_compare_at_amount:
price_list_id:
variant_id: variant_UkLWZg9DAJ
- created_at: '2026-08-16T18:08:54.979Z'
- updated_at: '2026-08-16T18:08:54.979Z'
+ created_at: '2026-08-16T19:27:01.066Z'
+ updated_at: '2026-08-16T19:27:01.066Z'
original_price:
vendor_id:
status: active
metadata: {}
deleted_at:
- created_at: '2026-08-16T18:08:54.962Z'
- updated_at: '2026-08-16T18:08:54.988Z'
+ created_at: '2026-08-16T19:27:01.055Z'
+ updated_at: '2026-08-16T19:27:01.075Z'
delivery_profile_id: fp_UkLWZg9DAJ
vendor_name:
product_type_id:
@@ -26114,18 +26143,31 @@ paths:
label: Tag
description: Products carrying a matching tag
preference_schema: []
- "/api/v3/admin/companies/{company_id}/locations":
+ "/api/v3/admin/commission_lines":
get:
- summary: List company locations
+ summary: List commission lines
tags:
- - Companies
+ - Commission Lines
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.
+ What each sale actually earned the marketplace, frozen when the order
+ was placed. A later change to a commission rate never reaches these.
- **Required scope:** `read_customers` (for API-key authentication).
+ `amount` is the fee charged to the seller and `tax_amount` is the VAT on
+ that fee — the marketplace's own service to the seller, a supply
+ separate from the sale itself, which is why the two are not folded
+ together. `total` is their sum.
+
+ One line per commissioned item, plus one per delivery when the rate that
+ applied charges shipping too — read `line_item_id` and `fulfillment_id`
+ to tell them apart.
+
+ Read-only: correcting a charge is a reversal, not an edit.
+
+
+ **Required scope:** `read_commissions` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26137,10 +26179,12 @@ paths:
secretKey: 'sk_xxx',
})
- const { data: locations } = await client.companies.locations.list('comp_UkLWZg9DAJ')
+ // `amount` is the fee and `tax_amount` is the VAT charged on that fee — two
+ // separate supplies, which is why they are not folded together.
+ const { data: commissionLines } = await client.commissionLines.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
- source: spree api get /companies/{company_id}/locations
+ source: spree api get /commission_lines -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -26150,30 +26194,64 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: company_id
- in: path
- required: true
+ - name: page
+ in: query
+ required: false
+ description: Page number
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: Number of records per page
+ schema:
+ type: integer
+ - name: q[vendor_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: locations found
+ description: commission lines found
content:
application/json:
example:
data:
- - id: cloc_UkLWZg9DAJ
- name: Berlin
- external_id:
- metadata: {}
- created_at: '2026-08-16T18:08:55.205Z'
- updated_at: '2026-08-16T18:08:55.205Z'
- company_id: comp_UkLWZg9DAJ
- contacts_count: 0
- billing_address:
- shipping_address:
+ - id: comln_UkLWZg9DAJ
+ kind: percentage
+ currency: USD
+ created_at: '2026-08-16T19:27:01.419Z'
+ updated_at: '2026-08-16T19:27:01.419Z'
+ rate: '10.0'
+ amount: '10.0'
+ tax_amount: '2.1'
+ total: '12.1'
+ display_amount: "$10.00"
+ display_tax_amount: "$2.10"
+ display_total: "$12.10"
+ order_id: or_UkLWZg9DAJ
+ vendor_id: ven_UkLWZg9DAJ
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ commission_rate_id:
+ vendor_name: Sparks Audio
meta:
page: 1
limit: 25
@@ -26184,17 +26262,109 @@ paths:
in: 1
previous:
next:
- post:
- summary: Create a company location
+ 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:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ 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:
- - Companies
+ - 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:
+ example:
+ id: comln_UkLWZg9DAJ
+ kind: percentage
+ currency: USD
+ created_at: '2026-08-16T19:27:01.657Z'
+ updated_at: '2026-08-16T19:27:01.657Z'
+ rate: '10.0'
+ amount: '10.0'
+ tax_amount: '2.1'
+ total: '12.1'
+ display_amount: "$10.00"
+ display_tax_amount: "$2.10"
+ display_total: "$12.10"
+ order_id: or_UkLWZg9DAJ
+ vendor_id: ven_UkLWZg9DAJ
+ line_item_id: li_UkLWZg9DAJ
+ fulfillment_id:
+ commission_rate_id:
+ vendor_name: Sparks Audio
+ schema:
+ "$ref": "#/components/schemas/CommissionLine"
+ '404':
+ description: commission line not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Commission line not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/admin/commission_rates":
+ get:
+ summary: List commission rates
+ tags:
+ - Commission Rates
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.
+ What the marketplace charges its sellers.
- **Required scope:** `write_customers` (for API-key authentication).
+ Rates are tried in `priority` order, highest first, and the first one
+ whose targeting matches the sale wins. A rate carrying no rules matches
+ everything, which is how a marketplace expresses a single default
+ without configuring anything.
+
+
+ **Required scope:** `read_commissions` (for API-key authentication).
x-codeSamples:
- lang: javascript
label: Spree Admin SDK
@@ -26206,22 +26376,12 @@ paths:
secretKey: 'sk_xxx',
})
- const location = await client.companies.locations.create('comp_UkLWZg9DAJ', {
- name: 'Hamburg warehouse',
- billing_address: {
- first_name: 'Anna',
- last_name: 'Muller',
- address1: 'Hafenstr 1',
- city: 'Hamburg',
- postal_code: '20095',
- country_code: 'DE',
- },
- })
+ // Rates come back with their targeting attached. A rate holding no rules
+ // applies to every sale.
+ const { data: commissionRates } = await client.commissionRates.list({ page: 1, limit: 25 })
- lang: bash
label: Spree CLI
- source: spree api post /companies/{company_id}/locations -d '{"name":"Hamburg
- warehouse","billing_address":{"first_name":"Anna","last_name":"Muller","address1":"Hafenstr
- 1","city":"Hamburg","postal_code":"20095","country_code":"DE"}}'
+ source: spree api get /commission_rates -d '{"page":1,"limit":25}'
parameters:
- name: x-spree-api-key
in: header
@@ -26231,77 +26391,721 @@ paths:
- name: Authorization
in: header
required: true
+ description: Bearer token for admin authentication
schema:
type: string
- - name: company_id
- in: path
- required: true
+ - name: page
+ in: query
+ required: false
+ description: Page number
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: Number of records per page
+ schema:
+ type: integer
+ - name: q[name_cont]
+ in: query
+ required: false
+ description: Filter by name (contains)
+ schema:
+ type: string
+ - name: 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., `-priority`).
schema:
type: string
responses:
- '201':
- description: location created
- content:
- application/json:
- example:
- id: cloc_gbHJdmfrXB
- name: Hamburg warehouse
- external_id:
- metadata: {}
- created_at: '2026-08-16T18:08:55.263Z'
- updated_at: '2026-08-16T18:08:55.263Z'
- company_id: comp_UkLWZg9DAJ
- contacts_count: 0
- billing_address:
- id: addr_UkLWZg9DAJ
- first_name: Anna
- last_name: Muller
- full_name: Anna Muller
- address1: Hafenstr 1
- address2:
- postal_code: '20095'
- city: Hamburg
- phone:
- company:
- country_name: Germany
- country_code: DE
- state_text:
- state_code:
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr:
- country_iso: DE
- state_name:
- label:
- metadata: {}
- created_at: '2026-08-16T18:08:55.262Z'
- updated_at: '2026-08-16T18:08:55.262Z'
- customer_id:
- shipping_address:
- '422':
- description: invalid request
+ '200':
+ description: commission rates found
content:
application/json:
example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Hamburg warehouse
- external_id:
- type: string
- nullable: true
+ data:
+ - id: comrt_UkLWZg9DAJ
+ name: Standard
+ code:
+ enabled: true
+ priority: 5
+ kind: percentage
+ currency:
+ include_tax: false
+ include_shipping: false
+ deleted_at:
+ created_at: '2026-08-16T19:27:01.784Z'
+ updated_at: '2026-08-16T19:27:01.784Z'
+ value: '10.0'
+ min_amount:
+ max_amount:
+ commission_tax_rate:
+ rules: []
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/CommissionRate"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ '401':
+ description: unauthorized
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ post:
+ summary: Create a commission rate
+ tags:
+ - Commission Rates
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Sets what the marketplace charges, and which sales it applies to.
+
+ `rules` is the rate's whole targeting, sent inline. Rules are grouped by
+ `subject_type` and matched AND across the groups, OR within one — so
+ `[Cameras, Audio, VendorX]` reads "(Cameras OR Audio) AND VendorX",
+ which is how a seller-and-category pairing is expressed. Send no rules
+ to charge every sale.
+
+ `commission_tax_rate` is VAT on the commission itself — the
+ marketplace's own service to the seller, a separate supply from the
+ sale. Leave it null to let the store's tax engine answer for wherever
+ the seller's business sits.
+
+
+ **Required scope:** `write_commissions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Charges this seller 12.5% of every sale, with VAT on the commission itself
+ // left to your tax settings.
+ const commissionRate = await client.commissionRates.create({
+ name: 'Audio sellers',
+ kind: 'percentage',
+ value: 12.5,
+ priority: 10,
+ rules: [{ subject_type: 'Spree::Vendor', subject_id: 'ven_a1b2c3' }],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /commission_rates -d '{"name":"Audio sellers","kind":"percentage","value":12.5,"priority":10,"rules":[{"subject_type":"Spree::Vendor","subject_id":"ven_a1b2c3"}]}'
+ 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:
+ example:
+ id: comrt_gbHJdmfrXB
+ name: Audio sellers
+ code:
+ enabled: true
+ priority: 10
+ kind: percentage
+ currency:
+ include_tax: false
+ include_shipping: false
+ deleted_at:
+ created_at: '2026-08-16T19:27:01.846Z'
+ updated_at: '2026-08-16T19:27:01.846Z'
+ value: '12.5'
+ min_amount:
+ max_amount:
+ commission_tax_rate:
+ rules: []
+ schema:
+ "$ref": "#/components/schemas/CommissionRate"
+ '422':
+ description: validation failed
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Currency can't be blank
+ details:
+ currency:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ required:
+ - name
+ - kind
+ - value
+ properties:
+ name:
+ type: string
+ example: Audio sellers
+ code:
+ type: string
+ example: audio
+ nullable: true
+ description: Your own identifier for this rate; unique per store.
+ enabled:
+ type: boolean
+ example: true
+ priority:
+ type: integer
+ example: 10
+ description: Tried highest first; the first matching rate wins.
+ kind:
+ type: string
+ enum:
+ - percentage
+ - fixed
+ example: percentage
+ value:
+ type: string
+ example: '12.5'
+ description: A percentage (10 = 10%) or a flat amount, per `kind`.
+ currency:
+ type: string
+ example: USD
+ nullable: true
+ description: Required for a fixed rate, ignored for a percentage.
+ include_tax:
+ type: boolean
+ example: false
+ description: 'Charge on the gross price. Off is the EU rule: charge
+ on the seller''s net revenue.'
+ include_shipping:
+ type: boolean
+ example: false
+ description: Also charge commission on the seller's delivery revenue.
+ min_amount:
+ type: string
+ example: '1.0'
+ nullable: true
+ max_amount:
+ type: string
+ example: '50.0'
+ nullable: true
+ commission_tax_rate:
+ type: string
+ example: '0.21'
+ 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:
+ subject_type:
+ type: string
+ enum:
+ - Spree::Product
+ - Spree::Category
+ - Spree::Vendor
+ subject_id:
+ type: string
+ example: ven_a1b2c3
+ "/api/v3/admin/commission_rates/rule_subject_types":
+ get:
+ summary: List what a commission rule may target
+ tags:
+ - Commission Rates
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ The subject types a rule may name, so a client can build its picker
+ without hardcoding a list core owns.
+
+
+ **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:
+ example:
+ data:
+ - type: Spree::Product
+ name: Product
+ - type: Spree::Category
+ name: Category
+ - type: Spree::Vendor
+ name: Vendor
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ type:
+ type: string
+ example: Spree::Vendor
+ name:
+ type: string
+ example: Vendor
+ "/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)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const commissionRate = await client.commissionRates.get('comrt_a1b2c3')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /commission_rates/{id}
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: commission rate found
+ content:
+ application/json:
+ example:
+ id: comrt_UkLWZg9DAJ
+ name: Standard
+ code:
+ enabled: true
+ priority: 5
+ kind: percentage
+ currency:
+ include_tax: false
+ include_shipping: false
+ deleted_at:
+ created_at: '2026-08-16T19:27:01.913Z'
+ updated_at: '2026-08-16T19:27:01.913Z'
+ value: '10.0'
+ min_amount:
+ max_amount:
+ commission_tax_rate:
+ rules: []
+ schema:
+ "$ref": "#/components/schemas/CommissionRate"
+ '404':
+ description: commission rate not found
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Commission rate not found
+ 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
+ one was: commission lines keep their own snapshot of the rate that
+ applied.
+
+
+ **Required scope:** `write_commissions` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // `rules` is the rate's whole targeting — what you send replaces what it holds.
+ const commissionRate = await client.commissionRates.update('comrt_a1b2c3', {
+ value: 15,
+ rules: [{ subject_type: 'Spree::Category', subject_id: 'ctg_d4e5f6' }],
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api patch /commission_rates/{id} -d '{"value":15,"rules":[{"subject_type":"Spree::Category","subject_id":"ctg_d4e5f6"}]}'
+ parameters:
+ - 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:
+ example:
+ id: comrt_UkLWZg9DAJ
+ name: Standard
+ code:
+ enabled: true
+ priority: 5
+ kind: percentage
+ currency:
+ include_tax: false
+ include_shipping: false
+ deleted_at:
+ created_at: '2026-08-16T19:27:01.978Z'
+ updated_at: '2026-08-16T19:27:01.998Z'
+ value: '15.0'
+ min_amount:
+ max_amount:
+ commission_tax_rate:
+ rules: []
+ schema:
+ "$ref": "#/components/schemas/CommissionRate"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Standard
+ enabled:
+ type: boolean
+ example: true
+ priority:
+ type: integer
+ example: 20
+ value:
+ type: string
+ example: '15.0'
+ rules:
+ type: array
+ items:
+ type: object
+ properties:
+ subject_type:
+ type: string
+ example: Spree::Category
+ subject_id:
+ type: string
+ example: ctg_a1b2c3
+ delete:
+ summary: Delete a commission rate
+ tags:
+ - Commission Rates
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: "**Required scope:** `write_commissions` (for API-key authentication)."
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ // Commission already charged is unaffected — the lines keep their own snapshot.
+ await client.commissionRates.delete('comrt_a1b2c3')
+ - lang: bash
+ label: Spree CLI
+ source: spree api delete /commission_rates/{id}
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: 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.
+
+ **Required scope:** `read_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const { data: locations } = await client.companies.locations.list('comp_UkLWZg9DAJ')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /companies/{company_id}/locations
+ 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:
+ example:
+ data:
+ - id: cloc_UkLWZg9DAJ
+ name: Berlin
+ external_id:
+ metadata: {}
+ created_at: '2026-08-16T19:27:02.039Z'
+ updated_at: '2026-08-16T19:27:02.039Z'
+ company_id: comp_UkLWZg9DAJ
+ contacts_count: 0
+ billing_address:
+ shipping_address:
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
+ 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.
+
+ **Required scope:** `write_customers` (for API-key authentication).
+ x-codeSamples:
+ - lang: javascript
+ label: Spree Admin SDK
+ source: |-
+ import { createAdminClient } from '@spree/admin-sdk'
+
+ const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+ })
+
+ const location = await client.companies.locations.create('comp_UkLWZg9DAJ', {
+ name: 'Hamburg warehouse',
+ billing_address: {
+ first_name: 'Anna',
+ last_name: 'Muller',
+ address1: 'Hafenstr 1',
+ city: 'Hamburg',
+ postal_code: '20095',
+ country_code: 'DE',
+ },
+ })
+ - lang: bash
+ label: Spree CLI
+ source: spree api post /companies/{company_id}/locations -d '{"name":"Hamburg
+ warehouse","billing_address":{"first_name":"Anna","last_name":"Muller","address1":"Hafenstr
+ 1","city":"Hamburg","postal_code":"20095","country_code":"DE"}}'
+ 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:
+ example:
+ id: cloc_gbHJdmfrXB
+ name: Hamburg warehouse
+ external_id:
+ metadata: {}
+ created_at: '2026-08-16T19:27:02.086Z'
+ updated_at: '2026-08-16T19:27:02.086Z'
+ company_id: comp_UkLWZg9DAJ
+ contacts_count: 0
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ first_name: Anna
+ last_name: Muller
+ full_name: Anna Muller
+ address1: Hafenstr 1
+ address2:
+ postal_code: '20095'
+ city: Hamburg
+ phone:
+ company:
+ country_name: Germany
+ country_code: DE
+ state_text:
+ state_code:
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr:
+ country_iso: DE
+ state_name:
+ label:
+ metadata: {}
+ created_at: '2026-08-16T19:27:02.085Z'
+ updated_at: '2026-08-16T19:27:02.085Z'
+ customer_id:
+ shipping_address:
+ '422':
+ description: invalid request
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Hamburg warehouse
+ external_id:
+ type: string
+ nullable: true
example: HAM-01
billing_address:
type: object
@@ -26375,8 +27179,8 @@ paths:
name: Berlin
external_id:
metadata: {}
- created_at: '2026-08-16T18:08:55.295Z'
- updated_at: '2026-08-16T18:08:55.295Z'
+ created_at: '2026-08-16T19:27:02.118Z'
+ updated_at: '2026-08-16T19:27:02.118Z'
company_id: comp_UkLWZg9DAJ
contacts_count: 0
billing_address:
@@ -26422,8 +27226,8 @@ paths:
name: Berlin Mitte
external_id:
metadata: {}
- created_at: '2026-08-16T18:08:55.318Z'
- updated_at: '2026-08-16T18:08:55.332Z'
+ created_at: '2026-08-16T19:27:02.143Z'
+ updated_at: '2026-08-16T19:27:02.160Z'
company_id: comp_UkLWZg9DAJ
contacts_count: 0
billing_address:
@@ -26538,8 +27342,8 @@ paths:
issued_at:
expires_at:
verified_at:
- created_at: '2026-08-16T18:08:55.364Z'
- updated_at: '2026-08-16T18:08:55.364Z'
+ created_at: '2026-08-16T19:27:02.198Z'
+ updated_at: '2026-08-16T19:27:02.198Z'
company_id: comp_UkLWZg9DAJ
country_code:
state_code:
@@ -26623,8 +27427,8 @@ paths:
issued_at:
expires_at:
verified_at:
- created_at: '2026-08-16T18:08:55.415Z'
- updated_at: '2026-08-16T18:08:55.417Z'
+ created_at: '2026-08-16T19:27:02.252Z'
+ updated_at: '2026-08-16T19:27:02.254Z'
company_id: comp_UkLWZg9DAJ
country_code: DE
state_code:
@@ -26753,9 +27557,9 @@ paths:
metadata: {}
issued_at:
expires_at:
- verified_at: '2026-08-16T18:08:55.507Z'
- created_at: '2026-08-16T18:08:55.488Z'
- updated_at: '2026-08-16T18:08:55.508Z'
+ verified_at: '2026-08-16T19:27:02.342Z'
+ created_at: '2026-08-16T19:27:02.324Z'
+ updated_at: '2026-08-16T19:27:02.343Z'
company_id: comp_UkLWZg9DAJ
country_code:
state_code:
@@ -26833,9 +27637,9 @@ paths:
metadata: {}
issued_at:
expires_at:
- verified_at: '2026-08-16T18:08:55.517Z'
- created_at: '2026-08-16T18:08:55.517Z'
- updated_at: '2026-08-16T18:08:55.534Z'
+ verified_at: '2026-08-16T19:27:02.352Z'
+ created_at: '2026-08-16T19:27:02.353Z'
+ updated_at: '2026-08-16T19:27:02.372Z'
company_id: comp_UkLWZg9DAJ
country_code:
state_code:
@@ -26953,8 +27757,8 @@ paths:
validation_evidence:
source:
validated_at:
- created_at: '2026-08-16T18:08:55.632Z'
- updated_at: '2026-08-16T18:08:55.632Z'
+ created_at: '2026-08-16T19:27:02.471Z'
+ updated_at: '2026-08-16T19:27:02.471Z'
validatable: false
customer_id:
cart_id:
@@ -27016,8 +27820,8 @@ paths:
validation_evidence:
source:
validated_at:
- created_at: '2026-08-16T18:08:55.685Z'
- updated_at: '2026-08-16T18:08:55.685Z'
+ created_at: '2026-08-16T19:27:02.518Z'
+ updated_at: '2026-08-16T19:27:02.518Z'
validatable: false
customer_id:
cart_id:
@@ -27164,8 +27968,8 @@ paths:
name: Acme Industrial
external_id: ACME-1
metadata: {}
- created_at: '2026-08-16T18:08:55.742Z'
- updated_at: '2026-08-16T18:08:55.742Z'
+ created_at: '2026-08-16T19:27:02.574Z'
+ updated_at: '2026-08-16T19:27:02.574Z'
locations_count: 0
meta:
page: 1
@@ -27227,8 +28031,8 @@ paths:
name: Globex Corporation
external_id: GLBX-42
metadata: {}
- created_at: '2026-08-16T18:08:55.783Z'
- updated_at: '2026-08-16T18:08:55.783Z'
+ created_at: '2026-08-16T19:27:02.617Z'
+ updated_at: '2026-08-16T19:27:02.617Z'
locations_count: 0
'422':
description: invalid request
@@ -27310,8 +28114,8 @@ paths:
data:
- id: cc_UkLWZg9DAJ
role: buyer
- created_at: '2026-08-16T18:08:55.826Z'
- updated_at: '2026-08-16T18:08:55.826Z'
+ created_at: '2026-08-16T19:27:02.660Z'
+ updated_at: '2026-08-16T19:27:02.660Z'
company_location_id: cloc_UkLWZg9DAJ
customer_id: cust_UkLWZg9DAJ
@@ -27367,11 +28171,11 @@ paths:
example:
id: cc_gbHJdmfrXB
role: admin
- created_at: '2026-08-16T18:08:55.879Z'
- updated_at: '2026-08-16T18:08:55.879Z'
+ created_at: '2026-08-16T19:27:02.717Z'
+ updated_at: '2026-08-16T19:27:02.717Z'
company_location_id: cloc_UkLWZg9DAJ
customer_id: cust_gbHJdmfrXB
'422':
description: invalid request
content:
@@ -27446,8 +28250,8 @@ paths:
example:
id: cc_UkLWZg9DAJ
role: buyer
- created_at: '2026-08-16T18:08:55.922Z'
- updated_at: '2026-08-16T18:08:55.922Z'
+ created_at: '2026-08-16T19:27:02.762Z'
+ updated_at: '2026-08-16T19:27:02.762Z'
company_location_id: cloc_UkLWZg9DAJ
customer_id: cust_UkLWZg9DAJ
@@ -27530,8 +28334,8 @@ paths:
name: General
default: true
position: 1
- created_at: '2026-08-16T18:08:52.505Z'
- updated_at: '2026-08-16T18:08:52.505Z'
+ created_at: '2026-08-16T19:26:58.805Z'
+ updated_at: '2026-08-16T19:26:58.805Z'
kind: shipping
digital: false
offers_pickup: false
@@ -27602,11 +28406,11 @@ paths:
application/json:
example:
id: fp_gbHJdmfrXB
- name: Oversized 1786903737.373298
+ name: Oversized 1786908424.230016
default: false
position: 2
- created_at: '2026-08-16T18:08:57.377Z'
- updated_at: '2026-08-16T18:08:57.377Z'
+ created_at: '2026-08-16T19:27:04.233Z'
+ updated_at: '2026-08-16T19:27:04.233Z'
kind: shipping
digital: false
offers_pickup: false
@@ -27710,8 +28514,8 @@ paths:
id: og_EfhxLZ9ck8
name: EU warehouse
position: 2
- created_at: '2026-08-16T18:08:57.435Z'
- updated_at: '2026-08-16T18:08:57.435Z'
+ created_at: '2026-08-16T19:27:04.300Z'
+ updated_at: '2026-08-16T19:27:04.300Z'
delivery_profile_id: fp_gbHJdmfrXB
stock_location_ids:
- sloc_UkLWZg9DAJ
@@ -27786,11 +28590,11 @@ paths:
application/json:
example:
id: fp_gbHJdmfrXB
- name: Bulky 1786903737.4443882
+ name: Bulky 1786908424.309066
default: false
position: 2
- created_at: '2026-08-16T18:08:57.445Z'
- updated_at: '2026-08-16T18:08:57.445Z'
+ created_at: '2026-08-16T19:27:04.309Z'
+ updated_at: '2026-08-16T19:27:04.309Z'
kind: shipping
digital: false
offers_pickup: false
@@ -27921,8 +28725,8 @@ paths:
tracking_url:
markup_flat: '0.0'
markup_percent: '0.0'
- created_at: '2026-08-16T18:08:57.548Z'
- updated_at: '2026-08-16T18:08:57.549Z'
+ created_at: '2026-08-16T19:27:04.382Z'
+ updated_at: '2026-08-16T19:27:04.383Z'
deleted_at:
services: []
rules: []
@@ -27933,9 +28737,9 @@ paths:
stock_location_ids: []
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ amounts: {}
amount: '10.0'
currency: USD
- amounts: {}
meta:
page: 1
limit: 25
@@ -28010,8 +28814,8 @@ paths:
tracking_url:
markup_flat: '0.0'
markup_percent: '0.0'
- created_at: '2026-08-16T18:08:57.613Z'
- updated_at: '2026-08-16T18:08:57.614Z'
+ created_at: '2026-08-16T19:27:04.443Z'
+ updated_at: '2026-08-16T19:27:04.444Z'
deleted_at:
services: []
rules: []
@@ -28022,9 +28826,9 @@ paths:
stock_location_ids: []
calculator_type: Spree::Calculator::Shipping::FlatRate
calculator_preferences:
+ amounts: {}
amount: '12.5'
currency: USD
- amounts: {}
requestBody:
content:
application/json:
@@ -28129,69 +28933,69 @@ paths:
- type: Spree::Calculator::Shipping::FlatRate
name: Flat rate
preference_schema:
+ - key: amounts
+ type: hash
+ default: {}
- key: amount
type: decimal
default: 0
- key: currency
type: string
default: USD
- - key: amounts
- type: hash
- default: {}
- type: Spree::Calculator::Shipping::FlexiRate
name: Flexible Rate per package item
preference_schema:
- - key: currency
- type: string
- default: USD
- - key: first_item
- type: decimal
- default: 0.0
- key: additional_item
type: decimal
default: 0.0
- key: max_items
type: integer
default: 0
+ - key: currency
+ type: string
+ default: USD
+ - key: first_item
+ type: decimal
+ default: 0.0
- type: Spree::Calculator::Shipping::PerItem
name: Flat rate per package item
preference_schema:
+ - key: amounts
+ type: hash
+ default: {}
- key: amount
type: decimal
default: 0
- key: currency
type: string
default: USD
- - key: amounts
- type: hash
- default: {}
- type: Spree::Calculator::Shipping::PriceSack
name: Price sack
preference_schema:
- - key: normal_amount
+ - key: minimal_amount
type: decimal
default: 0
- - key: discount_amount
+ - key: normal_amount
type: decimal
default: 0
- key: currency
type: string
default: USD
- - key: minimal_amount
+ - key: discount_amount
type: decimal
default: 0
- type: Spree::Calculator::Shipping::DigitalDelivery
name: Digital Delivery
preference_schema:
+ - key: amounts
+ type: hash
+ default: {}
- key: amount
type: decimal
default: 0
- key: currency
type: string
default: USD
- - key: amounts
- type: hash
- default: {}
"/api/v3/admin/delivery_zones":
post:
summary: Create delivery zone
@@ -28261,8 +29065,8 @@ paths:
postal_code_to:
country_name: United States
state_name:
- created_at: '2026-08-16T18:08:57.694Z'
- updated_at: '2026-08-16T18:08:57.694Z'
+ created_at: '2026-08-16T19:27:04.618Z'
+ updated_at: '2026-08-16T19:27:04.618Z'
- id: dzm_gbHJdmfrXB
member_type: postal_code
country_code: US
@@ -28272,10 +29076,10 @@ paths:
postal_code_to:
country_name: United States
state_name:
- created_at: '2026-08-16T18:08:57.695Z'
- updated_at: '2026-08-16T18:08:57.695Z'
- created_at: '2026-08-16T18:08:57.693Z'
- updated_at: '2026-08-16T18:08:57.693Z'
+ created_at: '2026-08-16T19:27:04.619Z'
+ updated_at: '2026-08-16T19:27:04.619Z'
+ created_at: '2026-08-16T19:27:04.618Z'
+ updated_at: '2026-08-16T19:27:04.618Z'
delivery_profile_id: fp_UkLWZg9DAJ
delivery_origin_group_id: og_UkLWZg9DAJ
delivery_method_ids: []
@@ -28370,8 +29174,8 @@ paths:
- id: int_UkLWZg9DAJ
name: Carrier
active: false
- created_at: '2026-08-16T18:08:58.983Z'
- updated_at: '2026-08-16T18:08:58.983Z'
+ created_at: '2026-08-16T19:27:05.828Z'
+ updated_at: '2026-08-16T19:27:05.828Z'
type: carrier
group: shipping
preferences:
@@ -28443,8 +29247,8 @@ paths:
id: int_UkLWZg9DAJ
name: Carrier
active: false
- created_at: '2026-08-16T18:08:59.071Z'
- updated_at: '2026-08-16T18:08:59.071Z'
+ created_at: '2026-08-16T19:27:05.926Z'
+ updated_at: '2026-08-16T19:27:05.926Z'
type: carrier
group: shipping
preferences:
@@ -28636,8 +29440,8 @@ paths:
- id: pt_UkLWZg9DAJ
name: T-Shirt
products_count: 0
- created_at: '2026-08-16T18:09:11.257Z'
- updated_at: '2026-08-16T18:09:11.257Z'
+ created_at: '2026-08-16T19:27:16.452Z'
+ updated_at: '2026-08-16T19:27:16.452Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -28712,8 +29516,8 @@ paths:
id: pt_gbHJdmfrXB
name: Hoodie
products_count: 0
- created_at: '2026-08-16T18:09:11.340Z'
- updated_at: '2026-08-16T18:09:11.340Z'
+ created_at: '2026-08-16T19:27:16.517Z'
+ updated_at: '2026-08-16T19:27:16.517Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -28813,8 +29617,8 @@ paths:
id: pt_UkLWZg9DAJ
name: T-Shirt
products_count: 0
- created_at: '2026-08-16T18:09:11.394Z'
- updated_at: '2026-08-16T18:09:11.394Z'
+ created_at: '2026-08-16T19:27:16.558Z'
+ updated_at: '2026-08-16T19:27:16.558Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -28867,8 +29671,8 @@ paths:
id: pt_UkLWZg9DAJ
name: Premium T-Shirt
products_count: 0
- created_at: '2026-08-16T18:09:11.459Z'
- updated_at: '2026-08-16T18:09:11.482Z'
+ created_at: '2026-08-16T19:27:16.624Z'
+ updated_at: '2026-08-16T19:27:16.643Z'
delivery_profile_id:
option_type_ids: []
category_ids: []
@@ -29079,8 +29883,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.347Z'
- updated_at: '2026-08-16T18:09:17.347Z'
+ created_at: '2026-08-16T19:27:21.649Z'
+ updated_at: '2026-08-16T19:27:21.649Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -29189,8 +29993,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.430Z'
- updated_at: '2026-08-16T18:09:17.430Z'
+ created_at: '2026-08-16T19:27:21.724Z'
+ updated_at: '2026-08-16T19:27:21.724Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -29327,8 +30131,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.491Z'
- updated_at: '2026-08-16T18:09:17.491Z'
+ created_at: '2026-08-16T19:27:21.757Z'
+ updated_at: '2026-08-16T19:27:21.757Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -29415,8 +30219,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.590Z'
- updated_at: '2026-08-16T18:09:17.612Z'
+ created_at: '2026-08-16T19:27:21.830Z'
+ updated_at: '2026-08-16T19:27:21.849Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -29446,8 +30250,8 @@ paths:
state_name:
label:
metadata: {}
- created_at: '2026-08-16T18:09:17.611Z'
- updated_at: '2026-08-16T18:09:17.611Z'
+ created_at: '2026-08-16T19:27:21.849Z'
+ updated_at: '2026-08-16T19:27:21.849Z'
customer_id:
schema:
"$ref": "#/components/schemas/Vendor"
@@ -29713,8 +30517,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.686Z'
- updated_at: '2026-08-16T18:09:17.715Z'
+ created_at: '2026-08-16T19:27:21.903Z'
+ updated_at: '2026-08-16T19:27:21.923Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -29810,8 +30614,8 @@ paths:
metadata: {}
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.730Z'
- updated_at: '2026-08-16T18:09:17.755Z'
+ created_at: '2026-08-16T19:27:21.936Z'
+ updated_at: '2026-08-16T19:27:21.955Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -29906,8 +30710,8 @@ paths:
suspension_reason: Counterfeit goods
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.807Z'
- updated_at: '2026-08-16T18:09:17.832Z'
+ created_at: '2026-08-16T19:27:21.994Z'
+ updated_at: '2026-08-16T19:27:22.013Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -29999,8 +30803,8 @@ paths:
rejection_reason: Incomplete paperwork
holiday_mode_until:
terms_accepted_at:
- created_at: '2026-08-16T18:09:17.850Z'
- updated_at: '2026-08-16T18:09:17.874Z'
+ created_at: '2026-08-16T19:27:22.025Z'
+ updated_at: '2026-08-16T19:27:22.052Z'
deleted_at:
minimum_payout_amount:
on_holiday: false
@@ -31250,6 +32054,162 @@ components:
- created_at
- updated_at
x-typelizer: true
+ CommissionLine:
+ type: object
+ properties:
+ id:
+ type: string
+ kind:
+ type: string
+ currency:
+ type: string
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ 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
+ vendor_id:
+ type: string
+ line_item_id:
+ type: string
+ nullable: true
+ fulfillment_id:
+ type: string
+ nullable: true
+ commission_rate_id:
+ type: string
+ nullable: true
+ vendor_name:
+ type: string
+ nullable: true
+ required:
+ - id
+ - kind
+ - currency
+ - created_at
+ - updated_at
+ - rate
+ - amount
+ - tax_amount
+ - total
+ - display_amount
+ - display_tax_amount
+ - display_total
+ - order_id
+ - vendor_id
+ - line_item_id
+ - fulfillment_id
+ - commission_rate_id
+ - vendor_name
+ x-typelizer: true
+ CommissionRate:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ code:
+ type: string
+ nullable: true
+ enabled:
+ type: boolean
+ priority:
+ type: number
+ kind:
+ type: string
+ currency:
+ type: string
+ nullable: true
+ include_tax:
+ type: boolean
+ include_shipping:
+ type: boolean
+ deleted_at:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ value:
+ type: string
+ min_amount:
+ type: string
+ nullable: true
+ max_amount:
+ type: string
+ nullable: true
+ commission_tax_rate:
+ type: string
+ nullable: true
+ rules:
+ type: array
+ items:
+ "$ref": "#/components/schemas/CommissionRule"
+ required:
+ - id
+ - name
+ - code
+ - enabled
+ - priority
+ - kind
+ - currency
+ - include_tax
+ - include_shipping
+ - deleted_at
+ - created_at
+ - updated_at
+ - value
+ - min_amount
+ - max_amount
+ - commission_tax_rate
+ - rules
+ x-typelizer: true
+ CommissionRule:
+ type: object
+ properties:
+ id:
+ type: string
+ subject_type:
+ type: string
+ nullable: true
+ created_at:
+ type: string
+ updated_at:
+ type: string
+ commission_rate_id:
+ type: string
+ subject_id:
+ type: string
+ nullable: true
+ subject_name:
+ type: string
+ nullable: true
+ required:
+ - id
+ - subject_type
+ - created_at
+ - updated_at
+ - commission_rate_id
+ - subject_id
+ - subject_name
+ x-typelizer: true
CompanyContact:
type: object
properties:
diff --git a/packages/admin-sdk/examples/commission_lines/list.ts b/packages/admin-sdk/examples/commission_lines/list.ts
new file mode 100644
index 0000000000..836cee74fa
--- /dev/null
+++ b/packages/admin-sdk/examples/commission_lines/list.ts
@@ -0,0 +1,15 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// `amount` is the fee and `tax_amount` is the VAT charged on that fee — two
+// separate supplies, which is why they are not folded together.
+const { data: commissionLines } = await client.commissionLines.list({ page: 1, limit: 25 })
+
+// endregion:example
+
+export { commissionLines }
diff --git a/packages/admin-sdk/examples/commission_rates/create.ts b/packages/admin-sdk/examples/commission_rates/create.ts
new file mode 100644
index 0000000000..36873d8118
--- /dev/null
+++ b/packages/admin-sdk/examples/commission_rates/create.ts
@@ -0,0 +1,21 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Charges this seller 12.5% of every sale, with VAT on the commission itself
+// left to your tax settings.
+const commissionRate = await client.commissionRates.create({
+ name: 'Audio sellers',
+ kind: 'percentage',
+ value: 12.5,
+ priority: 10,
+ rules: [{ subject_type: 'Spree::Vendor', subject_id: 'ven_a1b2c3' }],
+})
+
+// endregion:example
+
+export { commissionRate }
diff --git a/packages/admin-sdk/examples/commission_rates/delete.ts b/packages/admin-sdk/examples/commission_rates/delete.ts
new file mode 100644
index 0000000000..3dcab7af7b
--- /dev/null
+++ b/packages/admin-sdk/examples/commission_rates/delete.ts
@@ -0,0 +1,12 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Commission already charged is unaffected — the lines keep their own snapshot.
+await client.commissionRates.delete('comrt_a1b2c3')
+
+// endregion:example
diff --git a/packages/admin-sdk/examples/commission_rates/get.ts b/packages/admin-sdk/examples/commission_rates/get.ts
new file mode 100644
index 0000000000..deb6c1c0ec
--- /dev/null
+++ b/packages/admin-sdk/examples/commission_rates/get.ts
@@ -0,0 +1,13 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+const commissionRate = await client.commissionRates.get('comrt_a1b2c3')
+
+// endregion:example
+
+export { commissionRate }
diff --git a/packages/admin-sdk/examples/commission_rates/list.ts b/packages/admin-sdk/examples/commission_rates/list.ts
new file mode 100644
index 0000000000..af077d9058
--- /dev/null
+++ b/packages/admin-sdk/examples/commission_rates/list.ts
@@ -0,0 +1,15 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// Rates come back with their targeting attached. A rate holding no rules
+// applies to every sale.
+const { data: commissionRates } = await client.commissionRates.list({ page: 1, limit: 25 })
+
+// endregion:example
+
+export { commissionRates }
diff --git a/packages/admin-sdk/examples/commission_rates/update.ts b/packages/admin-sdk/examples/commission_rates/update.ts
new file mode 100644
index 0000000000..6e345efddc
--- /dev/null
+++ b/packages/admin-sdk/examples/commission_rates/update.ts
@@ -0,0 +1,17 @@
+import { createAdminClient } from '@spree/admin-sdk'
+
+const client = createAdminClient({
+ baseUrl: 'https://your-store.com',
+ secretKey: 'sk_xxx',
+})
+
+// region:example
+// `rules` is the rate's whole targeting — what you send replaces what it holds.
+const commissionRate = await client.commissionRates.update('comrt_a1b2c3', {
+ value: 15,
+ rules: [{ subject_type: 'Spree::Category', subject_id: 'ctg_d4e5f6' }],
+})
+
+// endregion:example
+
+export { commissionRate }
diff --git a/packages/admin-sdk/src/admin-client.ts b/packages/admin-sdk/src/admin-client.ts
index 60144e1026..79fb01a1b3 100644
--- a/packages/admin-sdk/src/admin-client.ts
+++ b/packages/admin-sdk/src/admin-client.ts
@@ -112,6 +112,9 @@ import type {
CollectionCreateParams,
CollectionProductRepositionParams,
CollectionUpdateParams,
+ CommissionRateCreateParams,
+ CommissionRateUpdateParams,
+ CommissionRuleSubjectType,
CompanyContactParams,
CompanyLocationParams,
CompanyParams,
@@ -238,6 +241,8 @@ import type {
Claim,
ClaimReason,
Collection,
+ CommissionLine,
+ CommissionRate,
Company,
CompanyContact,
CompanyLocation,
@@ -2403,6 +2408,89 @@ export class AdminClient {
this.request<Vendor>('PATCH', `/vendors/${id}/reject`, { ...options, body: params }),
}
+ // ============================================
+ // Commissions (what the marketplace charges its sellers)
+ // ============================================
+
+ /**
+ * CRUD for `Spree::CommissionRate`. Targeting rides the regular payload as
+ * `rules: [...]` — the whole editor saves in one round-trip, and the server
+ * replaces the rate's rules with exactly what it is sent.
+ */
+ readonly commissionRates = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<CommissionRate>> =>
+ this.request<PaginatedResponse<CommissionRate>>('GET', '/commission_rates', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<CommissionRate> =>
+ this.request<CommissionRate>('GET', `/commission_rates/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+
+ create: (
+ params: CommissionRateCreateParams,
+ options?: RequestOptions,
+ ): Promise<CommissionRate> =>
+ this.request<CommissionRate>('POST', '/commission_rates', { ...options, body: params }),
+
+ update: (
+ id: string,
+ params: CommissionRateUpdateParams,
+ options?: RequestOptions,
+ ): Promise<CommissionRate> =>
+ this.request<CommissionRate>('PATCH', `/commission_rates/${id}`, {
+ ...options,
+ body: params,
+ }),
+
+ delete: (id: string, options?: RequestOptions): Promise<void> =>
+ this.request<void>('DELETE', `/commission_rates/${id}`, options),
+
+ /** What a rule may target, so the picker isn't a hardcoded list. */
+ ruleSubjectTypes: (options?: RequestOptions): Promise<{ data: CommissionRuleSubjectType[] }> =>
+ this.request<{ data: CommissionRuleSubjectType[] }>(
+ 'GET',
+ '/commission_rates/rule_subject_types',
+ options,
+ ),
+ }
+
+ /**
+ * Read-only view of `Spree::CommissionLine` — what each sale actually earned
+ * the marketplace, frozen when the order was placed. There is no write path:
+ * correcting a charge is a reversal, not an edit.
+ */
+ readonly commissionLines = {
+ list: (
+ params?: ListParams & Record<string, unknown>,
+ options?: RequestOptions,
+ ): Promise<PaginatedResponse<CommissionLine>> =>
+ this.request<PaginatedResponse<CommissionLine>>('GET', '/commission_lines', {
+ ...options,
+ params: params ? transformListParams(params) : undefined,
+ }),
+
+ get: (
+ id: string,
+ params?: { expand?: string[] },
+ options?: RequestOptions,
+ ): Promise<CommissionLine> =>
+ this.request<CommissionLine>('GET', `/commission_lines/${id}`, {
+ ...options,
+ params: getParams(params),
+ }),
+ }
+
// ============================================
// Gift cards (admin-issued)
// ============================================
diff --git a/packages/admin-sdk/src/params.ts b/packages/admin-sdk/src/params.ts
index 92d338243f..c7f1b501c3 100644
--- a/packages/admin-sdk/src/params.ts
+++ b/packages/admin-sdk/src/params.ts
@@ -1417,6 +1417,67 @@ export interface VendorRejectParams {
reason?: string
}
+/**
+ * One targeting clause on a commission rate: the record it applies to.
+ *
+ * Rules are grouped by `subject_type` and matched AND across the groups, OR
+ * within one — so `[Cameras, Audio, VendorX]` reads "(Cameras OR Audio) AND
+ * VendorX", which is how a seller-and-category pairing is expressed.
+ *
+ * A clause with neither field is a global rule, and so is a rate with no rules
+ * at all: both match every sale.
+ */
+export interface CommissionRuleDraft {
+ /** `Spree::Product`, `Spree::Category` or `Spree::Vendor`. */
+ subject_type?: string | null
+ /** Prefixed id of the record being targeted. */
+ subject_id?: string | null
+}
+
+/** One entry from `commissionRates.ruleSubjectTypes()`. */
+export interface CommissionRuleSubjectType {
+ type: string
+ name: string
+}
+
+export interface CommissionRateCreateParams {
+ name: string
+ /** Optional operator-facing identifier; unique per store. */
+ code?: string | null
+ enabled?: boolean
+ /**
+ * Resolution order, walked highest first — the first matching rate wins.
+ * Precedence is yours to assign; there is no built-in ladder.
+ */
+ priority?: number
+ /** `percentage` charges a share of the sale; `fixed` charges a flat fee. */
+ kind: 'percentage' | 'fixed'
+ /** A percentage (e.g. `10` for 10%) or a flat amount, per `kind`. */
+ value: number
+ /** Required for a fixed rate, ignored for a percentage. */
+ currency?: string | null
+ /**
+ * Charge on the item's gross price rather than its net one. Off by default:
+ * in the EU the fee is a separate supply from the sale, so it is charged on
+ * the seller's net revenue and taxed on top.
+ */
+ include_tax?: boolean
+ /** Also charge commission on the seller's delivery revenue. */
+ include_shipping?: boolean
+ min_amount?: number | null
+ max_amount?: number | null
+ /**
+ * VAT on the commission itself, as a fraction (e.g. `0.21`). Leave null to
+ * let the store's tax engine answer for the seller's own jurisdiction.
+ */
+ commission_tax_rate?: number | null
+ /** The rate's full targeting; the server replaces what it holds with this. */
+ rules?: CommissionRuleDraft[]
+ metadata?: Record<string, unknown>
+}
+
+export type CommissionRateUpdateParams = Partial<CommissionRateCreateParams>
+
/**
* One entry in `preference_schema`, describing a single tunable knob on
* a STI subclass (payment provider, promotion action, promotion rule).
diff --git a/packages/admin-sdk/src/types/generated/CommissionLine.ts b/packages/admin-sdk/src/types/generated/CommissionLine.ts
new file mode 100644
index 0000000000..f994bc1615
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/CommissionLine.ts
@@ -0,0 +1,26 @@
+// Typelizer digest 016cf17cbfdff38a26074f5cd6e3cb1c
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface CommissionLine {
+ id: string;
+ kind: string;
+ currency: string;
+ created_at: string;
+ updated_at: string;
+ rate: string;
+ amount: string;
+ tax_amount: string;
+ total: string;
+ display_amount: string;
+ display_tax_amount: string;
+ display_total: string;
+ order_id: string;
+ vendor_id: string;
+ line_item_id: string | null;
+ fulfillment_id: string | null;
+ commission_rate_id: string | null;
+ vendor_name: string | null;
+}
+
+export default CommissionLine;
diff --git a/packages/admin-sdk/src/types/generated/CommissionRate.ts b/packages/admin-sdk/src/types/generated/CommissionRate.ts
new file mode 100644
index 0000000000..25be1acab5
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/CommissionRate.ts
@@ -0,0 +1,26 @@
+// Typelizer digest becc293771497cac1bc67f53d8703013
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+import type {CommissionRule} from '@/types'
+
+interface CommissionRate {
+ id: string;
+ name: string;
+ code: string | null;
+ enabled: boolean;
+ priority: number;
+ kind: string;
+ currency: string | null;
+ include_tax: boolean;
+ include_shipping: boolean;
+ deleted_at: string | null;
+ created_at: string;
+ updated_at: string;
+ value: string;
+ min_amount: string | null;
+ max_amount: string | null;
+ commission_tax_rate: string | null;
+ rules: Array<CommissionRule>;
+}
+
+export default CommissionRate;
diff --git a/packages/admin-sdk/src/types/generated/CommissionRule.ts b/packages/admin-sdk/src/types/generated/CommissionRule.ts
new file mode 100644
index 0000000000..3ddaf82b97
--- /dev/null
+++ b/packages/admin-sdk/src/types/generated/CommissionRule.ts
@@ -0,0 +1,15 @@
+// Typelizer digest bd8f0b3e34a466de13f987f6439b2cc4
+//
+// DO NOT MODIFY: This file was automatically generated by Typelizer.
+
+interface CommissionRule {
+ id: string;
+ subject_type: string | null;
+ created_at: string;
+ updated_at: string;
+ commission_rate_id: string;
+ subject_id: string | null;
+ subject_name: string | null;
+}
+
+export default CommissionRule;
diff --git a/packages/admin-sdk/src/types/generated/index.ts b/packages/admin-sdk/src/types/generated/index.ts
index 9baeb43e3f..2bc08a8a68 100644
--- a/packages/admin-sdk/src/types/generated/index.ts
+++ b/packages/admin-sdk/src/types/generated/index.ts
@@ -1,4 +1,4 @@
-// Typelizer digest e219697ade470609d92dd9ee61d32bdd
+// Typelizer digest fce9db0039332defec101f07c2aa4c2f
//
// DO NOT MODIFY: This file was automatically generated by Typelizer.
export type { default as Address } from './Address'
@@ -14,6 +14,9 @@ export type { default as ClaimReason } from './ClaimReason'
export type { default as Claim } from './Claim'
export type { default as CollectionRule } from './CollectionRule'
export type { default as Collection } from './Collection'
+export type { default as CommissionLine } from './CommissionLine'
+export type { default as CommissionRate } from './CommissionRate'
+export type { default as CommissionRule } from './CommissionRule'
export type { default as CompanyContact } from './CompanyContact'
export type { default as CompanyLocation } from './CompanyLocation'
export type { default as Company } from './Company'
diff --git a/packages/admin-sdk/src/types/index.ts b/packages/admin-sdk/src/types/index.ts
index 7589e0a620..92f043d19f 100644
--- a/packages/admin-sdk/src/types/index.ts
+++ b/packages/admin-sdk/src/types/index.ts
@@ -27,6 +27,9 @@ export type { default as ClaimLineItem } from './generated/ClaimLineItem'
export type { default as ClaimReason } from './generated/ClaimReason'
export type { default as Collection } from './generated/Collection'
export type { default as CollectionRule } from './generated/CollectionRule'
+export type { default as CommissionLine } from './generated/CommissionLine'
+export type { default as CommissionRate } from './generated/CommissionRate'
+export type { default as CommissionRule } from './generated/CommissionRule'
export type { default as Company } from './generated/Company'
export type { default as CompanyContact } from './generated/CompanyContact'
export type { default as CompanyLocation } from './generated/CompanyLocation'
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index b5d7a9037f..62bcab8bde 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/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 vendor 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/vendors":{"get":{"summary":"List vendors","tags":["Vendors"],"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 vendor who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"vendors found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Vendor"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The vendor 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_vendors` (for API-key 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":"vendor created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"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":["vendor","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/vendors/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single vendor, including its settlement and tax configuration.\n\n**Required scope:** `read_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"404":{"description":"vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the vendor'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_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"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 vendor'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 vendor'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 vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the vendor. 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_vendors` (for API-key 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":"vendor deleted"}}}},"/api/v3/admin/vendors/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the vendor's own team and moves the vendor to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the vendor panel.\n\n`role_id` must name a role this vendor owns; omit it for the vendor'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_vendors` (for API-key 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/Vendor"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/vendors/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the vendor 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_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"422":{"description":"vendor cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/vendors/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading vendor from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nvendor already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/vendors/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A vendor already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}}},"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},"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"},"vendor_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},"vendor":{"$ref":"#/components/schemas/Vendor"},"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","vendor_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},"vendor_id":{"type":"string","nullable":true},"vendor":{"$ref":"#/components/schemas/Vendor"},"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},"vendor_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","vendor_id","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","vendor_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},"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},"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"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","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"],"x-typelizer":true},"Vendor":{"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},"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[vendor_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 tried in `priority` order, highest first, and the first one\nwhose targeting matches the sale wins. A rate carrying no rules matches\neverything, which is how a marketplace expresses a single default\nwithout configuring anything.\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., `-priority`).","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. Rules are grouped by\n`subject_type` and matched AND across the groups, OR within one — so\n`[Cameras, Audio, VendorX]` reads \"(Cameras OR Audio) AND VendorX\",\nwhich is how a seller-and-category pairing is expressed. Send no rules\nto charge every sale.\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"},"priority":{"type":"integer","description":"Tried highest first; the first matching rate wins."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"currency":{"type":"string","nullable":true,"description":"Required for a fixed rate, ignored for a percentage."},"include_tax":{"type":"boolean","description":"Charge on the gross price. Off is the EU rule: charge on the seller's net revenue."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true},"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":{"subject_type":{"type":"string","enum":["Spree::Product","Spree::Category","Spree::Vendor"]},"subject_id":{"type":"string"}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_subject_types":{"get":{"summary":"List what a commission rule may target","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The subject types a rule may name, so a client can build its picker\nwithout hardcoding a list core owns.\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"}}}}}}}}}}}},"/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"},"priority":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"subject_type":{"type":"string"},"subject_id":{"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 vendor 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/vendors":{"get":{"summary":"List vendors","tags":["Vendors"],"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 vendor who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"vendors found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Vendor"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The vendor 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_vendors` (for API-key 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":"vendor created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"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":["vendor","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/vendors/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single vendor, including its settlement and tax configuration.\n\n**Required scope:** `read_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"404":{"description":"vendor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the vendor'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_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"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 vendor'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 vendor'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 vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the vendor. 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_vendors` (for API-key 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":"vendor deleted"}}}},"/api/v3/admin/vendors/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the vendor's own team and moves the vendor to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the vendor panel.\n\n`role_id` must name a role this vendor owns; omit it for the vendor'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_vendors` (for API-key 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/Vendor"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/vendors/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the vendor 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_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}},"422":{"description":"vendor cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/vendors/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading vendor from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nvendor already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/vendors/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Vendor prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a vendor","tags":["Vendors"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A vendor already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_vendors` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"vendor rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Vendor"}}}}},"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"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"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"},"vendor_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"vendor_name":{"type":"string","nullable":true}},"required":["id","kind","currency","created_at","updated_at","rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","vendor_id","line_item_id","fulfillment_id","commission_rate_id","vendor_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"priority":{"type":"number"},"kind":{"type":"string"},"currency":{"type":"string","nullable":true},"include_tax":{"type":"boolean"},"include_shipping":{"type":"boolean"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true},"commission_tax_rate":{"type":"string","nullable":true},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","priority","kind","currency","include_tax","include_shipping","deleted_at","created_at","updated_at","value","min_amount","max_amount","commission_tax_rate","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"subject_type":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"commission_rate_id":{"type":"string"},"subject_id":{"type":"string","nullable":true},"subject_name":{"type":"string","nullable":true}},"required":["id","subject_type","created_at","updated_at","commission_rate_id","subject_id","subject_name"],"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"},"vendor_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},"vendor":{"$ref":"#/components/schemas/Vendor"},"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","vendor_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},"vendor_id":{"type":"string","nullable":true},"vendor":{"$ref":"#/components/schemas/Vendor"},"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},"vendor_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","vendor_id","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","vendor_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},"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},"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"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_items":{"type":"array","items":{"$ref":"#/components/schemas/StockItem"}}},"required":["id","product_id","sku","options_text","track_inventory","media_count","preorder_ships_at","thumbnail_url","purchasable","in_stock","backorderable","preorder","weight","height","width","depth","price","original_price","option_values","metadata","position","cost_price","cost_currency","barcode","weight_unit","dimensions_unit","backorder_limit","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"],"x-typelizer":true},"Vendor":{"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},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
diff --git a/packages/cli/src/generated/resource-paths.json b/packages/cli/src/generated/resource-paths.json
index 69d890f7d2..c0ae1673a0 100644
--- a/packages/cli/src/generated/resource-paths.json
+++ b/packages/cli/src/generated/resource-paths.json
@@ -1 +1 @@
-["/admin_users","/allowed_origins","/api_keys","/auth","/categories","/channels","/collection_rules","/collections","/companies","/company_contacts","/company_locations","/custom_field_definitions","/customer_groups","/customers","/delivery_methods","/delivery_profiles","/delivery_zones","/exports","/gift_card_batches","/gift_cards","/imports","/integrations","/invitations","/locales","/markets","/me","/option_types","/order_routing_rules","/orders","/payment_methods","/permissions","/price_lists","/prices","/product_types","/products","/promotion_actions","/promotion_rules","/promotions","/roles","/stock_locations","/store","/store_credit_categories","/tags","/tax_rates","/translatable_resources","/translations","/vendors","/webhook_endpoints"]
\ No newline at end of file
+["/admin_users","/allowed_origins","/api_keys","/auth","/categories","/channels","/collection_rules","/collections","/commission_lines","/commission_rates","/companies","/company_contacts","/company_locations","/custom_field_definitions","/customer_groups","/customers","/delivery_methods","/delivery_profiles","/delivery_zones","/exports","/gift_card_batches","/gift_cards","/imports","/integrations","/invitations","/locales","/markets","/me","/option_types","/order_routing_rules","/orders","/payment_methods","/permissions","/price_lists","/prices","/product_types","/products","/promotion_actions","/promotion_rules","/promotions","/roles","/stock_locations","/store","/store_credit_categories","/tags","/tax_rates","/translatable_resources","/translations","/vendors","/webhook_endpoints"]
\ No newline at end of file
diff --git a/packages/dashboard-core/src/lib/permissions.ts b/packages/dashboard-core/src/lib/permissions.ts
index d7c06c7430..e2bef77885 100644
--- a/packages/dashboard-core/src/lib/permissions.ts
+++ b/packages/dashboard-core/src/lib/permissions.ts
@@ -59,6 +59,9 @@ export const Subject = {
WebhookDelivery: 'Spree::WebhookDelivery',
Wishlist: 'Spree::Wishlist',
Vendor: 'Spree::Vendor',
+ CommissionRate: 'Spree::CommissionRate',
+ CommissionRule: 'Spree::CommissionRule',
+ CommissionLine: 'Spree::CommissionLine',
} as const
export type SubjectName = (typeof Subject)[keyof typeof Subject] | string
diff --git a/packages/dashboard-core/src/locales/ar.json b/packages/dashboard-core/src/locales/ar.json
index 307a20db96..60ea28e6cc 100644
--- a/packages/dashboard-core/src/locales/ar.json
+++ b/packages/dashboard-core/src/locales/ar.json
@@ -368,6 +368,9 @@
},
"contact_email": {
"label": "البريد الإلكتروني للتواصل"
+ },
+ "enabled": {
+ "label": "مُفعّل"
}
},
"components": {
diff --git a/packages/dashboard-core/src/locales/de.json b/packages/dashboard-core/src/locales/de.json
index 1d5b73d5c9..041957f782 100644
--- a/packages/dashboard-core/src/locales/de.json
+++ b/packages/dashboard-core/src/locales/de.json
@@ -368,6 +368,9 @@
},
"contact_email": {
"label": "Kontakt-E-Mail"
+ },
+ "enabled": {
+ "label": "Aktiviert"
}
},
"components": {
diff --git a/packages/dashboard-core/src/locales/en.json b/packages/dashboard-core/src/locales/en.json
index baf5bbdcf6..5716f6ee50 100644
--- a/packages/dashboard-core/src/locales/en.json
+++ b/packages/dashboard-core/src/locales/en.json
@@ -368,6 +368,9 @@
},
"contact_email": {
"label": "Contact email"
+ },
+ "enabled": {
+ "label": "Enabled"
}
},
"components": {
diff --git a/packages/dashboard-core/src/locales/fr.json b/packages/dashboard-core/src/locales/fr.json
index 5c457308d0..016580c37e 100644
--- a/packages/dashboard-core/src/locales/fr.json
+++ b/packages/dashboard-core/src/locales/fr.json
@@ -368,6 +368,9 @@
},
"contact_email": {
"label": "E-mail de contact"
+ },
+ "enabled": {
+ "label": "Activé"
}
},
"components": {
diff --git a/packages/dashboard-core/src/locales/pl.json b/packages/dashboard-core/src/locales/pl.json
index 7bbe3a0873..87018d3568 100644
--- a/packages/dashboard-core/src/locales/pl.json
+++ b/packages/dashboard-core/src/locales/pl.json
@@ -368,6 +368,9 @@
},
"contact_email": {
"label": "E-mail kontaktowy"
+ },
+ "enabled": {
+ "label": "Włączone"
}
},
"components": {
diff --git a/packages/dashboard-core/src/locales/zh-CN.json b/packages/dashboard-core/src/locales/zh-CN.json
index de681b51ae..0a1cf2169f 100644
--- a/packages/dashboard-core/src/locales/zh-CN.json
+++ b/packages/dashboard-core/src/locales/zh-CN.json
@@ -368,6 +368,9 @@
},
"contact_email": {
"label": "联系邮箱"
+ },
+ "enabled": {
+ "label": "已启用"
}
},
"components": {
diff --git a/packages/dashboard/src/components/spree/commission-rule-subjects.ts b/packages/dashboard/src/components/spree/commission-rule-subjects.ts
new file mode 100644
index 0000000000..985d63266b
--- /dev/null
+++ b/packages/dashboard/src/components/spree/commission-rule-subjects.ts
@@ -0,0 +1,57 @@
+import type { ResourceFilterConfig } from '@spree/dashboard-core'
+import { categoryAutocompleteProps } from '../../hooks/use-categories'
+import { productAutocompleteProps } from '../../hooks/use-products'
+import { vendorAutocompleteProps } from '../../hooks/use-vendors'
+
+/**
+ * How to pick a record for each kind of commission-rule target.
+ *
+ * A registry rather than a branch in the form, because the server owns the
+ * list of targetable types (`commissionRates.ruleSubjectTypes()`) and may grow
+ * it — a channel, a market. Adding one here is then the whole client-side
+ * change, and a type nobody has registered yet still renders as itself rather
+ * than silently disappearing.
+ *
+ * Each entry is the shared autocomplete config the rest of the dashboard
+ * already uses for that resource, so a category picked here shows its full
+ * path exactly as it does on a product.
+ */
+/**
+ * Everything a `<ResourceMultiAutocomplete>` needs to search one resource,
+ * minus the value/onChange the form supplies — the shape the shared
+ * `*AutocompleteProps` helpers already return.
+ *
+ * The record type is `any` for the same reason the table registry's
+ * `filterResource` is: pickers for different resources cannot be stored under
+ * one key otherwise, since each one's `getOptionLabel` accepts only its own
+ * record.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type CommissionRuleSubjectPicker = (queryKey: string) => ResourceFilterConfig<any>
+
+const PICKERS: Record<string, CommissionRuleSubjectPicker> = {
+ 'Spree::Vendor': vendorAutocompleteProps,
+ 'Spree::Product': productAutocompleteProps,
+ 'Spree::Category': categoryAutocompleteProps,
+}
+
+/**
+ * The picker for a subject type, or undefined when nothing has registered one.
+ *
+ * @param subjectType e.g. `Spree::Vendor`
+ */
+export function commissionRuleSubjectPicker(
+ subjectType: string,
+): CommissionRuleSubjectPicker | undefined {
+ return PICKERS[subjectType]
+}
+
+/**
+ * Registers a picker for a subject type an extension has added to the catalog.
+ */
+export function registerCommissionRuleSubjectPicker(
+ subjectType: string,
+ picker: CommissionRuleSubjectPicker,
+): void {
+ PICKERS[subjectType] = picker
+}
diff --git a/packages/dashboard/src/hooks/use-commission-rates.ts b/packages/dashboard/src/hooks/use-commission-rates.ts
new file mode 100644
index 0000000000..e389638b17
--- /dev/null
+++ b/packages/dashboard/src/hooks/use-commission-rates.ts
@@ -0,0 +1,66 @@
+import type {
+ CommissionRate,
+ CommissionRateCreateParams,
+ CommissionRateUpdateParams,
+} from '@spree/admin-sdk'
+import {
+ adminClient,
+ useResourceKey,
+ useResourceKeyBuilder,
+ useResourceMutation,
+} from '@spree/dashboard-core'
+import { useQuery, useQueryClient } from '@tanstack/react-query'
+import i18n from 'i18next'
+
+export function useCommissionRate(id: string | undefined) {
+ return useQuery({
+ queryKey: useResourceKey('commission-rates', id ?? 'noop'),
+ queryFn: () => adminClient.commissionRates.get(id as string),
+ enabled: !!id,
+ })
+}
+
+/**
+ * What a rule may target. Store-independent and effectively static, so it is
+ * fetched once and never refetched.
+ */
+export function useCommissionRuleSubjectTypes() {
+ return useQuery({
+ queryKey: ['commission-rule-subject-types'],
+ queryFn: () => adminClient.commissionRates.ruleSubjectTypes(),
+ staleTime: Number.POSITIVE_INFINITY,
+ })
+}
+
+export function useCreateCommissionRate() {
+ return useResourceMutation<CommissionRate, Error, CommissionRateCreateParams>({
+ mutationFn: (params) => adminClient.commissionRates.create(params),
+ invalidate: [['commission-rates']],
+ successMessage: i18n.t('admin.commission_rates.messages.created'),
+ errorMessage: i18n.t('admin.errors.failed_to_create'),
+ })
+}
+
+export function useUpdateCommissionRate(id: string) {
+ return useResourceMutation<CommissionRate, Error, CommissionRateUpdateParams>({
+ mutationFn: (params) => adminClient.commissionRates.update(id, params),
+ invalidate: [['commission-rates'], ['commission-rates', id]],
+ successMessage: i18n.t('admin.commission_rates.messages.updated'),
+ errorMessage: i18n.t('admin.errors.failed_to_update'),
+ })
+}
+
+export function useDeleteCommissionRate() {
+ const queryClient = useQueryClient()
+ const buildKey = useResourceKeyBuilder()
+
+ return useResourceMutation<void, Error, string>({
+ mutationFn: (id) => adminClient.commissionRates.delete(id),
+ invalidate: [['commission-rates']],
+ successMessage: i18n.t('admin.commission_rates.messages.deleted'),
+ errorMessage: i18n.t('admin.errors.failed_to_delete'),
+ onSuccess: (_data, id) => {
+ queryClient.removeQueries({ queryKey: buildKey('commission-rates', id) })
+ },
+ })
+}
diff --git a/packages/dashboard/src/locales/ar.json b/packages/dashboard/src/locales/ar.json
index d0dae9dd5b..53ca680fd8 100644
--- a/packages/dashboard/src/locales/ar.json
+++ b/packages/dashboard/src/locales/ar.json
@@ -1663,6 +1663,58 @@
"placeholder": "اختر تاريخاً",
"help": "يبقى الكتالوج ظاهراً لكن لا يمكن الشراء حتى ذلك الحين."
}
+ },
+ "commission_rate": {
+ "name": {
+ "placeholder": "العمولة القياسية"
+ },
+ "code": {
+ "label": "الرمز",
+ "placeholder": "standard",
+ "help": "معرّفك الخاص لهذه النسبة."
+ },
+ "kind": {
+ "label": "الرسوم",
+ "options": {
+ "percentage": "نسبة من البيع",
+ "fixed": "رسوم ثابتة"
+ }
+ },
+ "value": {
+ "label": "المبلغ",
+ "help_percentage": "النسبة المئوية من البيع التي تُحتسب على البائع.",
+ "help_fixed": "رسوم ثابتة لكل عملية بيع، بالعملة أدناه."
+ },
+ "priority": {
+ "label": "الأولوية",
+ "help": "تُجرَّب النسب من الأعلى أولًا، ويفوز أول تطابق."
+ },
+ "rules": {
+ "label": "ينطبق على",
+ "help": "الاختيارات داخل حقل واحد بدائل؛ وكل حقل تملؤه يجب أن يتطابق. اترك الجميع فارغًا لاحتساب كل عملية بيع."
+ },
+ "min_amount": {
+ "label": "الحد الأدنى"
+ },
+ "max_amount": {
+ "label": "الحد الأقصى"
+ },
+ "commission_tax_rate": {
+ "label": "ضريبة على العمولة (%)",
+ "placeholder": "من إعدادات الضرائب",
+ "help": "ضريبة القيمة المضافة على العمولة نفسها، كخدمة منفصلة للبائع. اتركه فارغًا لاستخدام إعدادات الضرائب."
+ },
+ "include_shipping": {
+ "label": "احتساب على التوصيل",
+ "help": "احتساب العمولة أيضًا على إيرادات التوصيل لدى البائع."
+ },
+ "include_tax": {
+ "label": "الاحتساب على السعر الإجمالي",
+ "help": "الاحتساب على السعر شاملًا ضريبة العميل. الإيقاف هو قاعدة الاتحاد الأوروبي: على صافي إيراد البائع."
+ },
+ "enabled": {
+ "help": "تُتجاهل النسب المعطّلة عند الاحتساب."
+ }
}
},
"delivery_profiles": {
@@ -3034,6 +3086,10 @@
"tax_rates": {
"add_sheet_title": "نسبة ضريبة جديدة",
"edit_sheet_title": "تعديل نسبة الضريبة"
+ },
+ "commission_rates": {
+ "add_sheet_title": "إضافة نسبة عمولة",
+ "edit_sheet_title": "تعديل نسبة العمولة"
}
},
"staff": {
@@ -3762,7 +3818,8 @@
"store": "المتجر",
"tax_categories": "فئات الضريبة",
"tax_rates": "نسب الضريبة",
- "webhooks": "Webhooks"
+ "webhooks": "Webhooks",
+ "commission_rates": "نسب العمولة"
}
},
"setup": {
@@ -4240,6 +4297,25 @@
"placeholder": "ابحث عن بائعين",
"empty": "لم يُعثر على بائعين"
}
+ },
+ "commission_rates": {
+ "add_cta": "إضافة نسبة عمولة",
+ "applies_to_everything": "كل عملية بيع",
+ "create_description": "حدّد ما يتقاضاه السوق من البائعين، وعلى أي مبيعات ينطبق.",
+ "create_label": "إنشاء نسبة العمولة",
+ "delete_confirm": {
+ "message": "سيتم حذف {{name}}. العمولات المحتسبة سابقًا لن تتأثر.",
+ "title": "حذف نسبة العمولة؟"
+ },
+ "edit_description": "حدّث الرسوم وحدودها والمبيعات التي تنطبق عليها.",
+ "empty": "لا توجد نسب عمولة بعد",
+ "messages": {
+ "created": "تم إنشاء نسبة العمولة",
+ "deleted": "تم حذف نسبة العمولة",
+ "updated": "تم تحديث نسبة العمولة"
+ },
+ "search_placeholder": "البحث بالاسم…",
+ "rule_picker_unavailable": "لا يتضمن هذا الإصدار أداة اختيار لهذا النوع."
}
}
}
diff --git a/packages/dashboard/src/locales/de.json b/packages/dashboard/src/locales/de.json
index 2a5311b427..b5e9527830 100644
--- a/packages/dashboard/src/locales/de.json
+++ b/packages/dashboard/src/locales/de.json
@@ -1652,6 +1652,58 @@
"placeholder": "Datum wählen",
"help": "Der Katalog bleibt sichtbar, es kann bis dahin aber nichts gekauft werden."
}
+ },
+ "commission_rate": {
+ "name": {
+ "placeholder": "Standardprovision"
+ },
+ "code": {
+ "label": "Code",
+ "placeholder": "standard",
+ "help": "Ihre eigene Kennung für diesen Satz."
+ },
+ "kind": {
+ "label": "Gebühr",
+ "options": {
+ "percentage": "Prozent vom Verkauf",
+ "fixed": "Pauschale"
+ }
+ },
+ "value": {
+ "label": "Betrag",
+ "help_percentage": "Prozentsatz des Verkaufs, der dem Verkäufer berechnet wird.",
+ "help_fixed": "Pauschale pro Verkauf, in der Währung unten."
+ },
+ "priority": {
+ "label": "Priorität",
+ "help": "Sätze werden von hoch nach niedrig geprüft; der erste Treffer gilt."
+ },
+ "rules": {
+ "label": "Gilt für",
+ "help": "Einträge in einem Feld sind Alternativen; jedes ausgefüllte Feld muss zutreffen. Alle leer lassen, um jeden Verkauf zu berechnen."
+ },
+ "min_amount": {
+ "label": "Minimum"
+ },
+ "max_amount": {
+ "label": "Maximum"
+ },
+ "commission_tax_rate": {
+ "label": "Steuer auf die Provision (%)",
+ "placeholder": "Aus Ihren Steuereinstellungen",
+ "help": "Umsatzsteuer auf die Provision selbst, als eigene Leistung an den Verkäufer. Leer lassen, um Ihre Steuereinstellungen zu verwenden."
+ },
+ "include_shipping": {
+ "label": "Auf Versand berechnen",
+ "help": "Provision auch auf die Versanderlöse des Verkäufers berechnen."
+ },
+ "include_tax": {
+ "label": "Auf den Bruttopreis berechnen",
+ "help": "Auf den Preis inklusive Kundensteuer berechnen. Aus entspricht der EU-Regel: auf den Nettoerlös des Verkäufers."
+ },
+ "enabled": {
+ "help": "Deaktivierte Sätze werden bei der Berechnung übersprungen."
+ }
}
},
"delivery_profiles": {
@@ -3024,6 +3076,10 @@
"tax_rates": {
"add_sheet_title": "Neuer Steuersatz",
"edit_sheet_title": "Steuersatz bearbeiten"
+ },
+ "commission_rates": {
+ "add_sheet_title": "Provisionssatz hinzufügen",
+ "edit_sheet_title": "Provisionssatz bearbeiten"
}
},
"staff": {
@@ -3746,7 +3802,8 @@
"store": "Shop",
"tax_categories": "Steuerkategorien",
"tax_rates": "Steuersätze",
- "webhooks": "Webhooks"
+ "webhooks": "Webhooks",
+ "commission_rates": "Provisionssätze"
}
},
"setup": {
@@ -4220,6 +4277,25 @@
"placeholder": "Verkäufer suchen",
"empty": "Keine Verkäufer gefunden"
}
+ },
+ "commission_rates": {
+ "add_cta": "Provisionssatz hinzufügen",
+ "applies_to_everything": "Jeder Verkauf",
+ "create_description": "Legen Sie fest, was der Marktplatz Verkäufern berechnet und für welche Verkäufe das gilt.",
+ "create_label": "Provisionssatz erstellen",
+ "delete_confirm": {
+ "message": "{{name}} wird entfernt. Bereits berechnete Provisionen bleiben unverändert.",
+ "title": "Provisionssatz löschen?"
+ },
+ "edit_description": "Gebühr, Grenzen und betroffene Verkäufe aktualisieren.",
+ "empty": "Noch keine Provisionssätze",
+ "messages": {
+ "created": "Provisionssatz erstellt",
+ "deleted": "Provisionssatz gelöscht",
+ "updated": "Provisionssatz aktualisiert"
+ },
+ "search_placeholder": "Nach Namen suchen…",
+ "rule_picker_unavailable": "Dieser Build hat keine Auswahl für diesen Zieltyp."
}
}
}
diff --git a/packages/dashboard/src/locales/en.json b/packages/dashboard/src/locales/en.json
index e2c35f6715..a7751f1d39 100644
--- a/packages/dashboard/src/locales/en.json
+++ b/packages/dashboard/src/locales/en.json
@@ -1652,6 +1652,58 @@
"placeholder": "Pick a date",
"help": "The catalog stays visible but nothing can be bought until then."
}
+ },
+ "commission_rate": {
+ "name": {
+ "placeholder": "Standard commission"
+ },
+ "code": {
+ "label": "Code",
+ "placeholder": "standard",
+ "help": "Your own identifier for this rate."
+ },
+ "kind": {
+ "label": "Charge",
+ "options": {
+ "percentage": "Percentage of the sale",
+ "fixed": "Flat fee"
+ }
+ },
+ "value": {
+ "label": "Amount",
+ "help_percentage": "Percent of the sale charged to the seller.",
+ "help_fixed": "Flat fee charged per sale, in the currency below."
+ },
+ "priority": {
+ "label": "Priority",
+ "help": "Rates are tried highest first, and the first match wins."
+ },
+ "rules": {
+ "label": "Applies to",
+ "help": "Picks within one box are alternatives; every box you fill must match. Leave all empty to charge every sale."
+ },
+ "min_amount": {
+ "label": "Minimum"
+ },
+ "max_amount": {
+ "label": "Maximum"
+ },
+ "commission_tax_rate": {
+ "label": "Tax on commission (%)",
+ "placeholder": "From your tax settings",
+ "help": "VAT charged on the commission itself, as a separate supply to the seller. Leave empty to use your tax settings."
+ },
+ "include_shipping": {
+ "label": "Charge on delivery",
+ "help": "Also charge commission on the seller's delivery revenue."
+ },
+ "include_tax": {
+ "label": "Charge on the gross price",
+ "help": "Charge on the price including the customer's VAT. Off is the EU rule: charge on the seller's net revenue."
+ },
+ "enabled": {
+ "help": "Disabled rates are skipped when charging a sale."
+ }
}
},
"delivery_profiles": {
@@ -3024,6 +3076,10 @@
"tax_rates": {
"add_sheet_title": "New tax rate",
"edit_sheet_title": "Edit tax rate"
+ },
+ "commission_rates": {
+ "add_sheet_title": "Add commission rate",
+ "edit_sheet_title": "Edit commission rate"
}
},
"staff": {
@@ -3746,7 +3802,8 @@
"store": "Store",
"tax_categories": "Tax categories",
"tax_rates": "Tax rates",
- "webhooks": "Webhooks"
+ "webhooks": "Webhooks",
+ "commission_rates": "Commission rates"
}
},
"setup": {
@@ -4220,6 +4277,25 @@
"placeholder": "Search vendors",
"empty": "No vendors found"
}
+ },
+ "commission_rates": {
+ "add_cta": "Add commission rate",
+ "applies_to_everything": "Every sale",
+ "create_description": "Set what the marketplace charges sellers, and which sales it applies to.",
+ "create_label": "Create commission rate",
+ "delete_confirm": {
+ "message": "{{name}} will be removed. Commission already charged is unaffected.",
+ "title": "Delete commission rate?"
+ },
+ "edit_description": "Update the charge, its limits, and which sales it applies to.",
+ "empty": "No commission rates yet",
+ "messages": {
+ "created": "Commission rate created",
+ "deleted": "Commission rate deleted",
+ "updated": "Commission rate updated"
+ },
+ "search_placeholder": "Search by name…",
+ "rule_picker_unavailable": "This build has no picker for this target type."
}
}
}
diff --git a/packages/dashboard/src/locales/fr.json b/packages/dashboard/src/locales/fr.json
index d674c9ca8b..63dc9d69d7 100644
--- a/packages/dashboard/src/locales/fr.json
+++ b/packages/dashboard/src/locales/fr.json
@@ -1652,6 +1652,58 @@
"placeholder": "Choisir une date",
"help": "Le catalogue reste visible mais rien ne peut être acheté jusque-là."
}
+ },
+ "commission_rate": {
+ "name": {
+ "placeholder": "Commission standard"
+ },
+ "code": {
+ "label": "Code",
+ "placeholder": "standard",
+ "help": "Votre propre identifiant pour ce taux."
+ },
+ "kind": {
+ "label": "Frais",
+ "options": {
+ "percentage": "Pourcentage de la vente",
+ "fixed": "Montant fixe"
+ }
+ },
+ "value": {
+ "label": "Montant",
+ "help_percentage": "Pourcentage de la vente facturé au vendeur.",
+ "help_fixed": "Montant fixe par vente, dans la devise ci-dessous."
+ },
+ "priority": {
+ "label": "Priorité",
+ "help": "Les taux sont testés du plus élevé au plus bas ; le premier correspondant gagne."
+ },
+ "rules": {
+ "label": "S'applique à",
+ "help": "Les choix d'un même champ sont des alternatives ; chaque champ rempli doit correspondre. Laissez tout vide pour facturer chaque vente."
+ },
+ "min_amount": {
+ "label": "Minimum"
+ },
+ "max_amount": {
+ "label": "Maximum"
+ },
+ "commission_tax_rate": {
+ "label": "Taxe sur la commission (%)",
+ "placeholder": "Selon vos réglages de taxes",
+ "help": "TVA sur la commission elle-même, en tant que prestation distincte au vendeur. Laissez vide pour utiliser vos réglages de taxes."
+ },
+ "include_shipping": {
+ "label": "Facturer sur la livraison",
+ "help": "Facturer aussi la commission sur les revenus de livraison du vendeur."
+ },
+ "include_tax": {
+ "label": "Facturer sur le prix TTC",
+ "help": "Facturer sur le prix incluant la TVA du client. Désactivé correspond à la règle européenne : sur le revenu net du vendeur."
+ },
+ "enabled": {
+ "help": "Les taux désactivés sont ignorés lors de la facturation."
+ }
}
},
"delivery_profiles": {
@@ -3024,6 +3076,10 @@
"tax_rates": {
"add_sheet_title": "Nouveau taux de taxe",
"edit_sheet_title": "Modifier le taux de taxe"
+ },
+ "commission_rates": {
+ "add_sheet_title": "Ajouter un taux de commission",
+ "edit_sheet_title": "Modifier le taux de commission"
}
},
"staff": {
@@ -3746,7 +3802,8 @@
"store": "Boutique",
"tax_categories": "Catégories de taxe",
"tax_rates": "Taux de taxe",
- "webhooks": "Webhooks"
+ "webhooks": "Webhooks",
+ "commission_rates": "Taux de commission"
}
},
"setup": {
@@ -4220,6 +4277,25 @@
"placeholder": "Rechercher des vendeurs",
"empty": "Aucun vendeur trouvé"
}
+ },
+ "commission_rates": {
+ "add_cta": "Ajouter un taux de commission",
+ "applies_to_everything": "Toutes les ventes",
+ "create_description": "Définissez ce que la place de marché facture aux vendeurs, et les ventes concernées.",
+ "create_label": "Créer le taux de commission",
+ "delete_confirm": {
+ "message": "{{name}} sera supprimé. Les commissions déjà facturées ne changent pas.",
+ "title": "Supprimer le taux de commission ?"
+ },
+ "edit_description": "Modifiez les frais, leurs limites et les ventes concernées.",
+ "empty": "Aucun taux de commission",
+ "messages": {
+ "created": "Taux de commission créé",
+ "deleted": "Taux de commission supprimé",
+ "updated": "Taux de commission mis à jour"
+ },
+ "search_placeholder": "Rechercher par nom…",
+ "rule_picker_unavailable": "Cette version n'a pas de sélecteur pour ce type de cible."
}
}
}
diff --git a/packages/dashboard/src/locales/pl.json b/packages/dashboard/src/locales/pl.json
index 80d7dab349..2b53d33d07 100644
--- a/packages/dashboard/src/locales/pl.json
+++ b/packages/dashboard/src/locales/pl.json
@@ -1666,6 +1666,58 @@
"placeholder": "Wybierz datę",
"help": "Katalog pozostaje widoczny, ale do tego czasu nic nie da się kupić."
}
+ },
+ "commission_rate": {
+ "name": {
+ "placeholder": "Prowizja standardowa"
+ },
+ "code": {
+ "label": "Kod",
+ "placeholder": "standard",
+ "help": "Twój własny identyfikator tej stawki."
+ },
+ "kind": {
+ "label": "Opłata",
+ "options": {
+ "percentage": "Procent sprzedaży",
+ "fixed": "Kwota stała"
+ }
+ },
+ "value": {
+ "label": "Kwota",
+ "help_percentage": "Procent sprzedaży pobierany od sprzedawcy.",
+ "help_fixed": "Stała opłata za sprzedaż, w walucie poniżej."
+ },
+ "priority": {
+ "label": "Priorytet",
+ "help": "Stawki są sprawdzane od najwyższej; wygrywa pierwsze dopasowanie."
+ },
+ "rules": {
+ "label": "Dotyczy",
+ "help": "Wybory w jednym polu to alternatywy; każde wypełnione pole musi pasować. Zostaw wszystkie puste, aby objąć każdą sprzedaż."
+ },
+ "min_amount": {
+ "label": "Minimum"
+ },
+ "max_amount": {
+ "label": "Maksimum"
+ },
+ "commission_tax_rate": {
+ "label": "Podatek od prowizji (%)",
+ "placeholder": "Z ustawień podatkowych",
+ "help": "VAT od samej prowizji, jako odrębna usługa dla sprzedawcy. Zostaw puste, aby użyć ustawień podatkowych."
+ },
+ "include_shipping": {
+ "label": "Nalicz od dostawy",
+ "help": "Nalicz prowizję również od przychodów sprzedawcy z dostawy."
+ },
+ "include_tax": {
+ "label": "Nalicz od ceny brutto",
+ "help": "Nalicz od ceny z VAT klienta. Wyłączone to reguła UE: od przychodu netto sprzedawcy."
+ },
+ "enabled": {
+ "help": "Wyłączone stawki są pomijane przy naliczaniu."
+ }
}
},
"delivery_profiles": {
@@ -3068,6 +3120,10 @@
"tax_rates": {
"add_sheet_title": "Nowa stawka podatku",
"edit_sheet_title": "Edytuj stawkę podatku"
+ },
+ "commission_rates": {
+ "add_sheet_title": "Dodaj stawkę prowizji",
+ "edit_sheet_title": "Edytuj stawkę prowizji"
}
},
"staff": {
@@ -3800,7 +3856,8 @@
"store": "Sklep",
"tax_categories": "Kategorie podatkowe",
"tax_rates": "Stawki podatku",
- "webhooks": "Webhooki"
+ "webhooks": "Webhooki",
+ "commission_rates": "Stawki prowizji"
}
},
"setup": {
@@ -4276,6 +4333,25 @@
"placeholder": "Szukaj sprzedawców",
"empty": "Nie znaleziono sprzedawców"
}
+ },
+ "commission_rates": {
+ "add_cta": "Dodaj stawkę prowizji",
+ "applies_to_everything": "Każda sprzedaż",
+ "create_description": "Określ, ile marketplace pobiera od sprzedawców i których sprzedaży to dotyczy.",
+ "create_label": "Utwórz stawkę prowizji",
+ "delete_confirm": {
+ "message": "{{name}} zostanie usunięta. Naliczone już prowizje pozostaną bez zmian.",
+ "title": "Usunąć stawkę prowizji?"
+ },
+ "edit_description": "Zaktualizuj opłatę, jej limity i objęte nią sprzedaże.",
+ "empty": "Brak stawek prowizji",
+ "messages": {
+ "created": "Utworzono stawkę prowizji",
+ "deleted": "Usunięto stawkę prowizji",
+ "updated": "Zaktualizowano stawkę prowizji"
+ },
+ "search_placeholder": "Szukaj po nazwie…",
+ "rule_picker_unavailable": "Ta wersja nie ma selektora dla tego typu celu."
}
}
}
diff --git a/packages/dashboard/src/locales/zh-CN.json b/packages/dashboard/src/locales/zh-CN.json
index 3749090db9..cbaffedfb9 100644
--- a/packages/dashboard/src/locales/zh-CN.json
+++ b/packages/dashboard/src/locales/zh-CN.json
@@ -1649,6 +1649,58 @@
"placeholder": "选择日期",
"help": "在此之前商品仍然可见,但无法购买。"
}
+ },
+ "commission_rate": {
+ "name": {
+ "placeholder": "标准佣金"
+ },
+ "code": {
+ "label": "代码",
+ "placeholder": "standard",
+ "help": "你为该费率设定的标识。"
+ },
+ "kind": {
+ "label": "收费方式",
+ "options": {
+ "percentage": "按销售额百分比",
+ "fixed": "固定费用"
+ }
+ },
+ "value": {
+ "label": "金额",
+ "help_percentage": "向卖家收取的销售额百分比。",
+ "help_fixed": "每笔销售收取的固定费用,使用下方货币。"
+ },
+ "priority": {
+ "label": "优先级",
+ "help": "按优先级从高到低匹配,首个匹配的费率生效。"
+ },
+ "rules": {
+ "label": "适用范围",
+ "help": "同一栏内的选择是「或」的关系;每个填写的栏位都必须匹配。全部留空则适用于所有销售。"
+ },
+ "min_amount": {
+ "label": "最低"
+ },
+ "max_amount": {
+ "label": "最高"
+ },
+ "commission_tax_rate": {
+ "label": "佣金税率(%)",
+ "placeholder": "使用税务设置",
+ "help": "对佣金本身征收的增值税,属于面向卖家的独立服务。留空则使用你的税务设置。"
+ },
+ "include_shipping": {
+ "label": "对配送收费",
+ "help": "同时对卖家的配送收入收取佣金。"
+ },
+ "include_tax": {
+ "label": "按含税价计算",
+ "help": "按含客户增值税的价格计算。关闭即欧盟规则:按卖家净收入计算。"
+ },
+ "enabled": {
+ "help": "停用的费率在计费时会被跳过。"
+ }
}
},
"delivery_profiles": {
@@ -3020,6 +3072,10 @@
"tax_rates": {
"add_sheet_title": "新建税率",
"edit_sheet_title": "编辑税率"
+ },
+ "commission_rates": {
+ "add_sheet_title": "添加佣金费率",
+ "edit_sheet_title": "编辑佣金费率"
}
},
"staff": {
@@ -3742,7 +3798,8 @@
"store": "店铺",
"tax_categories": "税收类别",
"tax_rates": "税率",
- "webhooks": "Webhooks"
+ "webhooks": "Webhooks",
+ "commission_rates": "佣金费率"
}
},
"setup": {
@@ -4216,6 +4273,25 @@
"placeholder": "搜索卖家",
"empty": "未找到卖家"
}
+ },
+ "commission_rates": {
+ "add_cta": "添加佣金费率",
+ "applies_to_everything": "所有销售",
+ "create_description": "设置平台向卖家收取的费用,以及适用于哪些销售。",
+ "create_label": "创建佣金费率",
+ "delete_confirm": {
+ "message": "将删除 {{name}}。已收取的佣金不受影响。",
+ "title": "删除佣金费率?"
+ },
+ "edit_description": "更新费用、上下限以及适用的销售范围。",
+ "empty": "暂无佣金费率",
+ "messages": {
+ "created": "佣金费率已创建",
+ "deleted": "佣金费率已删除",
+ "updated": "佣金费率已更新"
+ },
+ "search_placeholder": "按名称搜索…",
+ "rule_picker_unavailable": "当前版本没有该目标类型的选择器。"
}
}
}
diff --git a/packages/dashboard/src/nav/settings.ts b/packages/dashboard/src/nav/settings.ts
index 7b319493f8..6f695c951c 100644
--- a/packages/dashboard/src/nav/settings.ts
+++ b/packages/dashboard/src/nav/settings.ts
@@ -3,6 +3,7 @@ import {
CreditCardIcon,
GlobeIcon,
GlobeLockIcon,
+ HandCoinsIcon,
KeyRoundIcon,
MailIcon,
PercentIcon,
@@ -103,6 +104,16 @@ settingsNav.add({
subject: Subject.TaxRate,
})
+settingsNav.add({
+ key: 'settings.commission-rates',
+ labelKey: 'admin.settings_nav.items.commission_rates',
+ path: '/commission-rates',
+ icon: HandCoinsIcon,
+ group: 'payments',
+ position: 275,
+ subject: Subject.CommissionRate,
+})
+
settingsNav.add({
key: 'settings.markets',
labelKey: 'admin.settings_nav.items.markets',
diff --git a/packages/dashboard/src/routeTree.gen.ts b/packages/dashboard/src/routeTree.gen.ts
index 529441839e..f39c64e226 100644
--- a/packages/dashboard/src/routeTree.gen.ts
+++ b/packages/dashboard/src/routeTree.gen.ts
@@ -45,6 +45,7 @@ import { Route as SettingsMarketsRouteImport } from './routes/_authenticated/$st
import { Route as SettingsIntegrationsRouteImport } from './routes/_authenticated/$storeId/settings/integrations'
import { Route as SettingsEmailsRouteImport } from './routes/_authenticated/$storeId/settings/emails'
import { Route as SettingsCustomFieldDefinitionsRouteImport } from './routes/_authenticated/$storeId/settings/custom-field-definitions'
+import { Route as SettingsCommissionRatesRouteImport } from './routes/_authenticated/$storeId/settings/commission-rates'
import { Route as SettingsChannelsRouteImport } from './routes/_authenticated/$storeId/settings/channels'
import { Route as SettingsApiKeysRouteImport } from './routes/_authenticated/$storeId/settings/api-keys'
import { Route as SettingsAllowedOriginsRouteImport } from './routes/_authenticated/$storeId/settings/allowed-origins'
@@ -261,6 +262,11 @@ const SettingsCustomFieldDefinitionsRoute =
path: '/custom-field-definitions',
getParentRoute: () => SettingsRoute,
} as any)
+const SettingsCommissionRatesRoute = SettingsCommissionRatesRouteImport.update({
+ id: '/commission-rates',
+ path: '/commission-rates',
+ getParentRoute: () => SettingsRoute,
+} as any)
const SettingsChannelsRoute = SettingsChannelsRouteImport.update({
id: '/channels',
path: '/channels',
@@ -472,6 +478,7 @@ export interface FileRoutesByFullPath {
'/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
'/$storeId/settings/channels': typeof SettingsChannelsRoute
+ '/$storeId/settings/commission-rates': typeof SettingsCommissionRatesRoute
'/$storeId/settings/custom-field-definitions': typeof SettingsCustomFieldDefinitionsRoute
'/$storeId/settings/emails': typeof SettingsEmailsRoute
'/$storeId/settings/integrations': typeof SettingsIntegrationsRoute
@@ -541,6 +548,7 @@ export interface FileRoutesByTo {
'/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
'/$storeId/settings/channels': typeof SettingsChannelsRoute
+ '/$storeId/settings/commission-rates': typeof SettingsCommissionRatesRoute
'/$storeId/settings/custom-field-definitions': typeof SettingsCustomFieldDefinitionsRoute
'/$storeId/settings/emails': typeof SettingsEmailsRoute
'/$storeId/settings/integrations': typeof SettingsIntegrationsRoute
@@ -614,6 +622,7 @@ export interface FileRoutesById {
'/_authenticated/$storeId/settings/allowed-origins': typeof SettingsAllowedOriginsRoute
'/_authenticated/$storeId/settings/api-keys': typeof SettingsApiKeysRoute
'/_authenticated/$storeId/settings/channels': typeof SettingsChannelsRoute
+ '/_authenticated/$storeId/settings/commission-rates': typeof SettingsCommissionRatesRoute
'/_authenticated/$storeId/settings/custom-field-definitions': typeof SettingsCustomFieldDefinitionsRoute
'/_authenticated/$storeId/settings/emails': typeof SettingsEmailsRoute
'/_authenticated/$storeId/settings/integrations': typeof SettingsIntegrationsRoute
@@ -687,6 +696,7 @@ export interface FileRouteTypes {
| '/$storeId/settings/allowed-origins'
| '/$storeId/settings/api-keys'
| '/$storeId/settings/channels'
+ | '/$storeId/settings/commission-rates'
| '/$storeId/settings/custom-field-definitions'
| '/$storeId/settings/emails'
| '/$storeId/settings/integrations'
@@ -756,6 +766,7 @@ export interface FileRouteTypes {
| '/$storeId/settings/allowed-origins'
| '/$storeId/settings/api-keys'
| '/$storeId/settings/channels'
+ | '/$storeId/settings/commission-rates'
| '/$storeId/settings/custom-field-definitions'
| '/$storeId/settings/emails'
| '/$storeId/settings/integrations'
@@ -828,6 +839,7 @@ export interface FileRouteTypes {
| '/_authenticated/$storeId/settings/allowed-origins'
| '/_authenticated/$storeId/settings/api-keys'
| '/_authenticated/$storeId/settings/channels'
+ | '/_authenticated/$storeId/settings/commission-rates'
| '/_authenticated/$storeId/settings/custom-field-definitions'
| '/_authenticated/$storeId/settings/emails'
| '/_authenticated/$storeId/settings/integrations'
@@ -1133,6 +1145,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof SettingsCustomFieldDefinitionsRouteImport
parentRoute: typeof SettingsRoute
}
+ '/_authenticated/$storeId/settings/commission-rates': {
+ id: '/_authenticated/$storeId/settings/commission-rates'
+ path: '/commission-rates'
+ fullPath: '/$storeId/settings/commission-rates'
+ preLoaderRoute: typeof SettingsCommissionRatesRouteImport
+ parentRoute: typeof SettingsRoute
+ }
'/_authenticated/$storeId/settings/channels': {
id: '/_authenticated/$storeId/settings/channels'
path: '/channels'
@@ -1378,6 +1397,7 @@ interface SettingsRouteChildren {
SettingsAllowedOriginsRoute: typeof SettingsAllowedOriginsRoute
SettingsApiKeysRoute: typeof SettingsApiKeysRoute
SettingsChannelsRoute: typeof SettingsChannelsRoute
+ SettingsCommissionRatesRoute: typeof SettingsCommissionRatesRoute
SettingsCustomFieldDefinitionsRoute: typeof SettingsCustomFieldDefinitionsRoute
SettingsEmailsRoute: typeof SettingsEmailsRoute
SettingsIntegrationsRoute: typeof SettingsIntegrationsRoute
@@ -1405,6 +1425,7 @@ const SettingsRouteChildren: SettingsRouteChildren = {
SettingsAllowedOriginsRoute: SettingsAllowedOriginsRoute,
SettingsApiKeysRoute: SettingsApiKeysRoute,
SettingsChannelsRoute: SettingsChannelsRoute,
+ SettingsCommissionRatesRoute: SettingsCommissionRatesRoute,
SettingsCustomFieldDefinitionsRoute: SettingsCustomFieldDefinitionsRoute,
SettingsEmailsRoute: SettingsEmailsRoute,
SettingsIntegrationsRoute: SettingsIntegrationsRoute,
diff --git a/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx
new file mode 100644
index 0000000000..c7f8084b2b
--- /dev/null
+++ b/packages/dashboard/src/routes/_authenticated/$storeId/settings/commission-rates.tsx
@@ -0,0 +1,569 @@
+import { zodResolver } from '@hookform/resolvers/zod'
+import type { CommissionRate, CommissionRateCreateParams } from '@spree/admin-sdk'
+import {
+ adminClient,
+ Can,
+ mapSpreeErrorsToForm,
+ ResourceMultiAutocomplete,
+ ResourceTable,
+ resourceSearchSchema,
+ Subject,
+ usePermissions,
+} from '@spree/dashboard-core'
+import {
+ Button,
+ Field,
+ FieldError,
+ FieldGroup,
+ FieldLabel,
+ Input,
+ RowActions,
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+ Sheet,
+ SheetContent,
+ SheetDescription,
+ SheetFooter,
+ SheetHeader,
+ SheetTitle,
+ Switch,
+ useConfirm,
+ useRowClickBridge,
+} from '@spree/dashboard-ui'
+import { createFileRoute, useNavigate } from '@tanstack/react-router'
+import { PlusIcon } from 'lucide-react'
+import { useEffect } from 'react'
+import { Controller, type UseFormReturn, useForm } from 'react-hook-form'
+import { useTranslation } from 'react-i18next'
+import { z } from 'zod/v4'
+import { commissionRuleSubjectPicker } from '../../../../components/spree/commission-rule-subjects'
+import {
+ useCommissionRate,
+ useCommissionRuleSubjectTypes,
+ useCreateCommissionRate,
+ useDeleteCommissionRate,
+ useUpdateCommissionRate,
+} from '../../../../hooks/use-commission-rates'
+import {
+ COMMISSION_RATE_DEFAULTS,
+ COMMISSION_RATE_KINDS,
+ type CommissionRateFormValues,
+ commissionRateFormSchema,
+ commissionRateToFormValues,
+ commissionRateValuesToParams,
+} from '../../../../schemas/commission-rate'
+import '../../../../tables/commission-rates'
+
+const commissionRatesSearchSchema = resourceSearchSchema.extend({
+ edit: z.string().optional(),
+ new: z.coerce.boolean().optional(),
+})
+
+export const Route = createFileRoute('/_authenticated/$storeId/settings/commission-rates')({
+ validateSearch: commissionRatesSearchSchema,
+ component: CommissionRatesPage,
+})
+
+function CommissionRatesPage() {
+ const { t } = useTranslation()
+ const search = Route.useSearch() as z.infer<typeof commissionRatesSearchSchema>
+ const navigate = useNavigate()
+ const confirm = useConfirm()
+ const deleteMutation = useDeleteCommissionRate()
+ const { permissions } = usePermissions()
+
+ const editId = search.edit
+ const isCreating = !!search.new
+
+ const closeSheet = () =>
+ navigate({
+ search: (prev: Record<string, unknown>) => {
+ const { edit: _e, new: _n, ...rest } = prev
+ return rest as never
+ },
+ })
+
+ const openCreate = () =>
+ navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, new: true }) as never })
+
+ const openEdit = (id: string) =>
+ navigate({ search: (prev: Record<string, unknown>) => ({ ...prev, edit: id }) as never })
+
+ useRowClickBridge('data-commission-rate-id', openEdit)
+
+ async function handleDelete(rate: CommissionRate) {
+ const ok = await confirm({
+ title: t('admin.commission_rates.delete_confirm.title'),
+ message: t('admin.commission_rates.delete_confirm.message', { name: rate.name ?? '' }),
+ variant: 'destructive',
+ confirmLabel: t('admin.actions.delete'),
+ })
+ if (!ok) return
+ await deleteMutation.mutateAsync(rate.id).catch(() => undefined)
+ }
+
+ return (
+ <>
+ <ResourceTable<CommissionRate>
+ tableKey="commission-rates"
+ queryKey="commission-rates"
+ queryFn={(params) => adminClient.commissionRates.list(params)}
+ searchParams={search}
+ rowActions={(rate) => (
+ <RowActions
+ actions={[
+ { key: 'edit', onSelect: () => openEdit(rate.id) },
+ {
+ key: 'delete',
+ destructive: true,
+ visible: permissions.can('destroy', Subject.CommissionRate),
+ disabled: deleteMutation.isPending,
+ onSelect: () => handleDelete(rate),
+ },
+ ]}
+ />
+ )}
+ actions={
+ <Can I="create" a={Subject.CommissionRate}>
+ <Button size="sm" className="h-[2.125rem]" onClick={openCreate}>
+ <PlusIcon className="size-4" />
+ {t('admin.commission_rates.add_cta')}
+ </Button>
+ </Can>
+ }
+ />
+
+ {isCreating && <CreateCommissionRateSheet open onOpenChange={(o) => !o && closeSheet()} />}
+ {editId && (
+ <EditCommissionRateSheet id={editId} open onOpenChange={(o) => !o && closeSheet()} />
+ )}
+ </>
+ )
+}
+
+function CreateCommissionRateSheet({
+ open,
+ onOpenChange,
+}: {
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const createMutation = useCreateCommissionRate()
+ const form = useForm<CommissionRateFormValues>({
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ resolver: zodResolver(commissionRateFormSchema) as any,
+ defaultValues: COMMISSION_RATE_DEFAULTS,
+ })
+
+ async function onSubmit(values: CommissionRateFormValues) {
+ try {
+ await createMutation.mutateAsync(
+ commissionRateValuesToParams(values) as CommissionRateCreateParams,
+ )
+ form.reset(COMMISSION_RATE_DEFAULTS)
+ onOpenChange(false)
+ } catch (err) {
+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+ }
+ }
+
+ return (
+ <Sheet
+ open={open}
+ onOpenChange={(next) => {
+ if (!next) form.reset(COMMISSION_RATE_DEFAULTS)
+ onOpenChange(next)
+ }}
+ >
+ <SheetContent>
+ <SheetHeader>
+ <SheetTitle>{t('admin.pages.settings.commission_rates.add_sheet_title')}</SheetTitle>
+ <SheetDescription>{t('admin.commission_rates.create_description')}</SheetDescription>
+ </SheetHeader>
+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+ <CommissionRateFormFields form={form} />
+ </div>
+ <SheetFooter>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ {t('admin.actions.cancel')}
+ </Button>
+ <Button type="submit" size="sm" disabled={form.formState.isSubmitting}>
+ {form.formState.isSubmitting
+ ? t('admin.actions.creating')
+ : t('admin.commission_rates.create_label')}
+ </Button>
+ </SheetFooter>
+ </form>
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+function EditCommissionRateSheet({
+ id,
+ open,
+ onOpenChange,
+}: {
+ id: string
+ open: boolean
+ onOpenChange: (open: boolean) => void
+}) {
+ const { t } = useTranslation()
+ const { data: rate, isLoading } = useCommissionRate(id)
+ const updateMutation = useUpdateCommissionRate(id)
+
+ const form = useForm<CommissionRateFormValues>({
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ resolver: zodResolver(commissionRateFormSchema) as any,
+ defaultValues: COMMISSION_RATE_DEFAULTS,
+ })
+
+ useEffect(() => {
+ if (rate) form.reset(commissionRateToFormValues(rate))
+ }, [rate, form])
+
+ async function onSubmit(values: CommissionRateFormValues) {
+ try {
+ await updateMutation.mutateAsync(commissionRateValuesToParams(values))
+ form.reset(values)
+ onOpenChange(false)
+ } catch (err) {
+ if (!mapSpreeErrorsToForm(err, form.setError)) throw err
+ }
+ }
+
+ return (
+ <Sheet open={open} onOpenChange={onOpenChange}>
+ <SheetContent>
+ <SheetHeader>
+ <SheetTitle>
+ {rate?.name ?? t('admin.pages.settings.commission_rates.edit_sheet_title')}
+ </SheetTitle>
+ <SheetDescription>{t('admin.commission_rates.edit_description')}</SheetDescription>
+ </SheetHeader>
+ {isLoading ? (
+ <div className="p-4 text-sm text-muted-foreground">{t('admin.common.loading')}</div>
+ ) : (
+ <form onSubmit={form.handleSubmit(onSubmit)} className="flex min-h-0 flex-1 flex-col">
+ <div className="flex flex-1 flex-col gap-4 overflow-y-auto p-4">
+ <CommissionRateFormFields form={form} />
+ </div>
+ <SheetFooter>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={form.formState.isSubmitting}
+ >
+ {t('admin.actions.cancel')}
+ </Button>
+ <Button
+ type="submit"
+ size="sm"
+ disabled={form.formState.isSubmitting || !form.formState.isDirty}
+ >
+ {form.formState.isSubmitting ? t('admin.actions.saving') : t('admin.actions.save')}
+ </Button>
+ </SheetFooter>
+ </form>
+ )}
+ </SheetContent>
+ </Sheet>
+ )
+}
+
+function CommissionRateFormFields({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
+ const { t } = useTranslation()
+ const { errors } = form.formState
+ const kind = form.watch('kind')
+
+ const kindOptions = COMMISSION_RATE_KINDS.map((value) => ({
+ value,
+ label: t(`admin.fields.commission_rate.kind.options.${value}`),
+ }))
+
+ return (
+ <FieldGroup>
+ {errors.root?.message && (
+ <p className="text-sm text-destructive" role="alert">
+ {errors.root.message}
+ </p>
+ )}
+
+ <Field>
+ <FieldLabel htmlFor="name">{t('admin.fields.name.label')}</FieldLabel>
+ <Input
+ id="name"
+ autoFocus
+ placeholder={t('admin.fields.commission_rate.name.placeholder')}
+ aria-invalid={!!errors.name || undefined}
+ {...form.register('name')}
+ />
+ <FieldError errors={[errors.name]} />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="code">{t('admin.fields.commission_rate.code.label')}</FieldLabel>
+ <Input
+ id="code"
+ placeholder={t('admin.fields.commission_rate.code.placeholder')}
+ aria-invalid={!!errors.code || undefined}
+ {...form.register('code')}
+ />
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.code.help')}
+ </span>
+ <FieldError errors={[errors.code]} />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="kind">{t('admin.fields.commission_rate.kind.label')}</FieldLabel>
+ <Controller
+ name="kind"
+ control={form.control}
+ render={({ field }) => (
+ <Select items={kindOptions} value={field.value} onValueChange={field.onChange}>
+ <SelectTrigger id="kind">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {kindOptions.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {option.label}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ )}
+ />
+ </Field>
+
+ <Field>
+ <FieldLabel htmlFor="value">{t('admin.fields.commission_rate.value.label')}</FieldLabel>
+ <Input
+ id="value"
+ type="number"
+ step="0.01"
+ min="0"
+ aria-invalid={!!errors.value || undefined}
+ {...form.register('value')}
+ />
+ <span className="text-xs text-muted-foreground">
+ {t(`admin.fields.commission_rate.value.help_${kind}`)}
+ </span>
+ <FieldError errors={[errors.value]} />
+ </Field>
+
+ {/* A percentage travels across currencies; only a flat fee needs one. */}
+ {kind === 'fixed' && (
+ <Field>
+ <FieldLabel htmlFor="currency">{t('admin.fields.currency.label')}</FieldLabel>
+ <Input
+ id="currency"
+ placeholder="USD"
+ aria-invalid={!!errors.currency || undefined}
+ {...form.register('currency')}
+ />
+ <FieldError errors={[errors.currency]} />
+ </Field>
+ )}
+
+ <Field>
+ <FieldLabel htmlFor="priority">
+ {t('admin.fields.commission_rate.priority.label')}
+ </FieldLabel>
+ <Input
+ id="priority"
+ type="number"
+ step="1"
+ aria-invalid={!!errors.priority || undefined}
+ {...form.register('priority')}
+ />
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.priority.help')}
+ </span>
+ <FieldError errors={[errors.priority]} />
+ </Field>
+
+ <CommissionRulesField form={form} />
+
+ <div className="grid grid-cols-2 gap-4">
+ <Field>
+ <FieldLabel htmlFor="min_amount">
+ {t('admin.fields.commission_rate.min_amount.label')}
+ </FieldLabel>
+ <Input
+ id="min_amount"
+ type="number"
+ step="0.01"
+ min="0"
+ {...form.register('min_amount')}
+ />
+ <FieldError errors={[errors.min_amount]} />
+ </Field>
+ <Field>
+ <FieldLabel htmlFor="max_amount">
+ {t('admin.fields.commission_rate.max_amount.label')}
+ </FieldLabel>
+ <Input
+ id="max_amount"
+ type="number"
+ step="0.01"
+ min="0"
+ {...form.register('max_amount')}
+ />
+ <FieldError errors={[errors.max_amount]} />
+ </Field>
+ </div>
+
+ <Field>
+ <FieldLabel htmlFor="commission_tax_rate">
+ {t('admin.fields.commission_rate.commission_tax_rate.label')}
+ </FieldLabel>
+ <Input
+ id="commission_tax_rate"
+ type="number"
+ step="0.01"
+ min="0"
+ placeholder={t('admin.fields.commission_rate.commission_tax_rate.placeholder')}
+ {...form.register('commission_tax_rate')}
+ />
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.commission_tax_rate.help')}
+ </span>
+ <FieldError errors={[errors.commission_tax_rate]} />
+ </Field>
+
+ <ToggleField
+ form={form}
+ name="include_shipping"
+ label={t('admin.fields.commission_rate.include_shipping.label')}
+ help={t('admin.fields.commission_rate.include_shipping.help')}
+ />
+
+ <ToggleField
+ form={form}
+ name="include_tax"
+ label={t('admin.fields.commission_rate.include_tax.label')}
+ help={t('admin.fields.commission_rate.include_tax.help')}
+ />
+
+ <ToggleField
+ form={form}
+ name="enabled"
+ label={t('admin.fields.enabled.label')}
+ help={t('admin.fields.commission_rate.enabled.help')}
+ />
+ </FieldGroup>
+ )
+}
+
+function ToggleField({
+ form,
+ name,
+ label,
+ help,
+}: {
+ form: UseFormReturn<CommissionRateFormValues>
+ name: 'enabled' | 'include_tax' | 'include_shipping'
+ label: string
+ help: string
+}) {
+ return (
+ <Field>
+ <div className="flex items-start justify-between gap-4">
+ <div className="flex flex-col">
+ <FieldLabel htmlFor={name} className="cursor-pointer">
+ {label}
+ </FieldLabel>
+ <span className="text-xs text-muted-foreground">{help}</span>
+ </div>
+ <Controller
+ name={name}
+ control={form.control}
+ render={({ field }) => (
+ <Switch id={name} checked={!!field.value} onCheckedChange={field.onChange} />
+ )}
+ />
+ </div>
+ </Field>
+ )
+}
+
+/**
+ * The rate's targeting, one picker per dimension.
+ *
+ * Grouping the pickers by subject type is what makes the matching rule
+ * legible: everything picked inside one box is an alternative, and every box
+ * that holds something has to match. A rate with all three empty applies to
+ * every sale, which the empty state says outright.
+ */
+function CommissionRulesField({ form }: { form: UseFormReturn<CommissionRateFormValues> }) {
+ const { t } = useTranslation()
+ const { data: subjectTypes } = useCommissionRuleSubjectTypes()
+ const rules = form.watch('rules') ?? []
+
+ function idsFor(subjectType: string) {
+ return rules.filter((rule) => rule.subject_type === subjectType).map((rule) => rule.subject_id)
+ }
+
+ function setIdsFor(subjectType: string, ids: string[]) {
+ const others = rules.filter((rule) => rule.subject_type !== subjectType)
+ form.setValue(
+ 'rules',
+ [...others, ...ids.map((id) => ({ subject_type: subjectType, subject_id: id }))],
+ { shouldDirty: true },
+ )
+ }
+
+ return (
+ <Field>
+ <FieldLabel>{t('admin.fields.commission_rate.rules.label')}</FieldLabel>
+ <span className="text-xs text-muted-foreground">
+ {t('admin.fields.commission_rate.rules.help')}
+ </span>
+ <div className="flex flex-col gap-3 pt-1">
+ {(subjectTypes?.data ?? []).map((subjectType) => {
+ const picker = commissionRuleSubjectPicker(subjectType.type)
+
+ return (
+ <div key={subjectType.type} className="flex flex-col gap-1">
+ <span className="text-xs font-medium">{subjectType.name}</span>
+ {picker ? (
+ <ResourceMultiAutocomplete
+ {...picker(`commission-rule-${subjectType.type}`)}
+ value={idsFor(subjectType.type)}
+ onChange={(ids: string[]) => setIdsFor(subjectType.type, ids)}
+ />
+ ) : (
+ // The server can offer a dimension this build has no picker
+ // for. Saying so beats rendering nothing, which reads as the
+ // dimension not existing.
+ <span className="text-xs text-muted-foreground">
+ {t('admin.commission_rates.rule_picker_unavailable')}
+ </span>
+ )}
+ </div>
+ )
+ })}
+ {rules.length === 0 && (
+ <span className="text-xs text-muted-foreground">
+ {t('admin.commission_rates.applies_to_everything')}
+ </span>
+ )}
+ </div>
+ </Field>
+ )
+}
diff --git a/packages/dashboard/src/schemas/commission-rate.ts b/packages/dashboard/src/schemas/commission-rate.ts
new file mode 100644
index 0000000000..cfe2fabdbf
--- /dev/null
+++ b/packages/dashboard/src/schemas/commission-rate.ts
@@ -0,0 +1,105 @@
+import type {
+ CommissionRate,
+ CommissionRateCreateParams,
+ CommissionRateUpdateParams,
+} from '@spree/admin-sdk'
+import { blankToNull } from '@spree/dashboard-core'
+import { requiredMessage } from '@spree/dashboard-ui'
+import { z } from 'zod/v4'
+
+export const COMMISSION_RATE_KINDS = ['percentage', 'fixed'] as const
+
+export const commissionRateFormSchema = z.object({
+ name: z.string().min(1, { error: requiredMessage('name') }),
+ code: z.string().optional(),
+ enabled: z.boolean(),
+ priority: z.coerce.number().int(),
+ kind: z.enum(COMMISSION_RATE_KINDS),
+ value: z.coerce.number().min(0),
+ currency: z.string().optional(),
+ include_tax: z.boolean(),
+ include_shipping: z.boolean(),
+ min_amount: z.string().optional(),
+ max_amount: z.string().optional(),
+ // Held as a percentage in the form because that is how merchants think about
+ // VAT; converted to the fraction the API stores on the way out.
+ commission_tax_rate: z.string().optional(),
+ // Shallow on purpose: react-hook-form's `Path<T>` walks every nested key, so
+ // an SDK entity here would drag its whole object graph into the form type.
+ // The pickers resolve their own labels, so an id is all the form carries.
+ rules: z.array(
+ z.object({
+ subject_type: z.string(),
+ subject_id: z.string(),
+ }),
+ ),
+})
+
+export type CommissionRateFormValues = z.infer<typeof commissionRateFormSchema>
+
+export const COMMISSION_RATE_DEFAULTS: CommissionRateFormValues = {
+ name: '',
+ code: '',
+ enabled: true,
+ priority: 0,
+ kind: 'percentage',
+ value: 10,
+ currency: '',
+ include_tax: false,
+ include_shipping: false,
+ min_amount: '',
+ max_amount: '',
+ commission_tax_rate: '',
+ rules: [],
+}
+
+export function commissionRateToFormValues(rate: CommissionRate): CommissionRateFormValues {
+ return {
+ name: rate.name,
+ code: rate.code ?? '',
+ enabled: rate.enabled,
+ priority: rate.priority,
+ kind: (rate.kind as CommissionRateFormValues['kind']) ?? 'percentage',
+ value: Number(rate.value ?? 0),
+ currency: rate.currency ?? '',
+ include_tax: rate.include_tax,
+ include_shipping: rate.include_shipping,
+ min_amount: rate.min_amount == null ? '' : String(rate.min_amount),
+ max_amount: rate.max_amount == null ? '' : String(rate.max_amount),
+ commission_tax_rate:
+ rate.commission_tax_rate == null ? '' : String(Number(rate.commission_tax_rate) * 100),
+ rules: (rate.rules ?? []).map((rule) => ({
+ subject_type: rule.subject_type ?? '',
+ subject_id: rule.subject_id ?? '',
+ })),
+ }
+}
+
+function decimalOrNull(value: string | undefined): number | null {
+ const trimmed = value?.trim()
+ return trimmed ? Number(trimmed) : null
+}
+
+export function commissionRateValuesToParams(
+ v: CommissionRateFormValues,
+): CommissionRateCreateParams & CommissionRateUpdateParams {
+ const taxPercentage = decimalOrNull(v.commission_tax_rate)
+
+ return {
+ name: v.name,
+ code: blankToNull(v.code),
+ enabled: v.enabled,
+ priority: v.priority,
+ kind: v.kind,
+ value: v.value,
+ // A percentage applies in any currency, so sending one would only be
+ // noise the server ignores.
+ currency: v.kind === 'fixed' ? blankToNull(v.currency) : null,
+ include_tax: v.include_tax,
+ include_shipping: v.include_shipping,
+ min_amount: decimalOrNull(v.min_amount),
+ max_amount: decimalOrNull(v.max_amount),
+ commission_tax_rate: taxPercentage === null ? null : taxPercentage / 100,
+ rules: v.rules,
+ }
+}
diff --git a/packages/dashboard/src/tables/commission-rates.tsx b/packages/dashboard/src/tables/commission-rates.tsx
new file mode 100644
index 0000000000..3179d0f6ac
--- /dev/null
+++ b/packages/dashboard/src/tables/commission-rates.tsx
@@ -0,0 +1,74 @@
+import type { CommissionRate } from '@spree/admin-sdk'
+import { defineTable } from '@spree/dashboard-core'
+import { ActiveBadge, ResourceNameCell } from '@spree/dashboard-ui'
+import i18n from 'i18next'
+import { HandCoinsIcon } from 'lucide-react'
+
+defineTable<CommissionRate>('commission-rates', {
+ title: i18n.t('admin.settings_nav.items.commission_rates'),
+ searchParam: 'name_cont',
+ searchPlaceholder: i18n.t('admin.commission_rates.search_placeholder'),
+ // Highest priority first — the order the marketplace actually resolves in,
+ // so the list reads as the ladder it is.
+ defaultSort: { field: 'priority', direction: 'desc' },
+ emptyIcon: <HandCoinsIcon className="size-8 text-muted-foreground" />,
+ emptyMessage: i18n.t('admin.commission_rates.empty'),
+ columns: [
+ {
+ key: 'name',
+ label: i18n.t('admin.fields.name.label'),
+ sortable: true,
+ filterable: true,
+ default: true,
+ render: (rate) => (
+ <ResourceNameCell
+ id={rate.id}
+ dataAttr="data-commission-rate-id"
+ name={rate.name}
+ secondary={rate.code}
+ />
+ ),
+ },
+ {
+ key: 'value',
+ label: i18n.t('admin.fields.commission_rate.value.label'),
+ sortable: true,
+ default: true,
+ render: (rate) =>
+ rate.kind === 'percentage'
+ ? `${rate.value}%`
+ : `${rate.value} ${rate.currency ?? ''}`.trim(),
+ },
+ {
+ key: 'priority',
+ label: i18n.t('admin.fields.commission_rate.priority.label'),
+ sortable: true,
+ default: true,
+ render: (rate) => rate.priority,
+ },
+ {
+ key: 'rules',
+ label: i18n.t('admin.fields.commission_rate.rules.label'),
+ default: true,
+ render: (rate) =>
+ rate.rules?.length
+ ? rate.rules
+ .map((rule) => rule.subject_name)
+ .filter(Boolean)
+ .join(', ')
+ : i18n.t('admin.commission_rates.applies_to_everything'),
+ },
+ {
+ key: 'enabled',
+ label: i18n.t('admin.fields.enabled.label'),
+ default: true,
+ render: (rate) => (
+ <ActiveBadge
+ active={rate.enabled}
+ activeLabel={i18n.t('admin.fields.enabled.label')}
+ dashWhenInactive
+ />
+ ),
+ },
+ ],
+})
diff --git a/spree/api/app/controllers/spree/api/v3/admin/commission_lines_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/commission_lines_controller.rb
new file mode 100644
index 0000000000..4d5a3d97ca
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/commission_lines_controller.rb
@@ -0,0 +1,37 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # What the marketplace actually earned, sale by sale.
+ #
+ # Read-only, enforced by the routes: a commission line records
+ # something that already happened, frozen when the order was placed.
+ # Correcting one is not an edit but a reversal, which arrives with
+ # refunds in the next phase.
+ class CommissionLinesController < ResourceController
+ scoped_resource :commissions
+
+ protected
+
+ def model_class
+ Spree::CommissionLine
+ end
+
+ def serializer_class
+ Spree.api.admin_commission_line_serializer
+ end
+
+ # Reached through the store's own orders: the lines carry no store of
+ # their own, and the order is what ties them to one.
+ def scope
+ super.where(order_id: current_store.orders.select(:id))
+ end
+
+ def collection_includes
+ [:vendor, :commission_rate, :order]
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/controllers/spree/api/v3/admin/commission_rates_controller.rb b/spree/api/app/controllers/spree/api/v3/admin/commission_rates_controller.rb
new file mode 100644
index 0000000000..2de530e188
--- /dev/null
+++ b/spree/api/app/controllers/spree/api/v3/admin/commission_rates_controller.rb
@@ -0,0 +1,106 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # What the marketplace charges its sellers, as the operator configures it.
+ #
+ # Targeting rides the regular payload as `rules: [...]` rather than
+ # living at its own endpoint, so the whole editor saves in one
+ # round-trip — the same shape price lists use.
+ #
+ # Operator-only: `read_commissions`/`write_commissions` is closed to the
+ # vendor audience, because a seller must never see, let alone set, what
+ # anyone is charged.
+ class CommissionRatesController < ResourceController
+ scoped_resource :commissions
+
+ # GET /api/v3/admin/commission_rates/rule_subject_types
+ #
+ # What a rule may target, so the dashboard can build its picker
+ # without hardcoding a list that core owns.
+ def rule_subject_types
+ authorize! :read, Spree::CommissionRule
+
+ render json: {
+ data: Spree::CommissionRule::SUBJECT_TYPES.map do |subject_type|
+ {
+ type: subject_type,
+ name: Spree.t("commission_rule_subjects.#{subject_type.demodulize.underscore}",
+ default: subject_type.demodulize.titleize)
+ }
+ end
+ }
+ end
+
+ protected
+
+ def model_class
+ Spree::CommissionRate
+ end
+
+ def serializer_class
+ Spree.api.admin_commission_rate_serializer
+ end
+
+ def scope
+ super.for_store(current_store)
+ end
+
+ def collection_includes
+ [{ commission_rules: :subject }]
+ end
+
+ # `rule_subject_types` is read-only discovery — maps to the read
+ # scope and the :show ability rather than counting as a write.
+ def read_actions
+ super + %w[rule_subject_types]
+ end
+
+ def permitted_params
+ attributes = normalize_params(
+ params.permit(
+ :name, :code, :enabled, :priority, :kind, :value, :currency,
+ :include_tax, :include_shipping, :min_amount, :max_amount, :commission_tax_rate,
+ metadata: {},
+ rules: [:subject_type, :subject_id]
+ )
+ )
+
+ attributes[:rules] = own_store_rules(attributes[:rules]) if attributes.key?(:rules)
+ attributes
+ end
+
+ private
+
+ # Drops any rule naming a record this store does not own.
+ #
+ # The model assigns rule subjects by id with no scoping of its own, so
+ # without this a rate could be targeted at another store's product —
+ # and the serializer would then read that record's name straight back,
+ # which is an enumeration oracle over someone else's catalog.
+ def own_store_rules(rules)
+ Array(rules).select do |rule|
+ subject_type = rule[:subject_type].presence
+ next true if subject_type.nil? && rule[:subject_id].blank?
+ next false unless Spree::CommissionRule::SUBJECT_TYPES.include?(subject_type)
+
+ own_store_subject?(subject_type, rule[:subject_id])
+ end
+ end
+
+ def own_store_subject?(subject_type, subject_id)
+ return false if subject_id.blank?
+
+ case subject_type
+ when 'Spree::Product' then current_store.products.exists?(id: subject_id)
+ when 'Spree::Vendor' then current_store.vendors.exists?(id: subject_id)
+ # Categories are store-owned too, and reached the same way.
+ when 'Spree::Category' then current_store.categories.exists?(id: subject_id)
+ else false
+ end
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/commission_line_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/commission_line_serializer.rb
new file mode 100644
index 0000000000..19dde09276
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/commission_line_serializer.rb
@@ -0,0 +1,55 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Serializes Spree::CommissionLine — what one sale actually earned the
+ # marketplace, frozen at placement.
+ #
+ # Read-only everywhere: a commission line records something that
+ # already happened, so it is never written through the API.
+ #
+ # `amount` and `tax_amount` stay separate rather than being folded into
+ # `total`, because they are two different supplies: the fee, and the
+ # VAT the platform charges the seller on that fee. A seller's invoice
+ # has to show both.
+ class CommissionLineSerializer < V3::BaseSerializer
+ typelize order_id: :string,
+ vendor_id: :string,
+ vendor_name: 'string | null',
+ line_item_id: 'string | null',
+ fulfillment_id: 'string | null',
+ commission_rate_id: 'string | null',
+ kind: :string,
+ rate: :string,
+ amount: :string,
+ tax_amount: :string,
+ total: :string,
+ currency: :string,
+ display_amount: :string,
+ display_tax_amount: :string,
+ display_total: :string
+
+ attributes :kind, :currency, created_at: :iso8601, updated_at: :iso8601
+
+ # Strings, so the figures a seller is invoiced round-trip exactly.
+ %i[rate amount tax_amount total].each do |decimal|
+ attribute(decimal) { |line| line.public_send(decimal)&.to_s }
+ end
+
+ %i[display_amount display_tax_amount display_total].each do |formatted|
+ attribute(formatted) { |line| line.public_send(formatted).to_s }
+ end
+
+ %i[order vendor line_item fulfillment commission_rate].each do |association|
+ attribute(:"#{association}_id") { |line| line.public_send(association)&.prefixed_id }
+ end
+
+ # The seller's name, so a commission table reads without expanding.
+ attribute :vendor_name do |line|
+ line.vendor&.name
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb
new file mode 100644
index 0000000000..2ab7f78d7c
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/commission_rate_serializer.rb
@@ -0,0 +1,49 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Serializes Spree::CommissionRate — what the marketplace charges, as
+ # configuration.
+ #
+ # Admin-only: a rate is a term of business between the operator and its
+ # sellers, so it has no Store API counterpart. Sellers read what they
+ # were actually charged (Spree::CommissionLine) on their own branch,
+ # never the rules that produced it.
+ class CommissionRateSerializer < V3::BaseSerializer
+ # Decimals serialize as strings, like every other money-ish field on
+ # the admin API: a rate has to round-trip exactly, and a float does
+ # not promise that.
+ typelize name: :string,
+ code: 'string | null',
+ enabled: :boolean,
+ priority: :number,
+ kind: :string,
+ value: :string,
+ currency: 'string | null',
+ include_tax: :boolean,
+ include_shipping: :boolean,
+ min_amount: 'string | null',
+ max_amount: 'string | null',
+ commission_tax_rate: 'string | null',
+ deleted_at: 'string | null'
+
+ attributes :name, :code, :enabled, :priority, :kind, :currency,
+ :include_tax, :include_shipping,
+ deleted_at: :iso8601, created_at: :iso8601, updated_at: :iso8601
+
+ %i[value min_amount max_amount commission_tax_rate].each do |decimal|
+ attribute(decimal) { |rate| rate.public_send(decimal)&.to_s }
+ end
+
+ # Always embedded rather than expand-gated: a rate without its
+ # targeting cannot be read (a rate with no rules means something
+ # entirely different from one whose rules were not loaded), and
+ # they are a handful of rows.
+ many :commission_rules,
+ key: :rules,
+ resource: proc { Spree.api.admin_commission_rule_serializer }
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/app/serializers/spree/api/v3/admin/commission_rule_serializer.rb b/spree/api/app/serializers/spree/api/v3/admin/commission_rule_serializer.rb
new file mode 100644
index 0000000000..6f4d53f986
--- /dev/null
+++ b/spree/api/app/serializers/spree/api/v3/admin/commission_rule_serializer.rb
@@ -0,0 +1,39 @@
+module Spree
+ module Api
+ module V3
+ module Admin
+ # Serializes Spree::CommissionRule — one targeting clause on a rate.
+ #
+ # Admin-only, like everything commission: what a marketplace charges is
+ # between it and its sellers, so there is no Store API counterpart.
+ #
+ # `subject_name` saves the SPA a lookup per rule: a rules list has to
+ # render "Cameras" rather than a prefixed id, and the alternative is
+ # three more requests to resolve a handful of names.
+ class CommissionRuleSerializer < V3::BaseSerializer
+ typelize commission_rate_id: :string,
+ subject_type: 'string | null',
+ subject_id: 'string | null',
+ subject_name: 'string | null'
+
+ attributes :subject_type, created_at: :iso8601, updated_at: :iso8601
+
+ attribute :commission_rate_id do |rule|
+ rule.commission_rate&.prefixed_id
+ end
+
+ attribute :subject_id do |rule|
+ rule.subject&.prefixed_id
+ end
+
+ attribute :subject_name do |rule|
+ subject = rule.subject
+ next nil if subject.nil?
+
+ subject.try(:name) || subject.try(:title)
+ end
+ end
+ end
+ end
+ end
+end
diff --git a/spree/api/config/routes.rb b/spree/api/config/routes.rb
index f925357728..a3fb0b4413 100644
--- a/spree/api/config/routes.rb
+++ b/spree/api/config/routes.rb
@@ -441,6 +441,16 @@ Spree::Core::Engine.add_routes do
end
end
+ # Commissions — what the marketplace charges its sellers. Rates are
+ # configuration; lines are the record of what was charged, so they are
+ # read-only.
+ resources :commission_rates do
+ collection do
+ get :rule_subject_types
+ end
+ end
+ resources :commission_lines, only: [:index, :show]
+
# Business customers. Branches and their buyers are created under their
# parent and then addressed directly, so a caller holding a branch id
# does not have to know which company it belongs to.
diff --git a/spree/api/lib/spree/api/dependencies.rb b/spree/api/lib/spree/api/dependencies.rb
index dcc1b4268e..8c493e2e05 100644
--- a/spree/api/lib/spree/api/dependencies.rb
+++ b/spree/api/lib/spree/api/dependencies.rb
@@ -154,6 +154,9 @@ module Spree
admin_admin_user_serializer: 'Spree::Api::V3::Admin::AdminUserSerializer',
vendor_serializer: 'Spree::Api::V3::VendorSerializer',
admin_vendor_serializer: 'Spree::Api::V3::Admin::VendorSerializer',
+ admin_commission_rate_serializer: 'Spree::Api::V3::Admin::CommissionRateSerializer',
+ admin_commission_rule_serializer: 'Spree::Api::V3::Admin::CommissionRuleSerializer',
+ admin_commission_line_serializer: 'Spree::Api::V3::Admin::CommissionLineSerializer',
admin_address_serializer: 'Spree::Api::V3::Admin::AddressSerializer',
admin_channel_serializer: 'Spree::Api::V3::Admin::ChannelSerializer',
admin_order_routing_rule_serializer: 'Spree::Api::V3::Admin::OrderRoutingRuleSerializer',
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/commission_lines_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/commission_lines_controller_spec.rb
new file mode 100644
index 0000000000..6ff50f854f
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/commission_lines_controller_spec.rb
@@ -0,0 +1,65 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::CommissionLinesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let(:vendor) { create(:vendor, :approved, store: store, name: 'Sparks Audio') }
+ let(:order) { create(:order, store: store) }
+ let(:line_item) { create(:line_item, order: order) }
+ let!(:commission_line) do
+ create(:commission_line, order: order, vendor: vendor, line_item: line_item,
+ amount: 10, tax_amount: 2.1, total: 12.1, currency: 'USD')
+ end
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ it 'lists what the marketplace earned' do
+ get :index, as: :json
+
+ expect(response).to have_http_status(:ok)
+ row = json_response['data'].first
+ expect(row['id']).to start_with('comln_')
+ expect(row['vendor_name']).to eq('Sparks Audio')
+ expect(row['amount']).to eq('10.0')
+ expect(row['tax_amount']).to eq('2.1')
+ expect(row['total']).to eq('12.1')
+ expect(row['display_total']).to eq('$12.10')
+ end
+
+ it "hides another marketplace's commission" do
+ other_store = create(:store)
+ other = create(:commission_line,
+ order: create(:order, store: other_store),
+ vendor: create(:vendor, store: other_store),
+ line_item: create(:line_item))
+
+ get :index, as: :json
+
+ expect(json_response['data'].map { |row| row['id'] }).not_to include(other.prefixed_id)
+ end
+ end
+
+ describe 'GET #show' do
+ it 'refuses a line from another store' do
+ other_store = create(:store)
+ other = create(:commission_line,
+ order: create(:order, store: other_store),
+ vendor: create(:vendor, store: other_store),
+ line_item: create(:line_item))
+
+ get :show, params: { id: other.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ # A commission line records something that already happened; correcting one
+ # is a reversal, not an edit.
+ it 'exposes no write route' do
+ expect { patch :update, params: { id: commission_line.prefixed_id }, as: :json }.
+ to raise_error(ActionController::UrlGenerationError)
+ end
+end
diff --git a/spree/api/spec/controllers/spree/api/v3/admin/commission_rates_controller_spec.rb b/spree/api/spec/controllers/spree/api/v3/admin/commission_rates_controller_spec.rb
new file mode 100644
index 0000000000..ad99ad006b
--- /dev/null
+++ b/spree/api/spec/controllers/spree/api/v3/admin/commission_rates_controller_spec.rb
@@ -0,0 +1,125 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Api::V3::Admin::CommissionRatesController, type: :controller do
+ render_views
+
+ include_context 'API v3 Admin authenticated'
+
+ let!(:rate) { create(:commission_rate, store: store, name: 'Standard', value: 10, priority: 5) }
+ let(:vendor) { create(:vendor, store: store) }
+
+ before { request.headers.merge!(headers) }
+
+ describe 'GET #index' do
+ it 'lists the store rates with their targeting' do
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+
+ get :index, as: :json
+
+ expect(response).to have_http_status(:ok)
+ row = json_response['data'].first
+ expect(row['id']).to start_with('comrt_')
+ expect(row['name']).to eq('Standard')
+ expect(row['kind']).to eq('percentage')
+ expect(row['rules'].first).to include('subject_type' => 'Spree::Vendor', 'subject_name' => vendor.name)
+ end
+
+ it "hides another marketplace's rates" do
+ other = create(:commission_rate, store: create(:store))
+
+ get :index, as: :json
+
+ expect(json_response['data'].map { |row| row['id'] }).not_to include(other.prefixed_id)
+ end
+ end
+
+ describe 'GET #show' do
+ it 'refuses a rate belonging to another store' do
+ other = create(:commission_rate, store: create(:store))
+
+ get :show, params: { id: other.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:not_found)
+ end
+ end
+
+ describe 'POST #create' do
+ it 'creates a rate with its targeting in one request' do
+ post :create, params: {
+ name: 'Audio sellers',
+ kind: 'percentage',
+ value: 12.5,
+ priority: 10,
+ rules: [{ subject_type: 'Spree::Vendor', subject_id: vendor.prefixed_id }]
+ }, as: :json
+
+ expect(response).to have_http_status(:created)
+ expect(json_response['value']).to eq('12.5')
+ expect(json_response['rules'].first['subject_id']).to eq(vendor.prefixed_id)
+ end
+
+ it 'refuses a fixed rate with no currency' do
+ post :create, params: { name: 'Flat', kind: 'fixed', value: 2 }, as: :json
+
+ expect(response).to have_http_status(:unprocessable_entity)
+ end
+ end
+
+ describe 'PATCH #update' do
+ it 'replaces the targeting wholesale' do
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+ other_vendor = create(:vendor, store: store)
+
+ patch :update, params: {
+ id: rate.prefixed_id,
+ rules: [{ subject_type: 'Spree::Vendor', subject_id: other_vendor.prefixed_id }]
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(rate.reload.commission_rules.map(&:subject)).to eq([other_vendor])
+ end
+
+ # A rule naming someone else's record would be read straight back by the
+ # serializer, which turns the rate editor into a way to enumerate another
+ # marketplace's catalog.
+ it 'drops a rule naming another store record' do
+ foreign_vendor = create(:vendor, store: create(:store))
+
+ patch :update, params: {
+ id: rate.prefixed_id,
+ rules: [{ subject_type: 'Spree::Vendor', subject_id: foreign_vendor.prefixed_id }]
+ }, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(rate.reload.commission_rules).to be_empty
+ end
+
+ it 'drops a rule naming a type that cannot be targeted' do
+ patch :update, params: {
+ id: rate.prefixed_id,
+ rules: [{ subject_type: 'Spree::Order', subject_id: create(:order, store: store).prefixed_id }]
+ }, as: :json
+
+ expect(rate.reload.commission_rules).to be_empty
+ end
+ end
+
+ describe 'DELETE #destroy' do
+ it 'removes a rate' do
+ delete :destroy, params: { id: rate.prefixed_id }, as: :json
+
+ expect(response).to have_http_status(:no_content)
+ expect(Spree::CommissionRate.where(id: rate.id)).to be_empty
+ end
+ end
+
+ describe 'GET #rule_subject_types' do
+ it 'tells the dashboard what a rule may target' do
+ get :rule_subject_types, as: :json
+
+ expect(response).to have_http_status(:ok)
+ expect(json_response['data'].map { |row| row['type'] }).
+ to match_array(['Spree::Product', 'Spree::Category', 'Spree::Vendor'])
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/commission_lines_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/commission_lines_spec.rb
new file mode 100644
index 0000000000..db8023a9da
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/commission_lines_spec.rb
@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Commission Lines API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let(:vendor) { create(:vendor, :approved, store: store, name: 'Sparks Audio') }
+ let(:order) { create(:order, store: store) }
+ let!(:commission_line) do
+ create(:commission_line, order: order, vendor: vendor, line_item: create(:line_item, order: order),
+ amount: 10, tax_amount: 2.1, total: 12.1, currency: 'USD')
+ end
+
+ path '/api/v3/admin/commission_lines' do
+ get 'List commission lines' do
+ tags 'Commission Lines'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ What each sale actually earned the marketplace, frozen when the order
+ was placed. A later change to a commission rate never reaches these.
+
+ `amount` is the fee charged to the seller and `tax_amount` is the VAT on
+ that fee — the marketplace's own service to the seller, a supply
+ separate from the sale itself, which is why the two are not folded
+ together. `total` is their sum.
+
+ One line per commissioned item, plus one per delivery when the rate that
+ applied charges shipping too — read `line_item_id` and `fulfillment_id`
+ to tell them apart.
+
+ Read-only: correcting a charge is a reversal, not an edit.
+ DESC
+ admin_scope :read, :commissions
+
+ admin_sdk_example 'commission_lines/list'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false,
+ description: 'Number of records per page'
+ parameter name: :'q[vendor_id_eq]', in: :query, type: :string, required: false,
+ description: 'Filter to one seller'
+ parameter name: :'q[order_id_eq]', in: :query, type: :string, required: false,
+ description: 'Filter to one order'
+ parameter name: :sort, in: :query, type: :string, required: false,
+ description: 'Sort by field. Prefix with `-` for descending (e.g., `-created_at`).'
+
+ response '200', 'commission lines found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('CommissionLine')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(commission_line.prefixed_id)
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:Authorization) { 'Bearer invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/commission_lines/{id}' do
+ parameter name: :id, in: :path, type: :string, description: 'Commission line ID'
+
+ get 'Get a commission line' do
+ tags 'Commission Lines'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :commissions
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'commission line found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { commission_line.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/CommissionLine'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['total']).to eq('12.1')
+ end
+ end
+
+ response '404', 'commission line not found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { 'comln_nonexistent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/api/spec/integration/spree/api/v3/admin/commission_rates_spec.rb b/spree/api/spec/integration/spree/api/v3/admin/commission_rates_spec.rb
new file mode 100644
index 0000000000..36b2156ab8
--- /dev/null
+++ b/spree/api/spec/integration/spree/api/v3/admin/commission_rates_spec.rb
@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'Admin Commission Rates API', type: :request, swagger_doc: 'api-reference/admin.yaml' do
+ include_context 'API v3 Admin'
+
+ let(:Authorization) { "Bearer #{admin_jwt_token}" }
+ let!(:commission_rate) do
+ create(:commission_rate, store: store, name: 'Standard', kind: 'percentage', value: 10, priority: 5)
+ end
+
+ path '/api/v3/admin/commission_rates' do
+ get 'List commission rates' do
+ tags 'Commission Rates'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ What the marketplace charges its sellers.
+
+ Rates are tried in `priority` order, highest first, and the first one
+ whose targeting matches the sale wins. A rate carrying no rules matches
+ everything, which is how a marketplace expresses a single default
+ without configuring anything.
+ DESC
+ admin_scope :read, :commissions
+
+ admin_sdk_example 'commission_rates/list'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true,
+ description: 'Bearer token for admin authentication'
+ parameter name: :page, in: :query, type: :integer, required: false, description: 'Page number'
+ parameter name: :limit, in: :query, type: :integer, required: false,
+ description: 'Number of records per page'
+ parameter name: :'q[name_cont]', in: :query, type: :string, required: false,
+ description: 'Filter by name (contains)'
+ parameter name: :'q[enabled_eq]', in: :query, type: :boolean, required: false,
+ description: 'Filter by whether the rate is in use'
+ parameter name: :sort, in: :query, type: :string, required: false,
+ description: 'Sort by field. Prefix with `-` for descending (e.g., `-priority`).'
+
+ response '200', 'commission rates found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema SwaggerSchemaHelpers.paginated('CommissionRate')
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('id')).to include(commission_rate.prefixed_id)
+ end
+ end
+
+ response '401', 'unauthorized' do
+ let(:'x-spree-api-key') { 'invalid' }
+ let(:Authorization) { 'Bearer invalid' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ post 'Create a commission rate' do
+ tags 'Commission Rates'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Sets what the marketplace charges, and which sales it applies to.
+
+ `rules` is the rate's whole targeting, sent inline. Rules are grouped by
+ `subject_type` and matched AND across the groups, OR within one — so
+ `[Cameras, Audio, VendorX]` reads "(Cameras OR Audio) AND VendorX",
+ which is how a seller-and-category pairing is expressed. Send no rules
+ to charge every sale.
+
+ `commission_tax_rate` is VAT on the commission itself — the
+ marketplace's own service to the seller, a separate supply from the
+ sale. Leave it null to let the store's tax engine answer for wherever
+ the seller's business sits.
+ DESC
+ admin_scope :write, :commissions
+
+ admin_sdk_example 'commission_rates/create'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ required: %w[name kind value],
+ properties: {
+ name: { type: :string, example: 'Audio sellers' },
+ code: { type: :string, example: 'audio', nullable: true,
+ description: 'Your own identifier for this rate; unique per store.' },
+ enabled: { type: :boolean, example: true },
+ priority: { type: :integer, example: 10,
+ description: 'Tried highest first; the first matching rate wins.' },
+ kind: { type: :string, enum: %w[percentage fixed], example: 'percentage' },
+ value: { type: :string, example: '12.5',
+ description: 'A percentage (10 = 10%) or a flat amount, per `kind`.' },
+ currency: { type: :string, example: 'USD', nullable: true,
+ description: 'Required for a fixed rate, ignored for a percentage.' },
+ include_tax: { type: :boolean, example: false,
+ description: "Charge on the gross price. Off is the EU rule: charge on the seller's net revenue." },
+ include_shipping: { type: :boolean, example: false,
+ description: "Also charge commission on the seller's delivery revenue." },
+ min_amount: { type: :string, example: '1.0', nullable: true },
+ max_amount: { type: :string, example: '50.0', nullable: true },
+ commission_tax_rate: { type: :string, example: '0.21', 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: {
+ subject_type: { type: :string, enum: ['Spree::Product', 'Spree::Category', 'Spree::Vendor'] },
+ subject_id: { type: :string, example: 'ven_a1b2c3' }
+ }
+ }
+ }
+ }
+ }
+
+ response '201', 'commission rate created' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:body) { { name: 'Audio sellers', kind: 'percentage', value: 12.5, priority: 10 } }
+
+ schema '$ref' => '#/components/schemas/CommissionRate'
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['name']).to eq('Audio sellers')
+ end
+ end
+
+ response '422', 'validation failed' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ # A flat fee means nothing without a currency to charge it in.
+ let(:body) { { name: 'Flat fee', kind: 'fixed', value: 2 } }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+ end
+
+ path '/api/v3/admin/commission_rates/rule_subject_types' do
+ get 'List what a commission rule may target' do
+ tags 'Commission Rates'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ The subject types a rule may name, so a client can build its picker
+ without hardcoding a list core owns.
+ DESC
+ admin_scope :read, :commissions
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'subject types found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+
+ schema type: :object,
+ properties: {
+ data: {
+ type: :array,
+ items: {
+ type: :object,
+ properties: {
+ type: { type: :string, example: 'Spree::Vendor' },
+ name: { type: :string, example: 'Vendor' }
+ }
+ }
+ }
+ }
+
+ run_test! do |response|
+ data = JSON.parse(response.body)
+ expect(data['data'].pluck('type')).to include('Spree::Vendor')
+ end
+ end
+ end
+ end
+
+ path '/api/v3/admin/commission_rates/{id}' do
+ parameter name: :id, in: :path, type: :string, description: 'Commission rate ID'
+
+ get 'Get a commission rate' do
+ tags 'Commission Rates'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :read, :commissions
+
+ admin_sdk_example 'commission_rates/get'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '200', 'commission rate found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { commission_rate.prefixed_id }
+
+ schema '$ref' => '#/components/schemas/CommissionRate'
+
+ run_test!
+ end
+
+ response '404', 'commission rate not found' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { 'comrt_nonexistent' }
+
+ schema '$ref' => '#/components/schemas/ErrorResponse'
+
+ run_test!
+ end
+ end
+
+ patch 'Update a commission rate' do
+ tags 'Commission Rates'
+ consumes 'application/json'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ description <<~DESC
+ Editing a rate changes what the next sale is charged, never what a past
+ one was: commission lines keep their own snapshot of the rate that
+ applied.
+ DESC
+ admin_scope :write, :commissions
+
+ admin_sdk_example 'commission_rates/update'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+ parameter name: :body, in: :body, schema: {
+ type: :object,
+ properties: {
+ name: { type: :string, example: 'Standard' },
+ enabled: { type: :boolean, example: true },
+ priority: { type: :integer, example: 20 },
+ value: { type: :string, example: '15.0' },
+ rules: {
+ type: :array,
+ items: {
+ type: :object,
+ properties: {
+ subject_type: { type: :string, example: 'Spree::Category' },
+ subject_id: { type: :string, example: 'ctg_a1b2c3' }
+ }
+ }
+ }
+ }
+ }
+
+ response '200', 'commission rate updated' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { commission_rate.prefixed_id }
+ let(:body) { { value: 15 } }
+
+ schema '$ref' => '#/components/schemas/CommissionRate'
+
+ run_test! do |response|
+ expect(JSON.parse(response.body)['value']).to eq('15.0')
+ end
+ end
+ end
+
+ delete 'Delete a commission rate' do
+ tags 'Commission Rates'
+ produces 'application/json'
+ security [api_key: [], bearer_auth: []]
+ admin_scope :write, :commissions
+
+ admin_sdk_example 'commission_rates/delete'
+
+ parameter name: 'x-spree-api-key', in: :header, type: :string, required: true
+ parameter name: :Authorization, in: :header, type: :string, required: true
+
+ response '204', 'commission rate deleted' do
+ let(:'x-spree-api-key') { secret_api_key.plaintext_token }
+ let(:id) { commission_rate.prefixed_id }
+
+ run_test!
+ end
+ end
+ end
+end
diff --git a/spree/core/app/models/concerns/spree/vat_price_calculation.rb b/spree/core/app/models/concerns/spree/vat_price_calculation.rb
index c72947f39d..7431ca0802 100644
--- a/spree/core/app/models/concerns/spree/vat_price_calculation.rb
+++ b/spree/core/app/models/concerns/spree/vat_price_calculation.rb
@@ -94,7 +94,7 @@ module Spree
end
def round_to_two_places(amount)
- BigDecimal(amount.to_s).round(2, BigDecimal::ROUND_HALF_UP)
+ Spree::Money::Rounding.quantize(amount, 2)
end
end
end
diff --git a/spree/core/app/models/spree/commission_line.rb b/spree/core/app/models/spree/commission_line.rb
new file mode 100644
index 0000000000..9b405f1965
--- /dev/null
+++ b/spree/core/app/models/spree/commission_line.rb
@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Spree
+ # What one sale earned the marketplace, frozen at placement.
+ #
+ # Deliberately **not** a Spree::Fee. A fee is buyer-facing and rolls into the
+ # order total; a commission is a platform↔seller settlement the customer
+ # never sees, so it lives off the order and never touches its totals. It
+ # merely follows the same typed-line design — concrete FKs, no polymorphic
+ # source, no state machine.
+ #
+ # Every field is a snapshot: the rate that applied, what it charged, and the
+ # VAT charged on top of it. Editing the Spree::CommissionRate afterwards
+ # changes nothing here, and neither does deleting it.
+ #
+ # `tax_amount` is the EU piece and the reason this model exists rather than a
+ # single `amount` column: the marketplace's commission is its own taxable B2B
+ # supply to the seller, separate from the consumer's item sale, so the two
+ # VATs are computed independently and never mix.
+ class CommissionLine < Spree.base_class
+ has_prefix_id :comln
+
+ include Spree::Metadata
+
+ #
+ # Associations
+ #
+ belongs_to :order, class_name: 'Spree::Order'
+ belongs_to :vendor, class_name: 'Spree::Vendor'
+ # Exactly one of these: the item that was commissioned, or the delivery,
+ # when the rate carries include_shipping.
+ belongs_to :line_item, class_name: 'Spree::LineItem', optional: true
+ belongs_to :fulfillment, class_name: 'Spree::Fulfillment', optional: true
+ # Optional because configuration outlives its use the other way round: the
+ # rate may be deleted while this record has to stay readable.
+ belongs_to :commission_rate, class_name: 'Spree::CommissionRate', optional: true
+
+ #
+ # Validations
+ #
+ validates :amount, :tax_amount, :total, :rate, numericality: true
+ validates :currency, presence: true
+ validates :kind, presence: true, inclusion: { in: Spree::CommissionRate::KINDS }
+ validate :exactly_one_subject
+
+ #
+ # Scopes
+ #
+ scope :for_line_items, -> { where.not(line_item_id: nil) }
+ scope :for_fulfillments, -> { where.not(fulfillment_id: nil) }
+
+ self.whitelisted_ransackable_attributes = %w[amount tax_amount total currency kind rate]
+ self.whitelisted_ransackable_associations = %w[order vendor commission_rate]
+
+ extend Spree::DisplayMoney
+ money_methods :amount, :tax_amount, :total
+
+ # What this row was charged against.
+ #
+ # @return [Spree::LineItem, Spree::Fulfillment, nil]
+ def subject
+ line_item || fulfillment
+ end
+
+ private
+
+ def exactly_one_subject
+ return if [line_item_id, fulfillment_id].compact.one?
+
+ errors.add(:base, :exactly_one_of_line_item_or_fulfillment)
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/commission_rate.rb b/spree/core/app/models/spree/commission_rate.rb
new file mode 100644
index 0000000000..ccd2e673f2
--- /dev/null
+++ b/spree/core/app/models/spree/commission_rate.rb
@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Spree
+ # What a marketplace charges a seller, as configuration.
+ #
+ # Rates are resolved per line item by walking a store's enabled rates in
+ # `priority` order and taking the first whose rules match
+ # (Spree::Commissions::ResolveRate). A rate with no rules matches
+ # everything, which is how a marketplace expresses a single default without
+ # configuring anything.
+ #
+ # Mutable, unlike the Spree::CommissionLine rows it produces: editing a rate
+ # changes what the next sale is charged and never what a past one was.
+ class CommissionRate < Spree.base_class
+ has_prefix_id :comrt
+
+ acts_as_paranoid
+
+ include Spree::SingleStoreResource
+ include Spree::Metadata
+
+ KINDS = %w[percentage fixed].freeze
+
+ #
+ # Associations
+ #
+ belongs_to :store, class_name: 'Spree::Store'
+ has_many :commission_rules, class_name: 'Spree::CommissionRule', dependent: :destroy, inverse_of: :commission_rate
+ # Nullified rather than destroyed: a commission line is a settlement record
+ # that has to outlive the configuration it came from.
+ has_many :commission_lines, class_name: 'Spree::CommissionLine', dependent: :nullify
+
+ #
+ # Validations
+ #
+ validates :name, presence: true
+ validates :kind, presence: true, inclusion: { in: KINDS }
+ validates :priority, numericality: { only_integer: true }
+ validates :value, numericality: { greater_than_or_equal_to: 0 }
+ validates :code, uniqueness: { scope: [*spree_base_uniqueness_scope, :store_id], case_sensitive: false },
+ allow_blank: true
+ # A flat fee is meaningless without one; a percentage applies in any
+ # currency, so it deliberately carries none.
+ validates :currency, presence: true, if: :fixed?
+ validates :min_amount, :max_amount, :commission_tax_rate,
+ numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+ validate :max_amount_above_min_amount
+
+ #
+ # Scopes
+ #
+ scope :enabled, -> { where(enabled: true) }
+ # The resolution order. Ties break on id so a rate added later never
+ # silently displaces an equal-priority one already in use.
+ scope :by_priority, -> { order(priority: :desc, id: :asc) }
+
+ self.whitelisted_ransackable_attributes = %w[name code kind enabled priority value currency
+ include_tax include_shipping]
+ self.whitelisted_ransackable_associations = %w[commission_rules]
+
+ # @return [Boolean]
+ def percentage?
+ kind == 'percentage'
+ end
+
+ # @return [Boolean]
+ def fixed?
+ kind == 'fixed'
+ end
+
+ # Whether this rate can be charged in the given currency. Only a fixed rate
+ # has an opinion — a percentage is a ratio and travels.
+ #
+ # @param order_currency [String]
+ # @return [Boolean]
+ def applies_to_currency?(order_currency)
+ return true if percentage?
+
+ currency.to_s.casecmp?(order_currency.to_s)
+ end
+
+ # Whether this rate's targeting admits the given subjects.
+ #
+ # Rules are grouped by what they target, and the groups are ANDed while the
+ # rules inside one are ORed: `{category: Cameras, category: Audio, vendor: X}`
+ # reads "(Cameras OR Audio) AND vendor X". A dimension the rate says nothing
+ # about is not a constraint, so a vendor-only rate matches that vendor's
+ # every product.
+ #
+ # @param subjects [Hash{String=>Array}] subject type => the sale's records
+ # of that type, e.g. `{'Spree::Vendor' => [vendor], 'Spree::Category' => [...]}`
+ # @return [Boolean]
+ def matches_subjects?(subjects)
+ rules_by_type = commission_rules.reject(&:global?).group_by(&:subject_type)
+ return true if rules_by_type.empty?
+
+ rules_by_type.all? do |subject_type, rules|
+ candidate_ids = Array(subjects[subject_type]).compact.map { |record| record.try(:id) || record }.map(&:to_s)
+ rules.any? { |rule| candidate_ids.include?(rule.subject_id.to_s) }
+ end
+ end
+
+ # The flat payload the admin API writes: `[{subject_type:, subject_id:}]`,
+ # replacing the rate's rules wholesale. Ids are already store-checked by
+ # the controller, which is where the tenancy boundary belongs.
+ #
+ # @param rows [Array<Hash>, nil]
+ # @return [void]
+ def rules=(rows)
+ self.commission_rules = Array(rows).map do |row|
+ attributes = row.to_h.with_indifferent_access
+ commission_rules.build(
+ subject_type: attributes[:subject_type].presence,
+ subject_id: attributes[:subject_id].presence
+ )
+ end
+ end
+
+ private
+
+ def max_amount_above_min_amount
+ return if max_amount.nil? || min_amount.nil?
+ return if max_amount >= min_amount
+
+ errors.add(:max_amount, :must_be_greater_than_min_amount)
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/commission_rule.rb b/spree/core/app/models/spree/commission_rule.rb
new file mode 100644
index 0000000000..1088267504
--- /dev/null
+++ b/spree/core/app/models/spree/commission_rule.rb
@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Spree
+ # One targeting clause on a Spree::CommissionRate: this rate applies to this
+ # product, this category, or this seller.
+ #
+ # Not STI, unlike the promotion and price rules: a commission rule carries no
+ # behavior of its own and no preferences — it names a record, and matching is
+ # set membership. The dimension it constrains is its `subject_type`, so
+ # adding one (a channel, a market) needs no new class.
+ #
+ # A rule with no subject is a global one, which reads the same as a rate
+ # holding no rules at all; both match every sale.
+ class CommissionRule < Spree.base_class
+ has_prefix_id :comrl
+
+ SUBJECT_TYPES = %w[Spree::Product Spree::Category Spree::Vendor].freeze
+
+ belongs_to :commission_rate, class_name: 'Spree::CommissionRate', inverse_of: :commission_rules
+ belongs_to :subject, polymorphic: true, optional: true
+
+ validates :subject_type, inclusion: { in: SUBJECT_TYPES }, allow_blank: true
+ validates :subject_id, presence: true, if: -> { subject_type.present? }
+ validates :subject_type, presence: true, if: -> { subject_id.present? }
+ validates :subject_id, uniqueness: { scope: [:commission_rate_id, :subject_type] }, allow_nil: true
+
+ # @return [Boolean]
+ def global?
+ subject_type.blank? || subject_id.blank?
+ end
+ end
+end
diff --git a/spree/core/app/models/spree/order.rb b/spree/core/app/models/spree/order.rb
index 6cf75c6596..7d1da8a2ed 100644
--- a/spree/core/app/models/spree/order.rb
+++ b/spree/core/app/models/spree/order.rb
@@ -182,6 +182,11 @@ module Spree
has_many :discounts, class_name: 'Spree::Discount', dependent: :destroy, inverse_of: :order
has_many :fees, class_name: 'Spree::Fee', dependent: :destroy, inverse_of: :order
+ # What the marketplace charged its sellers on this order. Off-order by
+ # design: commission never reaches a total the customer pays, so this is a
+ # ledger the order merely hosts. See docs/plans/6.0-multi-vendor-marketplace.md.
+ has_many :commission_lines, class_name: 'Spree::CommissionLine', dependent: :destroy, inverse_of: :order
+
has_many :line_item_tax_lines, through: :line_items, source: :tax_lines
has_many :line_item_discounts, through: :line_items, source: :discounts
diff --git a/spree/core/app/models/spree/store.rb b/spree/core/app/models/spree/store.rb
index 27af1ef920..7e017f3b37 100644
--- a/spree/core/app/models/spree/store.rb
+++ b/spree/core/app/models/spree/store.rb
@@ -60,6 +60,12 @@ module Spree
# be silenced — a marketplace fronting its own seller comms turns these off
# without also stopping customer receipts.
preference :send_vendor_transactional_emails, :boolean, default: true
+ # Marketplace preferences
+ #
+ # VAT on the commission itself, as a fraction, when neither the rate nor
+ # the tax provider names one. Zero by default: a marketplace outside the EU
+ # charges no tax on its fee, and inventing one would overcharge sellers.
+ preference :default_commission_tax_rate, :decimal, default: 0
# Checkout preferences
# Store-level fallback for the channel-owned `guest_checkout` preference
# (see Spree::Channel::Gating). Retained so existing accessors keep working.
@@ -178,6 +184,9 @@ module Spree
has_many :tax_categories, class_name: 'Spree::TaxCategory', dependent: :destroy, inverse_of: :store
has_many :tax_rates, class_name: 'Spree::TaxRate', dependent: :destroy, inverse_of: :store
+ has_many :vendors, class_name: 'Spree::Vendor', dependent: :destroy, inverse_of: :store
+ has_many :commission_rates, class_name: 'Spree::CommissionRate', dependent: :destroy, inverse_of: :store
+
has_many :wishlists, class_name: 'Spree::Wishlist'
has_many :data_feeds, class_name: 'Spree::DataFeed'
diff --git a/spree/core/app/models/spree/tax_provider/base.rb b/spree/core/app/models/spree/tax_provider/base.rb
index 57c905e85f..83387ad59f 100644
--- a/spree/core/app/models/spree/tax_provider/base.rb
+++ b/spree/core/app/models/spree/tax_provider/base.rb
@@ -107,6 +107,27 @@ module Spree
# @return [void]
def void(order); end
+ # The tax rate, as a fraction, on a service the platform itself supplies
+ # and invoices — today only a marketplace's commission to a seller.
+ #
+ # Distinct from +estimate+ because nothing here is a sale: there is no
+ # order, no buyer and no item, only a B2B supply between the platform and
+ # a business it invoices. Returning a rate rather than writing rows is
+ # deliberate for the same reason — the caller snapshots the number onto
+ # its own ledger row, which is not a TaxLine.
+ #
+ # Providers that cannot price a service supply return nil rather than
+ # zero: zero is the claim that the supply is untaxed, and the caller has
+ # a configured default to fall back on that a wrong zero would silence.
+ #
+ # @param address [Spree::Address, nil] where the business being invoiced
+ # is established — for commission, the seller's billing address
+ # @param store [Spree::Store]
+ # @return [BigDecimal, nil] e.g. 0.21 for 21%; nil if it has no opinion
+ def service_tax_rate(address:, store:)
+ nil
+ end
+
# Reports a partial credit against the committed document, keyed to the
# original transaction rather than voiding and re-committing it.
#
diff --git a/spree/core/app/models/spree/tax_provider/internal.rb b/spree/core/app/models/spree/tax_provider/internal.rb
index 5c2d7ee4f9..21b60f9ba5 100644
--- a/spree/core/app/models/spree/tax_provider/internal.rb
+++ b/spree/core/app/models/spree/tax_provider/internal.rb
@@ -67,6 +67,34 @@ module Spree
end
end
+ # Reads the service rate off the same TaxRate configuration as everything
+ # else, matched on where the invoiced business sits and taxed under the
+ # store's default category — this engine has no separate notion of a
+ # services category, and a marketplace commission is standard-rated
+ # nearly everywhere.
+ #
+ # Additional (not included-in-price) rates only: a commission is quoted
+ # net and its VAT is added on top, so a rate configured as
+ # tax-inclusive describes consumer pricing rather than this supply.
+ #
+ # Nil when the jurisdiction is unknown or configured with no matching
+ # rate at all, so the caller falls back to its own default instead of
+ # reading silence as "not taxed".
+ def service_tax_rate(address:, store:)
+ return nil if address&.country_code.blank?
+
+ category = default_tax_category_for(store)
+ return nil if category.nil?
+
+ rates = Spree::TaxRate.for_store(store).
+ for_jurisdiction(address.country_code, address.state_code).
+ for_tax_category(category).
+ where(included_in_price: false)
+ return nil if rates.empty?
+
+ rates.sum(:amount)
+ end
+
private
# Scoped to this engine's own rows: a landed-cost provider writes the
@@ -92,17 +120,22 @@ module Spree
if item.respond_to?(:tax_category_id) && item.tax_category_id
item.tax_category_id
else
- default_tax_category(owner)&.id
+ default_tax_category_for(owner.store)&.id
end
end
- # The owner's store's default, not any store's: defaults are per store
+ # The given store's default, not any store's: defaults are per store
# since 6.0, and a foreign category id would match none of this store's
# rates, silently leaving the item untaxed.
- def default_tax_category(owner)
- return @default_tax_category if defined?(@default_tax_category)
-
- @default_tax_category = Spree::TaxCategory.default(owner.store)
+ #
+ # Memoized per store rather than per provider, since one provider
+ # instance answers for a whole order — and, on a marketplace, for each of
+ # its sellers in turn.
+ def default_tax_category_for(store)
+ @default_tax_categories ||= {}
+ return @default_tax_categories[store.id] if @default_tax_categories.key?(store.id)
+
+ @default_tax_categories[store.id] = Spree::TaxCategory.default(store)
end
def taxable_basis(item)
diff --git a/spree/core/app/models/spree/vendor.rb b/spree/core/app/models/spree/vendor.rb
index aa23b3c467..f066bbbec7 100644
--- a/spree/core/app/models/spree/vendor.rb
+++ b/spree/core/app/models/spree/vendor.rb
@@ -87,6 +87,12 @@ module Spree
# happens to a departed seller's catalog, so it is never cascade-deleted.
has_many :products, class_name: 'Spree::Product', dependent: :nullify
+ # What this seller has been charged. Deliberately neither destroyed nor
+ # nullified when the vendor goes: a vendor is paranoid, so it is still
+ # there to be read, and a settlement record that forgot who owed it would
+ # be worse than no record at all.
+ has_many :commission_lines, class_name: 'Spree::CommissionLine', dependent: nil
+
#
# Attachments
#
diff --git a/spree/core/app/services/spree/commissions/calculate_line.rb b/spree/core/app/services/spree/commissions/calculate_line.rb
new file mode 100644
index 0000000000..d8738f985f
--- /dev/null
+++ b/spree/core/app/services/spree/commissions/calculate_line.rb
@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Spree
+ module Commissions
+ # Works out what one commission line is worth, and builds it.
+ #
+ # Two amounts, computed independently, because they are two different
+ # supplies. `amount` is the platform's fee, charged on what the seller sold.
+ # `tax_amount` is VAT on that fee — the marketplace's own taxable service to
+ # the seller, which is why it is applied *on top* rather than taken out of
+ # the item's own VAT. Keeping them apart is what lets a marketplace invoice
+ # its commission properly in the EU, and it is the reason the base defaults
+ # to the seller's **net** price: mixing the consumer's VAT into the fee base
+ # would tax the same money twice under two different regimes.
+ #
+ # The returned record is not saved — the caller persists it inside whatever
+ # transaction is placing the order.
+ #
+ # Swap through +Spree.commissions_calculate_line_service+.
+ class CalculateLine
+ prepend Spree::ServiceModule::Base
+
+ # @param rate [Spree::CommissionRate] the resolved rate
+ # @param vendor [Spree::Vendor] the seller being charged
+ # @param order [Spree::Order]
+ # @param line_item [Spree::LineItem, nil] the commissioned item…
+ # @param fulfillment [Spree::Fulfillment, nil] …or the commissioned delivery
+ # @param commission_tax_rate [BigDecimal, nil] pre-resolved VAT fraction,
+ # so commissioning a whole order resolves it once
+ # @return [Spree::CommissionLine] unsaved
+ def call(rate:, vendor:, order:, line_item: nil, fulfillment: nil, commission_tax_rate: nil)
+ subject = line_item || fulfillment
+ return failure(nil, 'a commission line needs a line item or a fulfillment') if subject.nil?
+
+ currency = order.currency
+ precision = Spree::Money::Rounding.precision(currency)
+ tax_rate = commission_tax_rate || resolve_tax_rate(rate: rate, vendor: vendor, order: order)
+
+ amount = Spree::Money::Rounding.quantize(charge_for(rate, subject), precision)
+ tax_amount = Spree::Money::Rounding.quantize(amount * tax_rate, precision)
+
+ success(
+ Spree::CommissionLine.new(
+ order: order,
+ vendor: vendor,
+ line_item: line_item,
+ fulfillment: fulfillment,
+ commission_rate: rate,
+ kind: rate.kind,
+ rate: rate.value,
+ amount: amount,
+ tax_amount: tax_amount,
+ # Summed from the two rounded parts rather than rounded again, so a
+ # marketplace's ledger reconciles with its payouts to the cent.
+ total: amount + tax_amount,
+ currency: currency
+ )
+ )
+ end
+
+ private
+
+ # A fixed rate is a flat fee for the sale, charged once however many units
+ # it covered — quantity is what a percentage already accounts for through
+ # the base.
+ def charge_for(rate, subject)
+ return clamp(rate, rate.value) if rate.fixed?
+
+ clamp(rate, base_for(rate, subject) * rate.value / 100)
+ end
+
+ # The seller's own revenue on this row, net of VAT unless the rate opts
+ # into a gross base. Discounts come off either way — `taxable_basis` is
+ # already the discounted, never-negative figure both line items and
+ # fulfillments agree on — because commission is charged on what the
+ # customer actually paid, and a promotion is the seller's concession in v1.
+ #
+ # Which VAT column matters depends on how the store prices: a
+ # tax-inclusive price carries VAT inside it, which a net base removes,
+ # while a tax-exclusive one carries none, so only a gross base adds any.
+ def base_for(rate, subject)
+ basis = subject.taxable_basis
+
+ base = if rate.include_tax?
+ basis + subject.additional_tax_total.to_d
+ else
+ basis - subject.included_tax_total.to_d
+ end
+
+ [base, BigDecimal(0)].max
+ end
+
+ def clamp(rate, amount)
+ amount = [amount, rate.min_amount].max if rate.min_amount.present?
+ amount = [amount, rate.max_amount].min if rate.max_amount.present?
+ amount
+ end
+
+ def resolve_tax_rate(rate:, vendor:, order:)
+ Spree.commissions_resolve_tax_rate_service.call(rate: rate, vendor: vendor, order: order).value
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/commissions/commission_order.rb b/spree/core/app/services/spree/commissions/commission_order.rb
new file mode 100644
index 0000000000..451fe82c45
--- /dev/null
+++ b/spree/core/app/services/spree/commissions/commission_order.rb
@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Spree
+ module Commissions
+ # Writes an order's commission lines: one per sold item, plus one per
+ # fulfillment when the rate charges delivery too.
+ #
+ # Runs once, at placement, and is idempotent — an order that already
+ # carries commission is left exactly as it is. Both matter because the
+ # lines are a settlement record: recomputing them later would let a rate
+ # edit rewrite what a seller was already told they owed, and a replayed
+ # placement would charge them twice.
+ #
+ # Lines are grouped by the seller each item was bought from, which is
+ # `line_item.vendor_id` — the snapshot frozen when the order was placed,
+ # not whoever owns the product today. Items with no seller are the
+ # marketplace's own and are not commissioned.
+ #
+ # It runs inside the customer's checkout, so everything it reads is loaded
+ # up front: the sellers, their billing addresses (the tax question is asked
+ # against those), the products behind each line, and the order's
+ # fulfillments — each once for the whole order rather than once per line.
+ #
+ # Swap through +Spree.commissions_commission_order_service+.
+ class CommissionOrder
+ prepend Spree::ServiceModule::Base
+
+ # @param order [Spree::Order]
+ # @return [Array<Spree::CommissionLine>] the lines written, empty when
+ # there was nothing to commission
+ def call(order:)
+ return success([]) if order.commission_lines.exists?
+
+ commissioned = order.line_items.
+ includes(vendor: :billing_address, variant: { product: :categories }).
+ select(&:vendor_id)
+ return success([]) if commissioned.empty?
+
+ rates = Spree::Commissions::ResolveRate.candidates_for(order.store)
+ categories = Spree::Commissions::ResolveRate.categories_for(
+ commissioned.map { |line_item| line_item.variant&.product }
+ )
+ deliveries = deliveries_by_vendor(order)
+ lines = []
+
+ Spree::CommissionLine.transaction do
+ commissioned.group_by(&:vendor_id).each_value do |line_items|
+ lines.concat(
+ commission_vendor(
+ order: order, vendor: line_items.first.vendor, line_items: line_items,
+ rates: rates, categories: categories, deliveries: deliveries
+ )
+ )
+ end
+ end
+
+ success(lines)
+ end
+
+ private
+
+ def commission_vendor(order:, vendor:, line_items:, rates:, categories:, deliveries:)
+ matched = line_items.filter_map do |line_item|
+ rate = resolve(line_item: line_item, vendor: vendor, order: order, rates: rates, categories: categories)
+ [line_item, rate] if rate
+ end
+ return [] if matched.empty?
+
+ # Memoized per rate rather than per line. Where the seller's business
+ # sits is the same question every time — so a basket governed by one
+ # rate asks the tax service once — but a rate may carry its own
+ # override, so two rates are still two answers.
+ tax_rates = Hash.new do |cache, rate|
+ cache[rate] = resolve_tax_rate(rate: rate, vendor: vendor, order: order)
+ end
+
+ lines = matched.map do |line_item, rate|
+ write(rate: rate, vendor: vendor, order: order, line_item: line_item, tax_rate: tax_rates[rate])
+ end
+
+ # A fulfillment carries goods, not a rate, so the one that governs
+ # delivery is whichever of the seller's matched rates asked for it.
+ shipping_rate = matched.map(&:last).find(&:include_shipping?)
+ return lines if shipping_rate.nil?
+
+ deliveries.fetch(vendor.id, []).each do |fulfillment|
+ next if fulfillment.taxable_basis.zero?
+
+ lines << write(rate: shipping_rate, vendor: vendor, order: order,
+ fulfillment: fulfillment, tax_rate: tax_rates[shipping_rate])
+ end
+
+ lines
+ end
+
+ # The order's fulfillments, keyed by the seller whose goods they carry.
+ #
+ # Read off each fulfillment's own line items rather than assumed from the
+ # order, because until the split lands an order still holds every
+ # seller's goods — and a delivery carrying two sellers' items belongs to
+ # neither of them alone. Charging both would bill one parcel twice, and
+ # picking one would bill the wrong seller, so a shared delivery is
+ # dropped here and stays uncommissioned until splitting gives each seller
+ # their own. Once it does, every fulfillment is single-seller by
+ # construction and this becomes the plain "the seller's deliveries".
+ #
+ # @return [Hash{Integer=>Array<Spree::Fulfillment>}]
+ def deliveries_by_vendor(order)
+ order.fulfillments.includes(fulfillment_items: :line_item).group_by do |fulfillment|
+ sellers = fulfillment.fulfillment_items.map { |item| item.line_item&.vendor_id }.uniq
+
+ sellers.one? ? sellers.first : nil
+ end.except(nil)
+ end
+
+ def resolve(line_item:, vendor:, order:, rates:, categories:)
+ Spree.commissions_resolve_rate_service.call(
+ line_item: line_item, vendor: vendor, store: order.store, currency: order.currency,
+ rates: rates, categories: categories
+ ).value
+ end
+
+ def resolve_tax_rate(rate:, vendor:, order:)
+ Spree.commissions_resolve_tax_rate_service.call(rate: rate, vendor: vendor, order: order).value
+ end
+
+ def write(rate:, vendor:, order:, tax_rate:, line_item: nil, fulfillment: nil)
+ line = Spree.commissions_calculate_line_service.call(
+ rate: rate, vendor: vendor, order: order,
+ line_item: line_item, fulfillment: fulfillment, commission_tax_rate: tax_rate
+ ).value
+ line.save!
+ line
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/commissions/resolve_rate.rb b/spree/core/app/services/spree/commissions/resolve_rate.rb
new file mode 100644
index 0000000000..6734281206
--- /dev/null
+++ b/spree/core/app/services/spree/commissions/resolve_rate.rb
@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Spree
+ module Commissions
+ # Picks the commission rate that governs one line item.
+ #
+ # Walks the store's enabled rates from highest priority down and takes the
+ # first whose targeting admits the sale. Precedence is therefore an integer
+ # the operator assigns, not a hardcoded product-beats-category-beats-seller
+ # ladder: the seeded rates order themselves so a marketplace that never
+ # touches priorities still gets the conventional answer, and one that needs
+ # a different order just reorders.
+ #
+ # Returns nil when nothing matches, which is a real answer — a marketplace
+ # with no rate for a sale charges no commission, rather than falling back
+ # to some default the operator never configured.
+ #
+ # Swap through +Spree.commissions_resolve_rate_service+.
+ class ResolveRate
+ prepend Spree::ServiceModule::Base
+
+ # @param line_item [Spree::LineItem] the sale being commissioned
+ # @param vendor [Spree::Vendor] its seller
+ # @param store [Spree::Store]
+ # @param currency [String] the order's currency
+ # @param rates [Array<Spree::CommissionRate>, nil] pre-loaded candidates,
+ # so commissioning a whole order reads the table once instead of once
+ # per line
+ # @param categories [Hash{Integer=>Array<Spree::Category>}, nil] each
+ # product's categories with their ancestors, resolved once for the
+ # order — see .categories_for
+ # @return [Spree::CommissionRate, nil]
+ def call(line_item:, vendor:, store:, currency: nil, rates: nil, categories: nil)
+ currency ||= line_item.currency
+ candidates = rates || self.class.candidates_for(store)
+ subjects = subjects_for(line_item, vendor, categories)
+
+ success(
+ candidates.find do |rate|
+ rate.applies_to_currency?(currency) && rate.matches_subjects?(subjects)
+ end
+ )
+ end
+
+ # The store's rates in resolution order, with rules preloaded — matching
+ # reads every rule of every candidate, so without this each rate costs a
+ # query per line item.
+ #
+ # @param store [Spree::Store]
+ # @return [Array<Spree::CommissionRate>]
+ def self.candidates_for(store)
+ store.commission_rates.enabled.by_priority.includes(:commission_rules).to_a
+ end
+
+ # Each product's categories together with their ancestors, keyed by
+ # product id.
+ #
+ # Resolved for a whole set of products at once because walking a nested
+ # set is a query per category, and this runs inside checkout: asking per
+ # line item would cost a query for every category of every item in the
+ # basket, most of them the same ones over and over.
+ #
+ # @param products [Array<Spree::Product>]
+ # @return [Hash{Integer=>Array<Spree::Category>}]
+ def self.categories_for(products)
+ products = products.compact.uniq
+ return {} if products.empty?
+
+ by_product = products.to_h { |product| [product.id, product.categories.to_a] }
+ ancestors = ancestors_of(by_product.values.flatten.uniq)
+
+ by_product.transform_values do |categories|
+ categories.flat_map { |category| ancestors.fetch(category.id, [category]) }.uniq
+ end
+ end
+
+ # Every category above each of the given ones, in one query per store
+ # rather than one per category. Nested sets make an ancestor a plain
+ # range comparison, so the whole set can be asked for at once.
+ #
+ # @param categories [Array<Spree::Category>]
+ # @return [Hash{Integer=>Array<Spree::Category>}]
+ def self.ancestors_of(categories)
+ return {} if categories.empty?
+
+ table = Spree::Category.arel_table
+ within_store = categories.group_by(&:store_id).map do |store_id, group|
+ reaching = group.map { |c| table[:lft].lteq(c.lft).and(table[:rgt].gteq(c.rgt)) }.reduce(:or)
+ Spree::Category.where(store_id: store_id).where(reaching)
+ end
+ pool = within_store.flat_map(&:to_a)
+
+ categories.to_h do |category|
+ [category.id, pool.select { |node| node.lft <= category.lft && node.rgt >= category.rgt }]
+ end
+ end
+
+ private
+
+ # What this sale offers a rule to match on. Categories include ancestors,
+ # so a rate targeting "Electronics" also governs a camera filed under
+ # "Electronics → Cameras" — the alternative would make a merchant restate
+ # every leaf whenever they add one.
+ def subjects_for(line_item, vendor, categories)
+ product = line_item.variant&.product
+
+ {
+ 'Spree::Vendor' => [vendor],
+ 'Spree::Product' => [product].compact,
+ 'Spree::Category' => product_categories(product, categories)
+ }
+ end
+
+ def product_categories(product, categories)
+ return [] if product.nil?
+ return categories.fetch(product.id, []) if categories
+
+ self.class.categories_for([product]).fetch(product.id, [])
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/commissions/resolve_tax_rate.rb b/spree/core/app/services/spree/commissions/resolve_tax_rate.rb
new file mode 100644
index 0000000000..757b9d52a2
--- /dev/null
+++ b/spree/core/app/services/spree/commissions/resolve_tax_rate.rb
@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Spree
+ module Commissions
+ # The VAT charged on a commission, as a fraction.
+ #
+ # This is tax on the marketplace's own service to the seller, not on the
+ # goods the customer bought — a separate supply with its own place of
+ # taxation, which is why it is asked against the **seller's billing
+ # address** rather than wherever the parcel went.
+ #
+ # Precedence: an explicit override on the rate, else the sale's tax engine,
+ # else the store's default. A provider with no opinion returns nil rather
+ # than zero, so silence falls through to the default instead of being read
+ # as "this fee is untaxed".
+ #
+ # Swap through +Spree.commissions_resolve_tax_rate_service+.
+ class ResolveTaxRate
+ prepend Spree::ServiceModule::Base
+
+ # @param rate [Spree::CommissionRate]
+ # @param vendor [Spree::Vendor] the seller being invoiced
+ # @param order [Spree::Order]
+ # @return [BigDecimal] e.g. 0.21 for 21%
+ def call(rate:, vendor:, order:)
+ return success(rate.commission_tax_rate.to_d) if rate.commission_tax_rate.present?
+
+ from_provider = provider_rate(vendor: vendor, order: order)
+ return success(from_provider.to_d) if from_provider.present?
+
+ success(order.store.preferred_default_commission_tax_rate.to_d)
+ end
+
+ private
+
+ # Commission is written while an order is being placed, so a tax service
+ # being unreachable must never cost the marketplace a checkout: the error
+ # is reported and the configured default applies.
+ def provider_rate(vendor:, order:)
+ order.tax_provider.service_tax_rate(address: vendor.billing_address, store: order.store)
+ rescue StandardError => error
+ Rails.error.report(
+ error,
+ handled: true,
+ context: { vendor_id: vendor.id, order_id: order.id },
+ source: 'spree.core'
+ )
+ nil
+ end
+ end
+ end
+end
diff --git a/spree/core/app/services/spree/orders/update_statuses.rb b/spree/core/app/services/spree/orders/update_statuses.rb
index 9e65f5ef5c..be75cc2f34 100644
--- a/spree/core/app/services/spree/orders/update_statuses.rb
+++ b/spree/core/app/services/spree/orders/update_statuses.rb
@@ -73,7 +73,7 @@ module Spree
end
def quantize(amount, precision)
- BigDecimal(amount.to_s).round(precision)
+ Spree::Money::Rounding.quantize(amount, precision)
end
end
end
diff --git a/spree/core/app/subscribers/spree/order_commission_subscriber.rb b/spree/core/app/subscribers/spree/order_commission_subscriber.rb
new file mode 100644
index 0000000000..f254807026
--- /dev/null
+++ b/spree/core/app/subscribers/spree/order_commission_subscriber.rb
@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Spree
+ # Charges commission once an order is placed.
+ #
+ # Synchronous, like the other placement side effects, because the commission
+ # lines are what a seller is told they owe: a marketplace that showed an
+ # order before its commission existed would be showing an incomplete book,
+ # and the work is a handful of rows against already-loaded records.
+ #
+ # Idempotency is the service's own — an order that already carries commission
+ # is left alone — so a replayed event cannot charge a seller twice.
+ class OrderCommissionSubscriber < Spree::Subscriber
+ subscribes_to 'order.placed', async: false
+
+ def handle(event)
+ order = Spree::Order.find_by_prefix_id(event.payload['id'])
+ return unless order
+
+ Spree.commissions_commission_order_service.call(order: order)
+ end
+ end
+end
diff --git a/spree/core/db/migrate/20260816210001_create_spree_commission_rates.rb b/spree/core/db/migrate/20260816210001_create_spree_commission_rates.rb
new file mode 100644
index 0000000000..ce66140055
--- /dev/null
+++ b/spree/core/db/migrate/20260816210001_create_spree_commission_rates.rb
@@ -0,0 +1,62 @@
+class CreateSpreeCommissionRates < ActiveRecord::Migration[8.1]
+ def change
+ create_table :spree_commission_rates do |t|
+ t.references :store, null: false
+ t.string :name, null: false
+ t.string :code
+ t.boolean :enabled, null: false, default: true
+ # Walked DESC when resolving, first match wins. Operator-assignable, so
+ # a marketplace reorders its own ladder instead of inheriting one.
+ t.integer :priority, null: false, default: 0
+
+ t.string :kind, null: false # percentage | fixed
+ t.decimal :value, precision: 10, scale: 5, null: false, default: 0
+ # Required for a fixed rate (a flat "2" means nothing without one),
+ # ignored for a percentage.
+ t.string :currency
+
+ # Commission base: net (ex-VAT) item price by default, which is the EU
+ # rule — the fee is a separate supply from the consumer's item sale.
+ t.boolean :include_tax, null: false, default: false
+ # Also commission the vendor order's delivery revenue.
+ t.boolean :include_shipping, null: false, default: false
+
+ t.decimal :min_amount, precision: 10, scale: 2
+ t.decimal :max_amount, precision: 10, scale: 2
+
+ # Overrides the tax provider's answer for VAT on the commission. Null
+ # means ask the provider, which is what keeps the rate jurisdiction-correct.
+ t.decimal :commission_tax_rate, precision: 8, scale: 5
+
+ if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+
+ t.timestamps
+ t.datetime :deleted_at
+ end
+
+ # Deleted rows are excluded, matching the model's own uniqueness check:
+ # rates are paranoid, so without this a store could never reuse the code of
+ # a rate it had retired.
+ add_index :spree_commission_rates, [:store_id, :code], unique: true, where: 'deleted_at IS NULL'
+ add_index :spree_commission_rates, [:store_id, :enabled, :priority]
+ add_index :spree_commission_rates, :deleted_at
+
+ create_table :spree_commission_rules do |t|
+ t.references :commission_rate, null: false
+ # Product | Category | Vendor. Null on every column means a global rule,
+ # which is how a rate with no targeting matches everything.
+ t.references :subject, polymorphic: true
+
+ t.timestamps
+ end
+
+ add_index :spree_commission_rules,
+ [:commission_rate_id, :subject_type, :subject_id],
+ unique: true,
+ name: 'index_commission_rules_on_rate_and_subject'
+ end
+end
diff --git a/spree/core/db/migrate/20260816210002_create_spree_commission_lines.rb b/spree/core/db/migrate/20260816210002_create_spree_commission_lines.rb
new file mode 100644
index 0000000000..d92da8b070
--- /dev/null
+++ b/spree/core/db/migrate/20260816210002_create_spree_commission_lines.rb
@@ -0,0 +1,50 @@
+class CreateSpreeCommissionLines < ActiveRecord::Migration[8.1]
+ def change
+ create_table :spree_commission_lines do |t|
+ t.references :order, null: false
+ t.references :vendor, null: false
+ # Exactly one of these two: the commissioned item, or the commissioned
+ # delivery when the rate carries include_shipping. Their indexes are
+ # declared below, unique.
+ t.references :line_item, index: false
+ t.references :fulfillment, index: false
+ # Nullable: the rate is mutable config and may be deleted long after the
+ # sale, but the line's snapshot below stays the record either way.
+ t.references :commission_rate
+
+ # Snapshot of what was applied, frozen at placement. A later rate change
+ # never reaches an existing line.
+ t.decimal :rate, precision: 8, scale: 5, null: false, default: 0
+ t.string :kind, null: false # percentage | fixed
+ # What the platform charges the seller.
+ t.decimal :amount, precision: 10, scale: 2, null: false, default: 0
+ # VAT on that commission — a separate B2B supply from the item sale.
+ t.decimal :tax_amount, precision: 10, scale: 2, null: false, default: 0
+ t.decimal :total, precision: 10, scale: 2, null: false, default: 0
+ t.string :currency, null: false
+
+ if t.respond_to?(:jsonb)
+ t.jsonb :metadata
+ else
+ t.json :metadata
+ end
+
+ t.timestamps
+
+ # Written portably rather than with num_nonnulls: the same schema has to
+ # build on MySQL and SQLite.
+ t.check_constraint '(line_item_id IS NULL) <> (fulfillment_id IS NULL)',
+ name: 'chk_spree_commission_lines_one_subject'
+ end
+
+ add_index :spree_commission_lines, [:vendor_id, :created_at]
+ # One commission per item, and per fulfillment, so a replayed placement
+ # cannot double-charge a seller. Plain unique indexes rather than partial
+ # ones: every adapter treats NULLs as distinct here, so the rows carrying
+ # the other subject never collide.
+ add_index :spree_commission_lines, :line_item_id, unique: true,
+ name: 'index_commission_lines_on_line_item'
+ add_index :spree_commission_lines, :fulfillment_id, unique: true,
+ name: 'index_commission_lines_on_fulfillment'
+ end
+end
diff --git a/spree/core/lib/spree/core/dependencies.rb b/spree/core/lib/spree/core/dependencies.rb
index 470aba45a1..44610f9428 100644
--- a/spree/core/lib/spree/core/dependencies.rb
+++ b/spree/core/lib/spree/core/dependencies.rb
@@ -110,6 +110,14 @@ module Spree
vendor_suspend_workflow: 'Spree::Vendors::Suspend',
vendor_reject_workflow: 'Spree::Vendors::Reject',
+ # commissions — what a marketplace charges its sellers. Swappable
+ # because the pricing of a marketplace's own service is exactly the
+ # kind of policy an operator replaces wholesale.
+ commissions_resolve_rate_service: 'Spree::Commissions::ResolveRate',
+ commissions_resolve_tax_rate_service: 'Spree::Commissions::ResolveTaxRate',
+ commissions_calculate_line_service: 'Spree::Commissions::CalculateLine',
+ commissions_commission_order_service: 'Spree::Commissions::CommissionOrder',
+
tax_exemption_certificate_verify_workflow: 'Spree::TaxExemptionCertificates::Verify',
# customers
diff --git a/spree/core/lib/spree/core/engine.rb b/spree/core/lib/spree/core/engine.rb
index 637eea7bbf..3cfed7f511 100644
--- a/spree/core/lib/spree/core/engine.rb
+++ b/spree/core/lib/spree/core/engine.rb
@@ -497,6 +497,7 @@ module Spree
# survives Zeitwerk code reloads in development.
Spree.subscribers.concat [
Spree::OrderPlacedSubscriber,
+ Spree::OrderCommissionSubscriber,
Spree::OrderStatusSubscriber,
Spree::ExportSubscriber,
Spree::ReportSubscriber,
diff --git a/spree/core/lib/spree/core/permission_configuration.rb b/spree/core/lib/spree/core/permission_configuration.rb
index 46f1c5cdd1..816dd77260 100644
--- a/spree/core/lib/spree/core/permission_configuration.rb
+++ b/spree/core/lib/spree/core/permission_configuration.rb
@@ -342,6 +342,14 @@ module Spree
# administering other sellers is the one thing this key must not allow.
register_resource(:vendors, group: :access, subjects: -> { [Spree::Vendor] })
+ # What the marketplace charges its sellers. Its own resource rather than
+ # part of `settings`, and closed to the vendor audience for the same
+ # reason `vendors` is: a seller must never be able to read, let alone
+ # set, what anyone is charged.
+ register_resource(:commissions, group: :access, subjects: -> {
+ [Spree::CommissionRate, Spree::CommissionRule, Spree::CommissionLine]
+ })
+
# A seller editing their own record: profile, branding, addresses,
# onboarding.
#
diff --git a/spree/core/lib/spree/money.rb b/spree/core/lib/spree/money.rb
index 8a1e7b24ef..82c7bf8414 100644
--- a/spree/core/lib/spree/money.rb
+++ b/spree/core/lib/spree/money.rb
@@ -5,6 +5,46 @@ Money.rounding_mode = BigDecimal::ROUND_HALF_UP
module Spree
class Money
+ # How Spree rounds an amount to a currency.
+ #
+ # Lives here beside the rounding mode above because "how much is this worth
+ # in this currency" is one answer a store should give consistently — the
+ # same two lines had otherwise been written out wherever a service needed
+ # them, each copy free to drift.
+ module Rounding
+ module_function
+
+ # The number of decimal places a currency is written in: 2 for most, 0
+ # for yen, 3 for dinar. An unknown currency falls back to two places
+ # rather than raising — a sale is not the moment to discover a typo in a
+ # currency code.
+ #
+ # @param currency [String, ::Money::Currency, nil]
+ # @return [Integer]
+ def precision(currency)
+ (::Money::Currency.find(currency) || ::Money::Currency.find('USD')).exponent
+ end
+
+ # Rounds to the currency's own minor unit, half-up, so amounts reconcile
+ # to the cent when they are summed.
+ #
+ # @param amount [Numeric, String, nil]
+ # @param currency [String, ::Money::Currency, nil]
+ # @return [BigDecimal]
+ def to_currency(amount, currency)
+ quantize(amount, precision(currency))
+ end
+
+ # The same rounding against a precision already in hand.
+ #
+ # @param amount [Numeric, String, nil]
+ # @param precision [Integer]
+ # @return [BigDecimal]
+ def quantize(amount, precision)
+ BigDecimal(amount.to_s).round(precision, BigDecimal::ROUND_HALF_UP)
+ end
+ end
+
include Comparable
class << self
diff --git a/spree/core/lib/spree/testing_support/factories/commission_rate_factory.rb b/spree/core/lib/spree/testing_support/factories/commission_rate_factory.rb
new file mode 100644
index 0000000000..08b4e82d58
--- /dev/null
+++ b/spree/core/lib/spree/testing_support/factories/commission_rate_factory.rb
@@ -0,0 +1,45 @@
+FactoryBot.define do
+ factory :commission_rate, class: Spree::CommissionRate do
+ sequence(:name) { |n| "Commission rate #{n}" }
+ store { Spree::Store.default || create(:store) }
+ kind { 'percentage' }
+ value { 10 }
+ enabled { true }
+ priority { 0 }
+
+ trait :fixed do
+ kind { 'fixed' }
+ value { 2.5 }
+ currency { 'USD' }
+ end
+
+ trait :disabled do
+ enabled { false }
+ end
+
+ trait :with_shipping do
+ include_shipping { true }
+ end
+
+ trait :gross_base do
+ include_tax { true }
+ end
+ end
+
+ factory :commission_rule, class: Spree::CommissionRule do
+ commission_rate { create(:commission_rate) }
+ subject { create(:vendor) }
+ end
+
+ factory :commission_line, class: Spree::CommissionLine do
+ order { create(:order) }
+ vendor { create(:vendor) }
+ line_item { create(:line_item) }
+ kind { 'percentage' }
+ rate { 10 }
+ amount { 10 }
+ tax_amount { 0 }
+ total { 10 }
+ currency { 'USD' }
+ end
+end
diff --git a/spree/core/spec/models/spree/commission_line_spec.rb b/spree/core/spec/models/spree/commission_line_spec.rb
new file mode 100644
index 0000000000..1cbfebfa85
--- /dev/null
+++ b/spree/core/spec/models/spree/commission_line_spec.rb
@@ -0,0 +1,52 @@
+require 'spec_helper'
+
+RSpec.describe Spree::CommissionLine, type: :model do
+ let(:store) { @default_store }
+ let(:order) { create(:order, store: store) }
+ let(:vendor) { create(:vendor, :approved, store: store) }
+ let(:line_item) { create(:line_item, order: order) }
+ let(:fulfillment) { create(:fulfillment, order: order) }
+
+ describe 'what it is charged against' do
+ it 'accepts an item' do
+ expect(build(:commission_line, order: order, vendor: vendor, line_item: line_item)).to be_valid
+ end
+
+ it 'accepts a delivery' do
+ expect(
+ build(:commission_line, order: order, vendor: vendor, line_item: nil, fulfillment: fulfillment)
+ ).to be_valid
+ end
+
+ it 'refuses both at once' do
+ expect(
+ build(:commission_line, order: order, vendor: vendor, line_item: line_item, fulfillment: fulfillment)
+ ).not_to be_valid
+ end
+
+ it 'refuses neither' do
+ expect(build(:commission_line, order: order, vendor: vendor, line_item: nil)).not_to be_valid
+ end
+ end
+
+ # A settlement record has to survive the configuration that produced it,
+ # because a marketplace still has to explain a charge it already made.
+ it 'outlives the rate it was calculated from' do
+ rate = create(:commission_rate, store: store)
+ line = create(:commission_line, order: order, vendor: vendor, line_item: line_item, commission_rate: rate)
+
+ rate.destroy
+
+ expect(line.reload).to be_persisted
+ expect(line.commission_rate).to be_nil
+ expect(line.rate).to eq(10)
+ end
+
+ it 'renders its parts as money' do
+ line = build(:commission_line, amount: 10, tax_amount: 2.1, total: 12.1, currency: 'USD')
+
+ expect(line.display_amount.to_s).to eq('$10.00')
+ expect(line.display_tax_amount.to_s).to eq('$2.10')
+ expect(line.display_total.to_s).to eq('$12.10')
+ end
+end
diff --git a/spree/core/spec/models/spree/commission_rate_spec.rb b/spree/core/spec/models/spree/commission_rate_spec.rb
new file mode 100644
index 0000000000..b9d241bdc4
--- /dev/null
+++ b/spree/core/spec/models/spree/commission_rate_spec.rb
@@ -0,0 +1,160 @@
+require 'spec_helper'
+
+RSpec.describe Spree::CommissionRate, type: :model do
+ let(:store) { @default_store }
+
+ describe 'validations' do
+ it 'requires a currency on a fixed rate but not on a percentage' do
+ expect(build(:commission_rate, kind: 'fixed', currency: nil)).not_to be_valid
+ expect(build(:commission_rate, kind: 'percentage', currency: nil)).to be_valid
+ end
+
+ it 'rejects a cap below the floor' do
+ rate = build(:commission_rate, min_amount: 10, max_amount: 5)
+
+ expect(rate).not_to be_valid
+ expect(rate.errors[:max_amount]).to be_present
+ end
+
+ it 'scopes the code to the store' do
+ create(:commission_rate, store: store, code: 'standard')
+ other_store = create(:store)
+
+ expect(build(:commission_rate, store: store, code: 'standard')).not_to be_valid
+ expect(build(:commission_rate, store: other_store, code: 'standard')).to be_valid
+ end
+
+ # Rates are paranoid, so the unique index has to ignore deleted rows or a
+ # store could never reuse the code of a rate it had retired.
+ it 'lets a store reuse the code of a rate it retired' do
+ create(:commission_rate, store: store, code: 'standard').destroy
+
+ expect { create(:commission_rate, store: store, code: 'standard') }.not_to raise_error
+ end
+
+ it 'allows several rates to carry no code at all' do
+ create(:commission_rate, store: store, code: nil)
+
+ expect { create(:commission_rate, store: store, code: nil) }.not_to raise_error
+ end
+ end
+
+ describe '#applies_to_currency?' do
+ it 'accepts any currency for a percentage' do
+ rate = build(:commission_rate, kind: 'percentage')
+
+ expect(rate.applies_to_currency?('EUR')).to be true
+ expect(rate.applies_to_currency?('USD')).to be true
+ end
+
+ it 'holds a fixed rate to its own currency' do
+ rate = build(:commission_rate, :fixed, currency: 'EUR')
+
+ expect(rate.applies_to_currency?('EUR')).to be true
+ expect(rate.applies_to_currency?('usd')).to be false
+ end
+ end
+
+ describe '#matches_subjects?' do
+ let(:vendor) { create(:vendor, store: store) }
+ let(:other_vendor) { create(:vendor, store: store) }
+ let(:cameras) { create(:category) }
+ let(:audio) { create(:category) }
+ let(:product) { create(:product, store: store) }
+
+ let(:subjects) do
+ { 'Spree::Vendor' => [vendor], 'Spree::Category' => [cameras], 'Spree::Product' => [product] }
+ end
+
+ it 'matches everything when it carries no rules' do
+ expect(create(:commission_rate, store: store).matches_subjects?(subjects)).to be true
+ end
+
+ it 'matches on a single dimension' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+
+ expect(rate.reload.matches_subjects?(subjects)).to be true
+ end
+
+ it 'does not match a rule naming someone else' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: other_vendor)
+
+ expect(rate.reload.matches_subjects?(subjects)).to be false
+ end
+
+ # The dimension-grouped rule: OR inside one subject type.
+ it 'matches when any rule of a dimension matches' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: cameras)
+ create(:commission_rule, commission_rate: rate, subject: audio)
+
+ expect(rate.reload.matches_subjects?(subjects)).to be true
+ end
+
+ # ...and AND across them, which is what expresses "this seller, in this
+ # category" — the pairing a marketplace actually sells.
+ it 'requires every dimension it names to match' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+ create(:commission_rule, commission_rate: rate, subject: audio)
+
+ expect(rate.reload.matches_subjects?(subjects)).to be false
+ end
+
+ it 'matches a seller-and-category pairing when both hold' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+ create(:commission_rule, commission_rate: rate, subject: cameras)
+
+ expect(rate.reload.matches_subjects?(subjects)).to be true
+ end
+
+ it 'ignores a dimension the rate says nothing about' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+
+ expect(rate.reload.matches_subjects?(subjects.except('Spree::Category'))).to be true
+ end
+
+ it 'treats a global rule as no constraint' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: nil)
+
+ expect(rate.reload.matches_subjects?(subjects)).to be true
+ end
+ end
+
+ describe '#rules=' do
+ let(:vendor) { create(:vendor, store: store) }
+ let(:category) { create(:category) }
+
+ it 'replaces the rate targeting wholesale' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+
+ rate.update!(rules: [{ subject_type: 'Spree::Category', subject_id: category.id }])
+
+ expect(rate.reload.commission_rules.map(&:subject)).to eq([category])
+ end
+
+ it 'clears the targeting when given nothing' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+
+ rate.update!(rules: [])
+
+ expect(rate.reload.commission_rules).to be_empty
+ end
+ end
+
+ describe '.by_priority' do
+ it 'walks from the highest priority down' do
+ low = create(:commission_rate, store: store, priority: 1)
+ high = create(:commission_rate, store: store, priority: 10)
+
+ expect(described_class.by_priority.to_a).to eq([high, low])
+ end
+ end
+end
diff --git a/spree/core/spec/models/spree/tax_provider/service_tax_rate_spec.rb b/spree/core/spec/models/spree/tax_provider/service_tax_rate_spec.rb
new file mode 100644
index 0000000000..c2fcab15b0
--- /dev/null
+++ b/spree/core/spec/models/spree/tax_provider/service_tax_rate_spec.rb
@@ -0,0 +1,56 @@
+require 'spec_helper'
+
+RSpec.describe 'Spree::TaxProvider service tax rate' do
+ let(:store) { @default_store }
+ let(:category) { Spree::TaxCategory.default(store) || create(:tax_category, store: store, is_default: true) }
+ let(:address) { create(:address, country_iso: 'DE') }
+
+ describe Spree::TaxProvider::Base do
+ # A provider that cannot price a service supply says nothing rather than
+ # zero, so its caller falls back to a configured default instead of
+ # treating silence as "untaxed".
+ it 'has no opinion by default' do
+ expect(described_class.new.service_tax_rate(address: address, store: store)).to be_nil
+ end
+ end
+
+ describe Spree::TaxProvider::Internal do
+ subject(:provider) { described_class.new }
+
+ it 'reads the rate configured for where the business sits' do
+ create(:tax_rate, store: store, tax_category: category, amount: 0.19,
+ country_code: 'DE', included_in_price: false)
+
+ expect(provider.service_tax_rate(address: address, store: store)).to eq(0.19)
+ end
+
+ it 'has no opinion when nothing is configured for that jurisdiction' do
+ create(:tax_rate, store: store, tax_category: category, amount: 0.19,
+ country_code: 'FR', included_in_price: false)
+
+ expect(provider.service_tax_rate(address: address, store: store)).to be_nil
+ end
+
+ it 'has no opinion without an address' do
+ expect(provider.service_tax_rate(address: nil, store: store)).to be_nil
+ end
+
+ # A commission is quoted net and its VAT is added on top, so a rate
+ # describing tax-inclusive consumer pricing does not describe this supply.
+ it 'ignores rates configured as included in the price' do
+ create(:tax_rate, store: store, tax_category: category, amount: 0.19,
+ country_code: 'DE', included_in_price: true)
+
+ expect(provider.service_tax_rate(address: address, store: store)).to be_nil
+ end
+
+ it 'does not read another store rates' do
+ other_store = create(:store)
+ other_category = create(:tax_category, store: other_store, is_default: true)
+ create(:tax_rate, store: other_store, tax_category: other_category, amount: 0.19,
+ country_code: 'DE', included_in_price: false)
+
+ expect(provider.service_tax_rate(address: address, store: store)).to be_nil
+ end
+ end
+end
diff --git a/spree/core/spec/services/spree/commissions/calculate_line_spec.rb b/spree/core/spec/services/spree/commissions/calculate_line_spec.rb
new file mode 100644
index 0000000000..679d375abe
--- /dev/null
+++ b/spree/core/spec/services/spree/commissions/calculate_line_spec.rb
@@ -0,0 +1,159 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Commissions::CalculateLine do
+ subject(:calculate) { described_class }
+
+ let(:store) { @default_store }
+ let(:vendor) { create(:vendor, :approved, store: store) }
+ let(:order) { create(:order, store: store, currency: 'USD') }
+ let(:line_item) { create(:line_item, order: order, price: 100, quantity: 1) }
+ let(:rate) { create(:commission_rate, store: store, kind: 'percentage', value: 10) }
+
+ def call(**overrides)
+ calculate.call(
+ { rate: rate, vendor: vendor, order: order, line_item: line_item, commission_tax_rate: 0 }.merge(overrides)
+ ).value
+ end
+
+ it 'charges a percentage of the item' do
+ expect(call.amount).to eq(10)
+ end
+
+ it 'charges a percentage of every unit sold' do
+ three = create(:line_item, order: order, price: 100, quantity: 3)
+
+ expect(call(line_item: three).amount).to eq(30)
+ end
+
+ it 'charges a fixed rate once, however many units it covered' do
+ three = create(:line_item, order: order, price: 100, quantity: 3)
+ fixed = create(:commission_rate, :fixed, store: store, value: 2.5, currency: 'USD')
+
+ expect(call(rate: fixed, line_item: three).amount).to eq(2.5)
+ end
+
+ it 'snapshots the rate that applied' do
+ line = call
+
+ expect(line.kind).to eq('percentage')
+ expect(line.rate).to eq(10)
+ expect(line.commission_rate).to eq(rate)
+ expect(line.currency).to eq('USD')
+ end
+
+ describe 'the commission base' do
+ # The EU rule: the fee is charged on what the seller earned net of the
+ # consumer's VAT, because the fee is its own separate supply.
+ it 'excludes VAT already inside the price' do
+ line_item.update_columns(included_tax_total: 20)
+
+ expect(call.amount).to eq(8)
+ end
+
+ it 'counts VAT added on top only when the rate asks for a gross base' do
+ line_item.update_columns(additional_tax_total: 20)
+
+ expect(call.amount).to eq(10)
+ expect(call(rate: create(:commission_rate, :gross_base, store: store, value: 10)).amount).to eq(12)
+ end
+
+ it 'charges on what the customer actually paid, after discounts' do
+ line_item.update_columns(taxable_adjustment_total: -40)
+
+ expect(call.amount).to eq(6)
+ end
+
+ it 'never pays the seller a commission when a discount exceeds the item' do
+ line_item.update_columns(taxable_adjustment_total: -500)
+
+ expect(call.amount).to eq(0)
+ end
+ end
+
+ describe 'floor and cap' do
+ it 'lifts a commission to the floor' do
+ floored = create(:commission_rate, store: store, value: 1, min_amount: 5)
+
+ expect(call(rate: floored).amount).to eq(5)
+ end
+
+ it 'holds a commission to the cap' do
+ capped = create(:commission_rate, store: store, value: 50, max_amount: 20)
+
+ expect(call(rate: capped).amount).to eq(20)
+ end
+ end
+
+ describe 'tax on the commission' do
+ # The headline EU behaviour: VAT is charged on the marketplace's fee as a
+ # separate B2B supply, on top of it rather than out of it.
+ it 'adds tax on top of the fee and totals the two' do
+ line = call(commission_tax_rate: 0.21)
+
+ expect(line.amount).to eq(10)
+ expect(line.tax_amount).to eq(2.1)
+ expect(line.total).to eq(12.1)
+ end
+
+ it 'leaves the fee alone when nothing taxes it' do
+ line = call(commission_tax_rate: 0)
+
+ expect(line.tax_amount).to eq(0)
+ expect(line.total).to eq(10)
+ end
+
+ it 'prefers an explicit rate override to anything the tax engine says' do
+ overridden = create(:commission_rate, store: store, value: 10, commission_tax_rate: 0.19)
+ allow(order.tax_provider).to receive(:service_tax_rate).and_return(0.21)
+
+ expect(call(rate: overridden, commission_tax_rate: nil).tax_amount).to eq(1.9)
+ end
+
+ it 'falls back to the store default when neither the rate nor the engine answers' do
+ stub_store_preferences(store, default_commission_tax_rate: 0.2)
+ allow_any_instance_of(Spree::TaxProvider::Internal).to receive(:service_tax_rate).and_return(nil)
+
+ expect(call(commission_tax_rate: nil).tax_amount).to eq(2)
+ end
+ end
+
+ describe 'rounding' do
+ it 'rounds each part half-up to the currency, then sums them' do
+ odd = create(:commission_rate, store: store, value: 3.33)
+ line = call(rate: odd, commission_tax_rate: 0.21)
+
+ # 100 * 3.33% = 3.33; 3.33 * 21% = 0.6993 -> 0.70
+ expect(line.amount).to eq(3.33)
+ expect(line.tax_amount).to eq(0.7)
+ expect(line.total).to eq(4.03)
+ end
+
+ # A currency with no minor unit rounds to whole units, so a marketplace
+ # billing in yen never writes a fraction of one.
+ it 'follows the currency to its own minor unit' do
+ allow_any_instance_of(Spree::Store).to receive(:supported_currencies_list).
+ and_return([::Money::Currency.find('USD'), ::Money::Currency.find('JPY')])
+ yen_order = create(:order, store: store, currency: 'JPY')
+ yen_item = create(:line_item, order: yen_order, price: 1000, quantity: 1, currency: 'JPY')
+ odd = create(:commission_rate, store: store, value: 3.33)
+
+ line = call(rate: odd, order: yen_order, line_item: yen_item)
+
+ expect(line.amount).to eq(33)
+ end
+ end
+
+ it 'commissions a delivery when handed a fulfillment' do
+ fulfillment = create(:fulfillment, order: order, cost: 50)
+
+ line = call(line_item: nil, fulfillment: fulfillment)
+
+ expect(line.amount).to eq(5)
+ expect(line.fulfillment).to eq(fulfillment)
+ expect(line.line_item).to be_nil
+ end
+
+ it 'refuses to price nothing' do
+ expect(calculate.call(rate: rate, vendor: vendor, order: order)).to be_failure
+ end
+end
diff --git a/spree/core/spec/services/spree/commissions/commission_order_spec.rb b/spree/core/spec/services/spree/commissions/commission_order_spec.rb
new file mode 100644
index 0000000000..8bd380e1ee
--- /dev/null
+++ b/spree/core/spec/services/spree/commissions/commission_order_spec.rb
@@ -0,0 +1,178 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Commissions::CommissionOrder do
+ let(:store) { @default_store }
+ let(:vendor) { create(:vendor, :approved, store: store) }
+ let(:other_vendor) { create(:vendor, :approved, store: store) }
+ let(:order) { create(:order, store: store, currency: 'USD') }
+
+ let!(:rate) { create(:commission_rate, store: store, kind: 'percentage', value: 10) }
+
+ def line_for(seller, price: 100)
+ product = create(:product, store: store, vendor: seller)
+ create(:line_item, order: order, variant: product.default_variant, price: price, quantity: 1)
+ end
+
+ def commission
+ described_class.call(order: order).value
+ end
+
+ it 'charges the seller of each item sold' do
+ line = line_for(vendor)
+
+ lines = commission
+
+ expect(lines.size).to eq(1)
+ expect(lines.first).to have_attributes(vendor: vendor, line_item: line, amount: 10, order: order)
+ end
+
+ it 'leaves the marketplace own items alone' do
+ create(:line_item, order: order, price: 100, quantity: 1)
+
+ expect(commission).to be_empty
+ end
+
+ it 'charges each seller on a mixed order separately' do
+ line_for(vendor, price: 100)
+ line_for(other_vendor, price: 50)
+
+ lines = commission
+
+ expect(lines.map(&:vendor)).to match_array([vendor, other_vendor])
+ expect(lines.find { |l| l.vendor == vendor }.amount).to eq(10)
+ expect(lines.find { |l| l.vendor == other_vendor }.amount).to eq(5)
+ end
+
+ # A commission line is a settlement record: charging twice for one sale is
+ # the failure that matters most here.
+ it 'does not charge again for an order it already commissioned' do
+ line_for(vendor)
+
+ commission
+
+ expect { commission }.not_to change(Spree::CommissionLine, :count)
+ end
+
+ it 'writes nothing when no rate matches the sale' do
+ rate.update!(enabled: false)
+ line_for(vendor)
+
+ expect(commission).to be_empty
+ end
+
+ it 'never touches what the customer pays' do
+ line_for(vendor)
+ total_before = order.reload.total
+
+ commission
+
+ expect(order.reload.total).to eq(total_before)
+ expect(order.fees).to be_empty
+ end
+
+ describe 'delivery' do
+ let!(:rate) { create(:commission_rate, :with_shipping, store: store, kind: 'percentage', value: 10) }
+
+ # The factory fills a fulfillment from every line on the order, so carrying
+ # exactly the named lines has to be stated.
+ def fulfillment_carrying(*line_items, cost: 20)
+ fulfillment = create(:fulfillment, order: order, cost: cost)
+ fulfillment.fulfillment_items.destroy_all
+ line_items.each { |line_item| fulfillment.fulfillment_items.create!(line_item: line_item, quantity: 1) }
+ fulfillment
+ end
+
+ it 'charges the delivery when the rate includes shipping' do
+ fulfillment_carrying(line_for(vendor))
+
+ delivery_line = commission.find(&:fulfillment_id)
+
+ expect(delivery_line.amount).to eq(2)
+ expect(delivery_line.vendor).to eq(vendor)
+ end
+
+ it 'leaves delivery alone when the rate does not include shipping' do
+ rate.update!(include_shipping: false)
+ fulfillment_carrying(line_for(vendor))
+
+ expect(commission.select(&:fulfillment_id)).to be_empty
+ end
+
+ it 'charges a delivery only to the seller whose goods it carries' do
+ mine = line_for(vendor)
+ theirs = line_for(other_vendor)
+ fulfillment_carrying(mine)
+ fulfillment_carrying(theirs, cost: 0)
+
+ delivery_lines = commission.select(&:fulfillment_id)
+
+ expect(delivery_lines.map(&:vendor)).to eq([vendor])
+ end
+
+ # Before the split, one delivery can carry two sellers' goods. It belongs
+ # to neither alone: billing both charges one parcel twice, and picking one
+ # bills the wrong seller.
+ it 'leaves a delivery shared between sellers uncommissioned' do
+ fulfillment_carrying(line_for(vendor), line_for(other_vendor))
+
+ lines = commission
+
+ expect(lines.select(&:fulfillment_id)).to be_empty
+ expect(lines.select(&:line_item_id).size).to eq(2)
+ end
+
+ it 'charges nothing for a free delivery' do
+ fulfillment_carrying(line_for(vendor), cost: 0)
+
+ expect(commission.select(&:fulfillment_id)).to be_empty
+ end
+ end
+
+ describe 'tax on the commission' do
+ # Each rate may carry its own tax override, so a basket governed by two
+ # rates must not have the first one's answer applied to both.
+ it 'taxes each line by the rate that governed it' do
+ generic = line_for(vendor, price: 100)
+ special_product = create(:product, store: store, vendor: vendor)
+ special_line = create(:line_item, order: order, variant: special_product.default_variant,
+ price: 100, quantity: 1)
+
+ special_rate = create(:commission_rate, store: store, value: 10, priority: 10,
+ commission_tax_rate: 0.19)
+ create(:commission_rule, commission_rate: special_rate, subject: special_product)
+ rate.update!(commission_tax_rate: 0.05)
+
+ lines = commission.index_by(&:line_item_id)
+
+ expect(lines[special_line.id].tax_amount).to eq(1.9)
+ expect(lines[generic.id].tax_amount).to eq(0.5)
+ end
+
+ # One rate governing a whole basket is one question about where the seller
+ # sits, so the tax engine is consulted once rather than per item.
+ it 'asks the tax engine once for a basket governed by one rate' do
+ 3.times { line_for(vendor) }
+ asked = 0
+ allow_any_instance_of(Spree::TaxProvider::Internal).to receive(:service_tax_rate) do
+ asked += 1
+ 0.2
+ end
+
+ lines = commission
+
+ expect(lines.size).to eq(3)
+ expect(asked).to eq(1)
+ end
+ end
+
+ describe 'the seller it charges' do
+ # The line's own snapshot is the record of who sold it — the catalog
+ # changing hands afterwards must never move the charge.
+ it 'follows the line snapshot rather than the product today' do
+ line = line_for(vendor)
+ line.variant.product.update!(vendor: other_vendor)
+
+ expect(commission.first.vendor).to eq(vendor)
+ end
+ end
+end
diff --git a/spree/core/spec/services/spree/commissions/resolve_rate_spec.rb b/spree/core/spec/services/spree/commissions/resolve_rate_spec.rb
new file mode 100644
index 0000000000..c4f5235bd9
--- /dev/null
+++ b/spree/core/spec/services/spree/commissions/resolve_rate_spec.rb
@@ -0,0 +1,138 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Commissions::ResolveRate do
+ let(:store) { @default_store }
+ let(:vendor) { create(:vendor, :approved, store: store) }
+ let(:other_vendor) { create(:vendor, :approved, store: store) }
+ let(:product) { create(:product, store: store, vendor: vendor) }
+ let(:order) { create(:order, store: store, currency: 'USD') }
+ let(:line_item) { create(:line_item, order: order, variant: product.default_variant) }
+
+ def resolve(currency: 'USD')
+ described_class.call(line_item: line_item, vendor: vendor, store: store, currency: currency).value
+ end
+
+ it 'returns nothing when the marketplace has configured no rates' do
+ expect(resolve).to be_nil
+ end
+
+ it 'takes an untargeted rate as the marketplace default' do
+ rate = create(:commission_rate, store: store)
+
+ expect(resolve).to eq(rate)
+ end
+
+ it 'ignores a disabled rate' do
+ create(:commission_rate, :disabled, store: store)
+
+ expect(resolve).to be_nil
+ end
+
+ it 'ignores another store rates' do
+ create(:commission_rate, store: create(:store))
+
+ expect(resolve).to be_nil
+ end
+
+ # Precedence is the operator's integer, not a hardcoded ladder.
+ it 'takes the highest priority match' do
+ create(:commission_rate, store: store, priority: 1)
+ winner = create(:commission_rate, store: store, priority: 10)
+
+ expect(resolve).to eq(winner)
+ end
+
+ it 'skips a higher-priority rate whose targeting does not match' do
+ mismatched = create(:commission_rate, store: store, priority: 10)
+ create(:commission_rule, commission_rate: mismatched, subject: other_vendor)
+ fallback = create(:commission_rate, store: store, priority: 1)
+
+ expect(resolve).to eq(fallback)
+ end
+
+ it 'matches a rate targeting the seller' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: vendor)
+
+ expect(resolve).to eq(rate)
+ end
+
+ it 'matches a rate targeting the product' do
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: product)
+
+ expect(resolve).to eq(rate)
+ end
+
+ it 'matches a rate targeting the product category' do
+ category = create(:category)
+ product.categories << category
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: category)
+
+ expect(resolve).to eq(rate)
+ end
+
+ # A rate on a parent category governs everything filed beneath it, so a
+ # marketplace does not have to restate the rule on every new leaf.
+ it 'matches a rate targeting an ancestor of the product category' do
+ parent = create(:category)
+ child = create(:category, parent: parent, taxonomy: parent.taxonomy)
+ product.categories << child
+ rate = create(:commission_rate, store: store)
+ create(:commission_rule, commission_rate: rate, subject: parent)
+
+ expect(resolve).to eq(rate)
+ end
+
+ # Walking a nested set is a query per category, so the ancestors are resolved
+ # for the whole order at once. That batching has to give exactly what asking
+ # each category on its own would.
+ describe '.categories_for' do
+ it 'gives each product its categories and their ancestors' do
+ root = create(:category)
+ middle = create(:category, parent: root, taxonomy: root.taxonomy)
+ leaf = create(:category, parent: middle, taxonomy: root.taxonomy)
+ unrelated = create(:category)
+
+ deep = create(:product, store: store)
+ deep.categories << leaf
+ wide = create(:product, store: store)
+ wide.categories << unrelated
+ wide.categories << middle
+
+ resolved = described_class.categories_for([deep, wide])
+
+ [deep, wide].each do |product|
+ one_at_a_time = product.categories.flat_map { |c| c.self_and_ancestors.to_a }.uniq
+
+ expect(resolved[product.id].map(&:id)).to match_array(one_at_a_time.map(&:id))
+ end
+ end
+
+ it 'gives a product with no categories an empty list' do
+ bare = create(:product, store: store)
+
+ expect(described_class.categories_for([bare])).to eq(bare.id => [])
+ end
+
+ it 'resolves nothing for nothing' do
+ expect(described_class.categories_for([])).to eq({})
+ end
+ end
+
+ describe 'currency' do
+ it 'passes over a fixed rate priced in another currency' do
+ create(:commission_rate, :fixed, store: store, currency: 'EUR', priority: 10)
+ fallback = create(:commission_rate, store: store, priority: 1)
+
+ expect(resolve(currency: 'USD')).to eq(fallback)
+ end
+
+ it 'accepts a percentage rate in any currency' do
+ rate = create(:commission_rate, store: store, kind: 'percentage')
+
+ expect(resolve(currency: 'EUR')).to eq(rate)
+ end
+ end
+end
diff --git a/spree/core/spec/services/spree/commissions/resolve_tax_rate_spec.rb b/spree/core/spec/services/spree/commissions/resolve_tax_rate_spec.rb
new file mode 100644
index 0000000000..3c219a93cb
--- /dev/null
+++ b/spree/core/spec/services/spree/commissions/resolve_tax_rate_spec.rb
@@ -0,0 +1,58 @@
+require 'spec_helper'
+
+RSpec.describe Spree::Commissions::ResolveTaxRate do
+ let(:store) { @default_store }
+ let(:billing_address) { create(:address, country_iso: 'DE') }
+ let(:vendor) { create(:vendor, :approved, store: store, billing_address: billing_address) }
+ let(:order) { create(:order, store: store) }
+ let(:rate) { create(:commission_rate, store: store) }
+
+ def resolve
+ described_class.call(rate: rate, vendor: vendor, order: order).value
+ end
+
+ it 'prefers an explicit override on the rate' do
+ rate.update!(commission_tax_rate: 0.19)
+ allow_any_instance_of(Spree::TaxProvider::Internal).to receive(:service_tax_rate).and_return(0.21)
+
+ expect(resolve).to eq(0.19)
+ end
+
+ it 'asks the tax engine when the rate names no rate of its own' do
+ allow_any_instance_of(Spree::TaxProvider::Internal).to receive(:service_tax_rate).and_return(0.21)
+
+ expect(resolve).to eq(0.21)
+ end
+
+ # The commission is invoiced to the seller's business, so it is taxed where
+ # that business sits — not where the customer's parcel went.
+ it 'asks against the seller billing address' do
+ expect_any_instance_of(Spree::TaxProvider::Internal).
+ to receive(:service_tax_rate).with(address: billing_address, store: store).and_return(0.19)
+
+ resolve
+ end
+
+ it 'falls back to the store default when the engine has no opinion' do
+ stub_store_preferences(store, default_commission_tax_rate: 0.2)
+ allow_any_instance_of(Spree::TaxProvider::Internal).to receive(:service_tax_rate).and_return(nil)
+
+ expect(resolve).to eq(0.2)
+ end
+
+ it 'charges nothing when nothing is configured anywhere' do
+ allow_any_instance_of(Spree::TaxProvider::Internal).to receive(:service_tax_rate).and_return(nil)
+
+ expect(resolve).to eq(0)
+ end
+
+ # Commission is written while an order is being placed, so a tax service
+ # being down must not cost the marketplace the sale.
+ it 'falls back rather than raising when the engine fails' do
+ stub_store_preferences(store, default_commission_tax_rate: 0.2)
+ allow_any_instance_of(Spree::TaxProvider::Internal).
+ to receive(:service_tax_rate).and_raise(StandardError, 'tax service unreachable')
+
+ expect(resolve).to eq(0.2)
+ end
+end