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.

Regenerated the API reference

Damian Legawiec9683f317c4b8
diff --git a/docs/api-reference/admin.yaml b/docs/api-reference/admin.yaml
index 977919dfc1..7709226b7c 100644
--- a/docs/api-reference/admin.yaml
+++ b/docs/api-reference/admin.yaml
@@ -563,9 +563,10 @@ paths:
whether or not the email matches an account, to prevent enumeration.
`redirect_url` is where the emailed link should point (the reset token
- is appended as a `token` query param). It must match one of the store's
- allowed origins — otherwise it is silently ignored and the server-side
- default is used. The email is delivered by Spree itself via the
+ is appended as a `token` query param). It is honoured only on the
+ dashboard's origin and for an account that is staff of the store —
+ otherwise it is silently ignored and the link opens the dashboard's
+ reset page. The email is delivered by Spree itself via the
`admin_user.password_reset_requested` event; this event is never
forwarded to webhook endpoints.
x-codeSamples:
@@ -11198,6 +11199,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -11211,6 +11214,8 @@ paths:
default: false
country_codes:
- DE
+ country_isos:
+ - DE
supported_locales:
- en
tax_provider:
@@ -11305,6 +11310,8 @@ paths:
default: false
country_codes:
- FR
+ country_isos:
+ - FR
supported_locales:
- en
- fr
@@ -11452,6 +11459,8 @@ paths:
default: false
country_codes:
- DE
+ country_isos:
+ - DE
supported_locales:
- en
tax_provider:
@@ -11533,6 +11542,8 @@ paths:
default: false
country_codes:
- DE
+ country_isos:
+ - DE
supported_locales:
- en
tax_provider:
@@ -12540,7 +12551,7 @@ paths:
application/json:
example:
id: gc_UkLWZg9DAJ
- code: 16C1B414C44A2F41
+ code: "************2F41"
status: active
currency: USD
amount: '10.0'
@@ -12738,6 +12749,10 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
meta:
@@ -12851,6 +12866,10 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -12986,6 +13005,10 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
patch:
@@ -13094,6 +13117,10 @@ paths:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
catalog_price: '19.99'
+ price_list_id:
+ price_list_name:
+ catalog_id:
+ catalog_name:
cost_price: '17.0'
tax_category_id: taxcat_UkLWZg9DAJ
requestBody:
@@ -13266,6 +13293,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -13530,6 +13559,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -13771,6 +13802,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -14045,6 +14078,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -14207,6 +14242,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -14382,6 +14419,10 @@ paths:
Set `notify_customer: true` to send the order confirmation email.
+ On a marketplace, an order holding several sellers' goods becomes one
+ order per seller, and the response is the order group they belong to
+ with those orders nested inside it.
+
**Required scope:** `write_orders` (for API-key authentication).
x-codeSamples:
@@ -14395,9 +14436,12 @@ paths:
secretKey: 'sk_xxx',
})
- const order = await client.orders.complete('or_UkLWZg9DAJ', {
+ const result = await client.orders.complete('or_UkLWZg9DAJ', {
notify_customer: true,
})
+
+ // An order holding several sellers' goods becomes one order per seller.
+ const orders = isOrderGroup(result) ? result.orders : [result]
- lang: bash
label: Spree CLI
source: spree api patch /orders/{id}/complete -d '{"notify_customer":true}'
@@ -14481,6 +14525,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -14678,6 +14724,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -14853,6 +14901,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -15002,6 +15052,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
tax_provider:
@@ -22522,11 +22574,11 @@ paths:
const refund = await client.orders.refunds.create('or_UkLWZg9DAJ', {
payment_id: 'pay_UkLWZg9DAJ',
amount: '5.00',
- refund_reason_id: 'refrsn_UkLWZg9DAJ',
+ refund_reason_id: 'rr_UkLWZg9DAJ',
})
- lang: bash
label: Spree CLI
- source: spree api post /orders/{order_id}/refunds -d '{"payment_id":"pay_UkLWZg9DAJ","amount":"5.00","refund_reason_id":"refrsn_UkLWZg9DAJ"}'
+ source: spree api post /orders/{order_id}/refunds -d '{"payment_id":"pay_UkLWZg9DAJ","amount":"5.00","refund_reason_id":"rr_UkLWZg9DAJ"}'
parameters:
- name: x-spree-api-key
in: header
@@ -24174,7 +24226,7 @@ paths:
- 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.
+ Removes the user's role assignments on the current store. The account is preserved — the user keeps access to any other stores. Removing a role needs the same rights as granting it, and the store always keeps at least one admin.
**Required scope:** `write_staff` (for API-key authentication).
x-codeSamples:
@@ -24265,7 +24317,6 @@ paths:
role_id: role_UkLWZg9DAJ
role_name: admin
inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=bcFtaxxWh2f6dkZb6EQNpKhJ"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -24335,7 +24386,6 @@ paths:
role_id: role_UkLWZg9DAJ
role_name: admin
inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_gbHJdmfrXB?token=VVL8HRJRDHaZmJ4pQEhtz6ey"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -24398,6 +24448,59 @@ paths:
responses:
'204':
description: invitation revoked
+ "/api/v3/admin/invitations/{invitation_id}/acceptance_link":
+ get:
+ summary: Get an invitation acceptance link
+ tags:
+ - Staff
+ security:
+ - api_key: []
+ bearer_auth: []
+ description: |-
+ Returns the link the invitee opens to accept a pending invitation. The link carries the invitation token, so it needs write access to staff and the right to grant the invitation's role; invitation listings never include it.
+
+ **Required scope:** `write_staff` (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 { acceptance_url } = await client.invitations.acceptanceLink('inv_xxx')
+ - lang: bash
+ label: Spree CLI
+ source: spree api get /invitations/{invitation_id}/acceptance_link
+ parameters:
+ - name: x-spree-api-key
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: Authorization
+ in: header
+ required: true
+ schema:
+ type: string
+ - name: invitation_id
+ in: path
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: acceptance link found
+ content:
+ application/json:
+ example:
+ id: inv_UkLWZg9DAJ
+ acceptance_url: http://www.example.com:3000/accept-invitation/inv_UkLWZg9DAJ?token=jDy3giwKk1iUW1wTMg5LRLEG
+ schema:
+ "$ref": "#/components/schemas/InvitationAcceptanceLink"
"/api/v3/admin/invitations/{id}/resend":
patch:
summary: Resend an invitation
@@ -24456,7 +24559,6 @@ paths:
role_id: role_UkLWZg9DAJ
role_name: admin
inviter_email: [email protected]
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=FxDpzwwoQd483CL8xLvY7u6R"
invitee_exists: false
store:
id: store_UkLWZg9DAJ
@@ -28020,7 +28122,7 @@ paths:
data:
message: This is a test webhook from Spree.
metadata:
- spree_version: 6.0.0.beta1
+ spree_version: 6.0.0.beta2
webhook_endpoint_id: whe_UkLWZg9DAJ
webhook_endpoint_url: https://shop.example.com/webhooks/orders
"/api/v3/admin/webhook_endpoints/{id}/enable":
@@ -32828,13 +32930,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/thinking-cat.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--ef2f66e38d520018b60615a0903aa4ecdfa9aaee/thinking-cat.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--22947d56d4ac0912819361bb0b822dde6aecb15c/thinking-cat.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7d198934cc9db4854d4d6d8797b2c51a08d68cd2/thinking-cat.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2e87feabba138d36b7be60f82611c17fab8d2a91/thinking-cat.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--af487de5d53fda6359a9f885788362b1e4570179/thinking-cat.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--6f4c660cdd78e69838fe7b0f57673dfedb55b740/thinking-cat.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--842df2157f0239c97e8da1cb68e59bad0bb1c65c/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--efc4098d67c95b766076ffd76169e7d49199c517/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e5a1c73260840c5ab2bb78ebed47f7f5db621e85/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--60df672360d3d2c45cd72572b2e6faf9882995e1/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--74872e2b62fcbb93875b99ea99356c004855f9d3/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--e97abb6268b26c7a282c61cd0aedea525f75a555/thinking-cat.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -32842,10 +32944,10 @@ paths:
filename: thinking-cat.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--9c5dc339f72f9ea0877ae0fdd1a16ed0dcbdbc67/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8bb0d93bcda0e7a158700e75fe6ce3f53ca8d223/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc
viewable_id: prod_UkLWZg9DAJ
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/thinking-cat.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg?disposition=attachment
metadata: {}
viewable_type: product
meta:
@@ -32916,13 +33018,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/library-upload.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--ef2f66e38d520018b60615a0903aa4ecdfa9aaee/library-upload.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--22947d56d4ac0912819361bb0b822dde6aecb15c/library-upload.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7d198934cc9db4854d4d6d8797b2c51a08d68cd2/library-upload.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2e87feabba138d36b7be60f82611c17fab8d2a91/library-upload.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--af487de5d53fda6359a9f885788362b1e4570179/library-upload.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--6f4c660cdd78e69838fe7b0f57673dfedb55b740/library-upload.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/library-upload.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--842df2157f0239c97e8da1cb68e59bad0bb1c65c/library-upload.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--efc4098d67c95b766076ffd76169e7d49199c517/library-upload.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e5a1c73260840c5ab2bb78ebed47f7f5db621e85/library-upload.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--60df672360d3d2c45cd72572b2e6faf9882995e1/library-upload.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--74872e2b62fcbb93875b99ea99356c004855f9d3/library-upload.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--e97abb6268b26c7a282c61cd0aedea525f75a555/library-upload.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -32930,10 +33032,10 @@ paths:
filename: library-upload.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--9c5dc339f72f9ea0877ae0fdd1a16ed0dcbdbc67/library-upload.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8bb0d93bcda0e7a158700e75fe6ce3f53ca8d223/library-upload.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9
viewable_id:
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--fe426c2edfa9458dd7a1cdf00d6fc76cb130eca6/library-upload.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MiwicHVyIjoiYmxvYl9pZCJ9fQ==--77436642b5a367321ca4aa243635450a505a66c9/library-upload.jpg?disposition=attachment
metadata: {}
viewable_type:
schema:
@@ -33090,13 +33192,13 @@ paths:
video_embed_url:
video_url:
poster_url:
- original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/thinking-cat.jpg
- mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--ef2f66e38d520018b60615a0903aa4ecdfa9aaee/thinking-cat.jpg
- small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--22947d56d4ac0912819361bb0b822dde6aecb15c/thinking-cat.jpg
- medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--7d198934cc9db4854d4d6d8797b2c51a08d68cd2/thinking-cat.jpg
- large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--2e87feabba138d36b7be60f82611c17fab8d2a91/thinking-cat.jpg
- xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--af487de5d53fda6359a9f885788362b1e4570179/thinking-cat.jpg
- og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--6f4c660cdd78e69838fe7b0f57673dfedb55b740/thinking-cat.jpg
+ original_url: http://localhost:3000/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg
+ mini_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjgsMTI4XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--842df2157f0239c97e8da1cb68e59bad0bb1c65c/thinking-cat.jpg
+ small_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyNTYsMjU2XSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--efc4098d67c95b766076ffd76169e7d49199c517/thinking-cat.jpg
+ medium_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls0MDAsNDAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--e5a1c73260840c5ab2bb78ebed47f7f5db621e85/thinking-cat.jpg
+ large_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOls3MjAsNzIwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--60df672360d3d2c45cd72572b2e6faf9882995e1/thinking-cat.jpg
+ xlarge_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsyMDAwLDIwMDBdLCJzYXZlciI6eyJzdHJpcCI6dHJ1ZSwicXVhbGl0eSI6NzUsImxvc3NsZXNzIjpmYWxzZSwiYWxwaGFfcSI6ODUsInJlZHVjdGlvbl9lZmZvcnQiOjYsInNtYXJ0X3N1YnNhbXBsZSI6dHJ1ZX19LCJwdXIiOiJ2YXJpYXRpb24ifX0=--74872e2b62fcbb93875b99ea99356c004855f9d3/thinking-cat.jpg
+ og_image_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2ZpbGwiOlsxMjAwLDYzMF0sInNhdmVyIjp7InN0cmlwIjp0cnVlLCJxdWFsaXR5Ijo3NSwibG9zc2xlc3MiOmZhbHNlLCJhbHBoYV9xIjo4NSwicmVkdWN0aW9uX2VmZm9ydCI6Niwic21hcnRfc3Vic2FtcGxlIjp0cnVlfX0sInB1ciI6InZhcmlhdGlvbiJ9fQ==--e97abb6268b26c7a282c61cd0aedea525f75a555/thinking-cat.jpg
external_references: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
@@ -33104,10 +33206,10 @@ paths:
filename: thinking-cat.jpg
content_type: image/jpeg
byte_size: 18090
- embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--9c5dc339f72f9ea0877ae0fdd1a16ed0dcbdbc67/thinking-cat.jpg
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac
+ embed_url: http://localhost:3000/rails/active_storage/representations/proxy/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/eyJfcmFpbHMiOnsiZGF0YSI6eyJmb3JtYXQiOiJ3ZWJwIiwicmVzaXplX3RvX2xpbWl0IjpbMTIwMCwxMjAwXSwic2F2ZXIiOnsic3RyaXAiOnRydWUsInF1YWxpdHkiOjc1LCJsb3NzbGVzcyI6ZmFsc2UsImFscGhhX3EiOjg1LCJyZWR1Y3Rpb25fZWZmb3J0Ijo2LCJzbWFydF9zdWJzYW1wbGUiOnRydWV9fSwicHVyIjoidmFyaWF0aW9uIn19--8bb0d93bcda0e7a158700e75fe6ce3f53ca8d223/thinking-cat.jpg
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc
viewable_id: prod_gbHJdmfrXB
- download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--eb68ae07452e9cb6221bea98b59480e0daa5afac/thinking-cat.jpg?disposition=attachment
+ download_url: http://localhost:3000/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc/thinking-cat.jpg?disposition=attachment
metadata: {}
viewable_type: product
schema:
@@ -37572,7 +37674,7 @@ paths:
example:
error:
code: processing_error
- message: already_approved
+ message: Already approved
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/admin/sellers/{id}/suspend":
@@ -44018,6 +44120,17 @@ components:
- preferences
- preference_schema
x-typelizer: true
+ InvitationAcceptanceLink:
+ type: object
+ properties:
+ id:
+ type: string
+ acceptance_url:
+ type: string
+ required:
+ - id
+ - acceptance_url
+ x-typelizer: true
Invitation:
type: object
properties:
@@ -44046,8 +44159,6 @@ components:
type: string
inviter_email:
type: string
- acceptance_url:
- type: string
invitee_exists:
type: boolean
store:
@@ -44062,7 +44173,6 @@ components:
- role_id
- role_name
- inviter_email
- - acceptance_url
- invitee_exists
- store
x-typelizer: true
@@ -44158,6 +44268,18 @@ components:
catalog_price:
type: string
nullable: true
+ price_list_id:
+ type: string
+ nullable: true
+ price_list_name:
+ type: string
+ nullable: true
+ catalog_id:
+ type: string
+ nullable: true
+ catalog_name:
+ type: string
+ nullable: true
cost_price:
type: string
nullable: true
@@ -44205,6 +44327,10 @@ components:
- created_at
- updated_at
- catalog_price
+ - price_list_id
+ - price_list_name
+ - catalog_id
+ - catalog_name
- cost_price
- tax_category_id
x-typelizer: true
@@ -44227,6 +44353,10 @@ components:
type: array
items:
type: string
+ country_isos:
+ type: array
+ items:
+ type: string
supported_locales:
type: array
items:
@@ -44250,6 +44380,7 @@ components:
- tax_inclusive
- default
- country_codes
+ - country_isos
- supported_locales
- tax_provider
- created_at
@@ -49029,6 +49160,7 @@ components:
nullable: true
payload:
type: object
+ nullable: true
webhook_endpoint_id:
type: string
webhook_endpoint_url:
diff --git a/docs/api-reference/seller.yaml b/docs/api-reference/seller.yaml
index fd41966380..58e4e685bb 100644
--- a/docs/api-reference/seller.yaml
+++ b/docs/api-reference/seller.yaml
@@ -204,409 +204,685 @@ paths:
kind: password
schema:
"$ref": "#/components/schemas/AuthProvidersResponse"
- "/api/v3/seller/balances":
+ "/api/v3/seller/auth/invitations/{id}/lookup":
+ parameters:
+ - name: id
+ in: path
+ description: Invitation ID from the emailed link
+ required: true
+ schema:
+ type: string
get:
- summary: List balances
+ summary: Look up an invitation
tags:
- - Earnings
- security:
- - bearer_auth: []
+ - Authentication
description: |
- Where this seller stands with the marketplace, one row per currency
- they have earned or been paid in: what they have earned (settled
- transfers, refund reversals included), what has reached them, what the
- marketplace still owes, and earnings the payout provider has not yet
- confirmed.
+ Reads an invitation from the emailed link, before anyone signs in.
- Computed from the ledger rather than stored, so the rows carry no id
- and there is nothing to page.
+ The acceptance page needs the invited address to decide whether it is
+ asking someone to set a new password or to confirm one they already have.
+
+ Unauthenticated — the ID and token in the emailed link are the
+ credential. A wrong token is indistinguishable from an unknown
+ invitation: both answer `404`, so the endpoint cannot be used to
+ enumerate. An invitation onto the store's own staff rather than a seller
+ answers `404` here too.
parameters:
- - name: X-Spree-Seller-Id
- in: header
+ - name: token
+ in: query
required: true
+ description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: balances listed
+ description: invitation found
content:
application/json:
example:
- data:
- - currency: USD
- settlement_currency: USD
- converted: false
- earned: '40.0'
- display_earned: "$40.00"
- payable: '40.0'
- display_payable: "$40.00"
- paid: '15.0'
- display_paid: "$15.00"
- balance: '25.0'
- display_balance: "$25.00"
- pending: '0.0'
- display_pending: "$0.00"
+ id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Balance"
- required:
- - data
- "/api/v3/seller/orders/{order_id}/claims":
+ "$ref": "#/components/schemas/Invitation"
+ '404':
+ description: wrong token, or an invitation that can no longer be accepted
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Invitation not found, expired, or already accepted.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/auth/invitations/{id}/accept":
parameters:
- - name: order_id
+ - name: id
in: path
- description: Prefixed order ID
+ description: Invitation ID from the emailed link
required: true
schema:
type: string
- get:
- summary: List claims
+ post:
+ summary: Accept an invitation
tags:
- - Claims
- security:
- - bearer_auth: []
- description: Problems reported on one of this seller's orders.
+ - Authentication
+ description: |
+ Accepts the invitation and returns a signed-in seller session, so the new
+ member lands in the panel rather than on a login form.
+
+ The email is never taken from the request — it always comes from the
+ invitation, which is what stops the link being redirected to another
+ address.
+
+ `password` is required when no account exists for the invited address, in
+ which case it sets one. When an account already exists, the same field is
+ how the person proves the account is theirs.
parameters:
- - name: X-Spree-Seller-Id
- in: header
+ - name: token
+ in: query
required: true
+ description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: claims listed
+ description: invitation accepted, session issued
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs
+ user:
+ id: adm_gbHJdmfrXB
+ first_name: Robin
+ last_name: Ellis
+ full_name: Robin Ellis
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ selected_locale:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 44
+ status: approved
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Claim"
- required:
- - data
+ "$ref": "#/components/schemas/AuthResponse"
+ '404':
+ description: wrong token, or an invitation that can no longer be accepted
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Invitation not found, expired, or already accepted.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ password:
+ type: string
+ example: password123
+ password_confirmation:
+ type: string
+ example: password123
+ first_name:
+ type: string
+ example: Robin
+ last_name:
+ type: string
+ example: Ellis
+ "/api/v3/seller/auth/password_resets":
post:
- summary: Open a claim
+ summary: Request password reset
tags:
- - Claims
- security:
- - bearer_auth: []
+ - Authentication
description: |
- Reports that something went wrong with a delivery, to be put right
- without necessarily asking for the goods back.
+ Requests a password reset email for a seller.
- A replacement variant, if one is offered, comes from this seller's own
- catalogue — a rival's is not theirs to promise.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
+ Unauthenticated. Always answers `202`, whether or not the address
+ belongs to a seller, so this cannot be used to discover which accounts
+ exist. A store staff member who runs no seller is treated as no match:
+ they have no seller panel to be sent to.
+
+ `redirect_url` is where the emailed link should point, with the reset
+ token appended as a `token` query param. It is honoured only when it
+ matches one of the store's allowed origins; otherwise it is silently
+ ignored and the server resolves the seller panel origin itself. The
+ email is delivered by Spree via the
+ `seller_user.password_reset_requested` event, which is never forwarded
+ to webhook endpoints.
+ parameters: []
responses:
- '201':
- description: claim opened
+ '202':
+ description: reset requested
content:
application/json:
- schema:
- "$ref": "#/components/schemas/Claim"
+ example:
+ message: If an account exists for that email, password reset instructions
+ have been sent.
requestBody:
content:
application/json:
schema:
type: object
properties:
- items:
- type: array
- items:
- type: object
- properties:
- line_item_id:
- type: string
- quantity:
- type: integer
- description:
- type: string
- nullable: true
- send_replacement:
- type: boolean
- replacement_variant_id:
- type: string
- nullable: true
- refund_amount:
- type: string
- nullable: true
- required:
- - line_item_id
- - quantity
- reason_id:
+ email:
type: string
- nullable: true
- memo:
+ format: email
+ redirect_url:
type: string
- nullable: true
+ example: https://sellers.your-store.com/reset-password
+ description: Must match an allowed origin of the store; ignored
+ otherwise.
required:
- - items
- "/api/v3/seller/orders/{order_id}/claims/{id}/approve":
- parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
+ - email
+ "/api/v3/seller/auth/password_resets/{id}":
patch:
- summary: Approve a claim
+ summary: Reset password
tags:
- - Claims
- security:
- - bearer_auth: []
- description: Accepts that the claim is good.
+ - Authentication
+ description: |
+ Spends a password reset token (the `token` query param from the emailed
+ link), sets the new password and signs the seller in: the response
+ carries a seller JWT and the rotatable refresh token is set in an
+ HttpOnly cookie, so they land in the panel rather than on a login form.
+
+ The token is single-use, and resetting revokes every other session the
+ account holds. A token whose seller membership has since been revoked is
+ refused exactly as an expired one.
parameters:
- - name: X-Spree-Seller-Id
- in: header
+ - name: id
+ in: path
+ description: The reset token from the emailed link
required: true
schema:
type: string
responses:
'200':
- description: claim approved
+ description: password reset
content:
application/json:
+ example:
+ token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImJjMDM3NTNhLTEzN2MtNGM1Zi1hMzM2LWUzMjBlZTNiMjQ5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.EASrzbGpJVyAl10SJyzs8na68Wmvedkm7G66wTBq_0k
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Ariana
+ last_name: Wiza
+ full_name: Ariana Wiza
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ selected_locale:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 81
+ status: approved
schema:
- "$ref": "#/components/schemas/Claim"
- "/api/v3/seller/orders/{order_id}/claims/{id}/resolve":
- parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Resolve a claim
- tags:
- - Claims
- security:
- - bearer_auth: []
- description: |
- Puts the claim right: money back, a replacement shipment, or both.
-
- A refund is bounded by this order's share of the payment, so one
- seller can never settle out of a sibling's money.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: claim resolved
+ "$ref": "#/components/schemas/AuthResponse"
+ '422':
+ description: invalid or expired token
content:
application/json:
+ example:
+ error:
+ code: password_reset_token_invalid
+ message: Password reset token is invalid or has expired.
schema:
- "$ref": "#/components/schemas/Claim"
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- resolution:
- type: string
- enum:
- - refund
- - replacement
- - refund_and_replacement
- refund_method:
+ password:
type: string
- enum:
- - original_payment
- - store_credit
- amount:
+ example: new-password-123
+ password_confirmation:
type: string
- nullable: true
- replacement_line_item_ids:
- type: array
- items:
- type: string
+ example: new-password-123
required:
- - resolution
- "/api/v3/seller/orders/{order_id}/claims/{id}/deny":
- parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Deny a claim
- tags:
- - Claims
- security:
- - bearer_auth: []
- description: Turns the claim down.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: claim denied
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Claim"
- "/api/v3/seller/claim_reasons":
- get:
- summary: List claim reasons
- tags:
- - Claims
- security:
- - bearer_auth: []
- description: |
- What can go wrong with a delivery, as the marketplace defines it.
-
- Read-only: a seller picks from the operator's vocabulary.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: reasons listed
- content:
- application/json:
- example:
- data:
- - id: clr_UkLWZg9DAJ
- name: Arrived damaged
- active: true
- 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/Reason"
- required:
- - data
- "/api/v3/seller/countries":
+ - password
+ - password_confirmation
+ "/api/v3/seller/me":
get:
- summary: List countries
+ summary: Current user
tags:
- - Countries
+ - Account
security:
- bearer_auth: []
description: |
- Countries and their states, for the panel's address forms.
-
- Public reference data — the same list the storefront serves — so it is
- not narrowed to the markets this marketplace sells into: a seller filling
- in a billing address needs every country.
+ The signed-in user, the sellers they may act for, and what they may do on
+ the selected one.
- Unpaginated. An address dropdown needs all ~250 at once.
+ This is the one authenticated endpoint that answers without
+ `X-Spree-Seller-Id` — it is what tells the panel which seller to name.
+ Sending the header narrows `permission_keys` and `permissions` to that
+ seller; without it both are empty, because capability is per seller and
+ there is no answer spanning all of them.
parameters:
- name: X-Spree-Seller-Id
in: header
- required: true
+ required: false
+ description: The seller to report capability for. Omit to list sellers without
+ narrowing permissions.
schema:
type: string
responses:
'200':
- description: countries listed
+ description: current user returned
content:
application/json:
example:
- data:
- - iso: AF
- iso3: AFG
- name: Afghanistan
- states_required: false
- zipcode_required: true
- states:
- - abbr: BDS
- name: Badakhshan
- - abbr: BDG
- name: Badghis
- - abbr: BGL
- name: Baghlan
- - abbr: BAL
- name: Balkh
- - abbr: BAM
- name: Bamian
- - abbr: DAY
- name: Daykondi
- - abbr: FRA
- name: Farah
- - abbr: FYB
- name: Faryab
- - abbr: GHA
- name: Ghazni
- - abbr: GHO
- name: Ghowr
- - abbr: HEL
- name: Helmand
- - abbr: HER
- name: Herat
- - abbr: JOW
- name: Jowzjan
- - abbr: KAB
- name: Kabul [Kabol]
- - abbr: KAN
- name: Kandahar
- - abbr: KAP
- name: Kapisa
- - abbr: KHO
- name: Khowst
- - abbr: KNR
- name: Konar [Kunar]
- - abbr: KDZ
- name: Kondoz [Kunduz]
- - abbr: LAG
- name: Laghman
- - abbr: NAN
- name: Nangrahar [Nangarhar]
- - abbr: NIM
- name: Nimruz
- - abbr: NUR
- name: Nurestan
- - abbr: PIA
- name: Paktia
- - abbr: PKA
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Nadia
+ last_name: Effertz
+ full_name: Nadia Effertz
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ selected_locale:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 54
+ slug: seller-54
+ status: approved
+ permissions:
+ - allow: true
+ actions:
+ - read
+ subjects:
+ - Spree::Country
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ subjects:
+ - Spree::State
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ subjects:
+ - Spree::Store
+ has_conditions: true
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Product
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Variant
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::OptionType
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::OptionValue
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Price
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::PriceList
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::PriceRule
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Catalog
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::CatalogProduct
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::CatalogAssignment
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::CustomField
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::DigitalAsset
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::Import
+ has_conditions: false
+ - allow: true
+ actions:
+ - read
+ - admin
+ subjects:
+ - Spree::ImportRow
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Product
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Variant
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::OptionType
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::OptionValue
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Price
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::PriceList
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::PriceRule
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Catalog
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::CatalogProduct
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::CatalogAssignment
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::CustomField
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::DigitalAsset
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::Import
+ has_conditions: false
+ - allow: true
+ actions:
+ - manage
+ subjects:
+ - Spree::ImportRow
+ has_conditions: false
+ permission_keys:
+ - read_products
+ - write_products
+ schema:
+ "$ref": "#/components/schemas/SellerMeResponse"
+ '401':
+ description: missing or invalid token
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update your account
+ tags:
+ - Account
+ security:
+ - bearer_auth: []
+ description: |
+ Edits the signed-in person's own account — the name and photo their team
+ sees, and the language their panel displays.
+
+ This is the person, not the business: the seller they act for is
+ `PATCH /profile`. Like `GET /me` it answers without
+ `X-Spree-Seller-Id`, because the account is the same whichever seller
+ they are acting for.
+
+ `avatar` takes an ActiveStorage direct-upload signed id to set the
+ photo, or `null` to remove it; omit it to leave the current one alone.
+ `email` is identity-bound and cannot be changed here.
+ parameters: []
+ responses:
+ '200':
+ description: account updated
+ content:
+ application/json:
+ example:
+ user:
+ id: adm_UkLWZg9DAJ
+ first_name: Ada
+ last_name: Lovelace
+ full_name: Ada Lovelace
+ created_at: '2026-01-15T12:00:00.000Z'
+ avatar_url:
+ selected_locale:
+ sellers:
+ - id: sel_UkLWZg9DAJ
+ name: Seller 56
+ slug: seller-56
+ status: approved
+ permissions: []
+ permission_keys: []
+ schema:
+ "$ref": "#/components/schemas/SellerMeResponse"
+ '422':
+ description: the photo is not a web image
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Avatar has an invalid content type (authorized content
+ types are PNG, JPG, GIF, WEBP)
+ details:
+ avatar:
+ - has an invalid content type (authorized content types are PNG,
+ JPG, GIF, WEBP)
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '401':
+ description: missing or invalid token
+ content:
+ application/json:
+ example:
+ error:
+ code: authentication_required
+ message: Authentication required
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ first_name:
+ type: string
+ example: Ada
+ last_name:
+ type: string
+ example: Lovelace
+ selected_locale:
+ type: string
+ example: de
+ description: Panel display language, as a code the panel ships.
+ avatar:
+ type: string
+ nullable: true
+ description: Direct-upload signed id, or `null` to remove the photo.
+ "/api/v3/seller/countries":
+ get:
+ summary: List countries
+ tags:
+ - Countries
+ security:
+ - bearer_auth: []
+ description: |
+ Countries and their states, for the panel's address forms.
+
+ Public reference data — the same list the storefront serves — so it is
+ not narrowed to the markets this marketplace sells into: a seller filling
+ in a billing address needs every country.
+
+ Unpaginated. An address dropdown needs all ~250 at once.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: countries listed
+ content:
+ application/json:
+ example:
+ data:
+ - iso: AF
+ iso3: AFG
+ name: Afghanistan
+ states_required: false
+ zipcode_required: true
+ states:
+ - abbr: BDS
+ name: Badakhshan
+ - abbr: BDG
+ name: Badghis
+ - abbr: BGL
+ name: Baghlan
+ - abbr: BAL
+ name: Balkh
+ - abbr: BAM
+ name: Bamian
+ - abbr: DAY
+ name: Daykondi
+ - abbr: FRA
+ name: Farah
+ - abbr: FYB
+ name: Faryab
+ - abbr: GHA
+ name: Ghazni
+ - abbr: GHO
+ name: Ghowr
+ - abbr: HEL
+ name: Helmand
+ - abbr: HER
+ name: Herat
+ - abbr: JOW
+ name: Jowzjan
+ - abbr: KAB
+ name: Kabul [Kabol]
+ - abbr: KAN
+ name: Kandahar
+ - abbr: KAP
+ name: Kapisa
+ - abbr: KHO
+ name: Khowst
+ - abbr: KNR
+ name: Konar [Kunar]
+ - abbr: KDZ
+ name: Kondoz [Kunduz]
+ - abbr: LAG
+ name: Laghman
+ - abbr: NAN
+ name: Nangrahar [Nangarhar]
+ - abbr: NIM
+ name: Nimruz
+ - abbr: NUR
+ name: Nurestan
+ - abbr: PIA
+ name: Paktia
+ - abbr: PKA
name: Paktika
- abbr: PAN
name: Panjshir
@@ -1419,17 +1695,17 @@ paths:
zipcode_required: true
states:
- abbr: BR
- name: Brestskaya voblasts' (be) Brestskaya oblast' (ru)
+ name: Brest
- abbr: HO
- name: Homyel'skaya voblasts' (be) Gomel'skaya oblast' (ru)
+ name: Homel
- abbr: HR
- name: Hrodzenskaya voblasts' (be) Grodnenskaya oblast' (ru)
+ name: Hrodna
- abbr: MA
- name: Mahilyowskaya voblasts' (be) Mogilevskaya oblast' (ru)
+ name: Magileu
- abbr: MI
- name: Minskaya voblasts' (be) Minskaya oblast' (ru)
+ name: Minsk Region
- abbr: VI
- name: Vitsyebskaya voblasts' (be) Vitebskaya oblast' (ru)
+ name: Vitebsk
- abbr: HM
name: Мінск
- iso: BE
@@ -1439,31 +1715,31 @@ paths:
zipcode_required: true
states:
- abbr: VAN
- name: Antwerpen (nl)
- - abbr: WBR
- name: Brabant Wallon (fr)
+ name: Antwerp
- abbr: BRU
name: Brussels
+ - abbr: VOV
+ name: East Flanders
+ - abbr: VBR
+ name: Flemish Brabant
- abbr: WHT
- name: Hainaut (fr)
+ name: Hainaut
- abbr: VLI
- name: Limburg (nl)
+ name: Limburg
- abbr: WLG
- name: Liège (fr)
+ name: Liège
- abbr: WLX
- name: Luxembourg (fr)
+ name: Luxembourg
- abbr: WNA
- name: Namur (fr)
- - abbr: VOV
- name: Oost-Vlaanderen (nl)
- - abbr: VBR
- name: Vlaams Brabant (nl)
+ name: Namur
- abbr: VLG
name: Vlaams Gewest
- abbr: WAL
name: Wallonië
+ - abbr: WBR
+ name: Walloon Brabant
- abbr: VWV
- name: West-Vlaanderen (nl)
+ name: West Flanders
- iso: BZ
iso3: BLZ
name: Belize
@@ -2294,6 +2570,8 @@ paths:
name: Hubei
- abbr: HN
name: Hunan
+ - abbr: NM
+ name: Inner Mongolia
- abbr: JS
name: Jiangsu
- abbr: JX
@@ -2302,8 +2580,6 @@ paths:
name: Jilin
- abbr: LN
name: Liaoning
- - abbr: NM
- name: Nei Mongol (mn)
- abbr: NX
name: Ningxia
- abbr: QH
@@ -6887,7 +7163,7 @@ paths:
- abbr: BRR
name: Berrechid
- abbr: BOD
- name: Boujdour (EH)
+ name: Boujdour
- abbr: BOM
name: Boulemane
- abbr: '05'
@@ -6902,8 +7178,6 @@ paths:
name: Chichaoua
- abbr: CHT
name: Chtouka-Ait Baha
- - abbr: '12'
- name: Dakhla-Oued Ed-Dahab (EH)
- abbr: DRI
name: Driouch
- abbr: '08'
@@ -6915,7 +7189,7 @@ paths:
- abbr: ERR
name: Errachidia
- abbr: ESM
- name: Es Smara (EH)
+ name: Es Semara
- abbr: ESI
name: Essaouira
- abbr: FAH
@@ -6955,7 +7229,7 @@ paths:
- abbr: LAR
name: Larache
- abbr: LAA
- name: Laâyoune* (EH)
+ name: Laâyoune
- abbr: '11'
name: Laâyoune-Sakia El Hamra (EH-partial)
- abbr: MAR
@@ -6979,7 +7253,7 @@ paths:
- abbr: OUA
name: Ouarzazate
- abbr: OUD
- name: Oued ed Dahab (EH)
+ name: Oued Ed-Dahab
- abbr: OUZ
name: Ouezzane
- abbr: OUJ
@@ -7010,6 +7284,8 @@ paths:
name: Skhirate-Témara
- abbr: '09'
name: Souss-Massa
+ - abbr: '12'
+ name: Tadla-Azilal
- abbr: TNT
name: Tan-Tan
- abbr: TNG
@@ -7751,7 +8027,7 @@ paths:
- abbr: JK
name: Azad Kashmir
- abbr: BA
- name: Baluchistan (en)
+ name: Balochistan
- abbr: GB
name: Gilgit-Baltistan
- abbr: IS
@@ -7761,7 +8037,7 @@ paths:
- abbr: PB
name: Punjab
- abbr: SD
- name: Sind (en)
+ name: Sindh
- iso: PW
iso3: PLW
name: Palau
@@ -10000,57 +10276,57 @@ paths:
zipcode_required: true
states:
- abbr: AG
- name: Aargau (de)
+ name: Aargau
- abbr: AR
- name: Appenzell Ausserrhoden (de)
+ name: Appenzell Ausserrhoden
- abbr: AI
- name: Appenzell Innerrhoden (de)
+ name: Appenzell Innerrhoden
- abbr: BL
- name: Basel-Landschaft (de)
+ name: Basel-Landschaft
- abbr: BS
- name: Basel-Stadt (de)
+ name: Basel-Stadt
- abbr: BE
- name: Bern (de)
+ name: Bern
- abbr: FR
- name: Fribourg (fr)
+ name: Fribourg
- abbr: GE
- name: Genève (fr)
+ name: Geneva
- abbr: GL
- name: Glarus (de)
+ name: Glarus
- abbr: GR
- name: Graubünden (de)
+ name: Graubünden
- abbr: JU
- name: Jura (fr)
+ name: Jura
- abbr: LU
- name: Luzern (de)
+ name: Lucerne
- abbr: NE
- name: Neuchâtel (fr)
+ name: Neuchâtel
- abbr: NW
- name: Nidwalden (de)
+ name: Nidwalden
- abbr: OW
- name: Obwalden (de)
- - abbr: SG
- name: Sankt Gallen (de)
+ name: Obwalden
- abbr: SH
- name: Schaffhausen (de)
+ name: Schaffhausen
- abbr: SZ
- name: Schwyz (de)
+ name: Schwyz
- abbr: SO
- name: Solothurn (de)
+ name: Solothurn
+ - abbr: SG
+ name: St. Gallen
- abbr: TG
- name: Thurgau (de)
+ name: Thurgau
- abbr: TI
- name: Ticino (it)
+ name: Ticino
- abbr: UR
- name: Uri (de)
+ name: Uri
- abbr: VS
- name: Valais (fr)
+ name: Valais
- abbr: VD
- name: Vaud (fr)
+ name: Vaud
- abbr: ZG
- name: Zug (de)
+ name: Zug
- abbr: ZH
- name: Zürich (de)
+ name: Zürich
- iso: SY
iso3: SYR
name: Syrian Arab Republic
@@ -12805,27 +13081,27 @@ paths:
required:
- data
- meta
- "/api/v3/seller/direct_uploads":
- post:
- summary: Create a direct upload
+ "/api/v3/seller/onboarding":
+ get:
+ summary: Get onboarding checklist
tags:
- - Uploads
+ - Onboarding
security:
- bearer_auth: []
description: |
- Presigns an upload target for a file the seller is about to send.
+ What this marketplace asks of the seller before it will admit them.
- Three steps: post the file's metadata here, `PUT` the bytes to the
- returned `direct_upload.url` with the headers it names, then send the
- returned `signed_id` wherever the file belongs — as a requirement
- submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the
- profile.
+ Singular: the checklist is always the acting seller's. Every answer is
+ computed server-side by the same evaluator the operator's own view uses,
+ so the panel and the operator can never show different progress.
- The blob is attached to nothing at this point. The endpoint that consumes
- the `signed_id` is the one that checks ownership.
+ `progress` counts optional requirements too — it is how far along the
+ checklist is, not how close to approval. Read `blocking` on each
+ requirement for that.
- `checksum` is the file's MD5 digest, base64-encoded — the storage service
- verifies the upload against it.
+ Each requirement's `id` is what a submission is posted against. A
+ marketplace that asks for nothing returns an empty list, which is a
+ complete answer rather than a missing one.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -12833,62 +13109,43 @@ paths:
schema:
type: string
responses:
- '201':
- description: upload target created
+ '200':
+ description: checklist returned
content:
application/json:
example:
- direct_upload:
- url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--98397ef4b61ccb9056997559e739cf48aed9b4f0
- headers:
- Content-Type: application/pdf
- signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--8689a8a2636cd26ac1081498c4c5d7b905fcd0ee
+ status: approved
+ progress:
+ done: 0
+ total: 0
+ requirements: []
schema:
- "$ref": "#/components/schemas/DirectUploadResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- blob:
- type: object
- properties:
- filename:
- type: string
- example: registration.pdf
- byte_size:
- type: integer
- example: 51234
- checksum:
- type: string
- description: Base64-encoded MD5 digest of the file
- example: rL0Y20zC+Fzt72VPzMSk2A==
- content_type:
- type: string
- example: application/pdf
- required:
- - filename
- - byte_size
- - checksum
- - content_type
- required:
- - blob
- "/api/v3/seller/orders/{order_id}/exchanges":
- parameters:
- - name: order_id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
- get:
- summary: List exchanges
+ "$ref": "#/components/schemas/SellerOnboardingResponse"
+ '403':
+ description: no seller named, or not a member of it
+ content:
+ application/json:
+ example:
+ error:
+ code: access_denied
+ message: You do not have access to this seller.
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/onboarding/submit_for_review":
+ post:
+ summary: Submit for review
tags:
- - Exchanges
+ - Onboarding
security:
- bearer_auth: []
- description: Goods swapped for different ones on one of this seller's orders.
+ description: |
+ Says the seller is ready, moving them from `onboarding` to
+ `ready_for_review`.
+
+ Refused with `422` when something required is still outstanding — the
+ message names the blocking requirements, and the seller's status is
+ unchanged. Returns the same payload as the checklist so the panel can
+ re-render from one response.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -12897,30 +13154,55 @@ paths:
type: string
responses:
'200':
- description: exchanges listed
+ description: submitted for review
+ content:
+ application/json:
+ example:
+ status: ready_for_review
+ progress:
+ done: 0
+ total: 0
+ requirements: []
+ schema:
+ "$ref": "#/components/schemas/SellerOnboardingResponse"
+ '422':
+ description: something required is still outstanding
content:
application/json:
+ example:
+ error:
+ code: processing_error
+ message: Requirements Accept terms is not complete
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Exchange"
- required:
- - data
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/requirements/{requirement_id}/submissions":
+ parameters:
+ - name: requirement_id
+ in: path
+ description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`
+ required: true
+ schema:
+ type: string
post:
- summary: Open an exchange
+ summary: Submit against a requirement
tags:
- - Exchanges
+ - Onboarding
security:
- bearer_auth: []
description: |
- Swaps goods for different ones.
+ What the seller says about one requirement: an attestation they tick, a
+ document they upload, a reference they paste.
- The replacement comes from this seller's own catalogue: it is stock
- they will send, so a variant belonging to another seller is not theirs
- to promise and reads as missing.
+ Create only. A submission records what was said and when, so a seller who
+ needs to correct something submits again rather than editing, and the
+ latest one counts.
+
+ `file` is **not** a multipart upload — it is the `signed_id` returned by
+ `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage
+ by the time this runs.
+
+ An attestation is accepted on the spot; a requirement the operator
+ reviews comes back `pending`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -12929,105 +13211,167 @@ paths:
type: string
responses:
'201':
- description: exchange opened
+ description: submission recorded
content:
application/json:
+ example:
+ id: selsub_UkLWZg9DAJ
+ status: accepted
+ note: Confirmed.
+ review_note:
+ reference:
+ reviewed_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ file_url:
+ file_name:
schema:
- "$ref": "#/components/schemas/Exchange"
+ "$ref": "#/components/schemas/RequirementSubmission"
+ '404':
+ description: a requirement belonging to another marketplace
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Seller requirement not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- items:
- type: array
- items:
- type: object
- properties:
- fulfillment_item_id:
- type: string
- new_variant_id:
- type: string
- quantity:
- type: integer
- required:
- - fulfillment_item_id
- - new_variant_id
- - quantity
- reason_id:
+ note:
type: string
- nullable: true
- stock_location_id:
+ description: Anything the seller wants to say alongside the submission
+ reference:
type: string
- nullable: true
- memo:
+ description: A reference number or external identifier, for requirements
+ that ask for one
+ file:
type: string
- nullable: true
- required:
- - items
- "/api/v3/seller/orders/{order_id}/exchanges/{id}/fulfill":
+ description: A direct-upload `signed_id`, for requirements that
+ ask for a document
+ "/api/v3/seller/requirement_submissions/{id}/download":
parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- name: id
in: path
+ description: Submission ID
required: true
schema:
type: string
- patch:
- summary: Send the replacement
+ get:
+ summary: Download a submitted document
tags:
- - Exchanges
+ - Onboarding
security:
- bearer_auth: []
description: |
- Sends the replacement goods, settling any price difference at the same
- time — which is why it takes a refund method.
+ Streams the file attached to one of this seller's submissions.
+
+ Served through the API rather than from a storage URL on purpose: these
+ are identity and registration documents, so every read is authorized
+ against the acting seller. Another seller's submission answers `404`.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '404':
+ description: another seller's submission
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Seller requirement submission not found
+ application/octet-stream:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/policies":
+ get:
+ summary: List policies
+ tags:
+ - Policies
+ security:
+ - bearer_auth: []
+ description: |
+ This seller's own policy documents.
+
+ Rooted in the acting seller, so the marketplace operator's store
+ policies and every other seller's are invisible here. A seller starts
+ with none: what they are expected to publish is decided by the
+ marketplace's onboarding checklist.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
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 (max 100)
+ schema:
+ type: integer
responses:
'200':
- description: replacement sent
+ description: policies listed
content:
application/json:
+ example:
+ data:
+ - id: pol_uw2YK1rnl0
+ name: Returns Policy
+ slug: returns-policy
+ body: Send anything back within 30 days.
+ body_html: "<p>Send anything back within 30 days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Exchange"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- refund_method:
- type: string
- enum:
- - original_payment
- - store_credit
- "/api/v3/seller/exports":
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Policy"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
post:
- summary: Create an export
+ summary: Create a policy
tags:
- - Exports
+ - Policies
security:
- bearer_auth: []
description: |
- Queues a CSV of this seller's own records.
-
- Only datasets that can be narrowed to a single seller are offered, so
- an export can never contain another seller's rows however it is
- filtered. The seller and the store come from the request context
- whatever the payload says.
+ Publishes one of this seller's policies. `body` accepts HTML and is
+ sanitized before it is stored.
- Generation runs in the background: poll `GET /api/v3/seller/exports/{id}`
- until `done` is true, then fetch `download_url`.
+ When the marketplace requires a named policy, use that exact name —
+ the onboarding check matches on it.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -13036,80 +13380,51 @@ paths:
type: string
responses:
'201':
- description: export queued
+ description: policy created
content:
application/json:
example:
- id: exp_UkLWZg9DAJ
- number: EF1001
- format: csv
- created_at: '2026-01-15T12:00:00.000Z'
+ id: pol_OIJLhNcSbf
+ name: Shipping Policy
+ slug: shipping-policy
+ body: Orders leave the workshop within two working days.
+ body_html: "<p>Orders leave the workshop within two working days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
- type: orders
- user_id: adm_UkLWZg9DAJ
- done: false
- filename:
- byte_size:
- download_url:
- schema:
- "$ref": "#/components/schemas/Export"
- '422':
- description: type cannot be scoped to one seller
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: 'Unsupported export type. Supported types: orders, products'
+ created_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/Policy"
requestBody:
content:
application/json:
schema:
type: object
properties:
- type:
+ name:
type: string
- enum:
- - orders
- - products
- description: Which dataset to export.
- record_selection:
+ example: Shipping Policy
+ slug:
type: string
- enum:
- - filtered
- - all
- description: "`filtered` (default) honours `search_params`; `all`
- exports everything this seller owns."
- search_params:
- type: object
- description: Ransack predicates, the same shape the list endpoints
- take. Ignored when `record_selection` is `all`.
- additionalProperties: true
- results_url:
+ example: shipping-policy
+ body:
type: string
- description: Panel URL the export-done email links back to. Honoured
- only when it matches one of the store's allowed origins.
+ example: "<p>Orders leave the workshop within two working days.</p>"
required:
- - type
- "/api/v3/seller/exports/{id}":
+ - name
+ "/api/v3/seller/policies/{id}":
parameters:
- name: id
in: path
- description: Export ID
required: true
+ description: Policy prefixed ID or slug
schema:
type: string
get:
- summary: Get an export
+ summary: Get a policy
tags:
- - Exports
+ - Policies
security:
- bearer_auth: []
- description: |
- Reads one of this seller's exports. Poll this until `done` is true,
- then fetch `download_url`.
+ description: Returns one of this seller's policies, by prefixed ID or slug.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -13118,52 +13433,36 @@ paths:
type: string
responses:
'200':
- description: export found
+ description: policy found
content:
application/json:
example:
- id: exp_UkLWZg9DAJ
- number: EF1001
- format: csv
- created_at: '2026-01-15T12:00:00.000Z'
+ id: pol_uw2YK1rnl0
+ name: Returns Policy
+ slug: returns-policy
+ body: Send anything back within 30 days.
+ body_html: "<p>Send anything back within 30 days.</p>"
updated_at: '2026-01-15T12:00:00.000Z'
- type: orders
- user_id: adm_UkLWZg9DAJ
- done: false
- filename:
- byte_size:
- download_url:
+ created_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/Export"
+ "$ref": "#/components/schemas/Policy"
'404':
- description: another seller's export
+ description: policy not found
content:
application/json:
example:
error:
code: record_not_found
- message: Export not found
+ message: Policy not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/exports/{id}/download":
- parameters:
- - name: id
- in: path
- description: Export ID
- required: true
- schema:
- type: string
- get:
- summary: Download an export
+ patch:
+ summary: Update a policy
tags:
- - Exports
+ - Policies
security:
- bearer_auth: []
- description: |
- Streams the finished CSV.
-
- The bytes are served by this endpoint rather than through a redirect,
- so the seller's own session authorizes every download.
+ description: Rewrites one of this seller's policies.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -13171,108 +13470,90 @@ paths:
schema:
type: string
responses:
- '422':
- description: export is still being written
- content:
- application/json:
- example:
- error:
- code: export_not_ready
- message: Export is not ready yet
- text/csv:
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: another seller's export
+ '200':
+ description: policy updated
content:
application/json:
example:
- error:
- code: record_not_found
- message: Export not found
- text/csv:
+ id: pol_uw2YK1rnl0
+ name: Returns Policy
+ slug: returns-policy
+ body: Send anything back within 60 days.
+ body_html: "<p>Send anything back within 60 days.</p>"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/orders/{order_id}/fulfillments":
- parameters:
- - name: order_id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
+ "$ref": "#/components/schemas/Policy"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ slug:
+ type: string
+ body:
+ type: string
+ delete:
+ summary: Delete a policy
+ tags:
+ - Policies
+ security:
+ - bearer_auth: []
+ description: Withdraws one of this seller's policies.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: policy deleted
+ "/api/v3/seller/product_types":
get:
- summary: List fulfillments
+ summary: List product types
tags:
- - Fulfillments
+ - Product Types
security:
- bearer_auth: []
description: |
- The parcels this seller owes on one order.
+ The product types a seller may list a product against.
- Reached through the order, which is itself fetched through the acting
- seller — so a fulfillment on somebody else's order is unreachable
- whatever ids are sent.
+ Read only. A type is the template that hands a product its option types
+ and its delivery profile, so a seller picks one when listing; defining
+ types is the marketplace's. Send the chosen `id` as `product_type_id`
+ on the product.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
schema:
type: string
- responses:
- '200':
- description: fulfillments listed
- content:
- application/json:
- example:
- data:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: unfulfilled
- tracking: U10000
- tracking_url:
- fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 81
- stock_location_name: Vernie Lehner
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 1869315
- sku: SKU-252
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 81
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
+ - name: page
+ in: query
+ required: false
+ description: Page number
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: Records per page (max 100)
+ schema:
+ type: integer
+ responses:
+ '200':
+ description: product types listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: pt_UkLWZg9DAJ
+ name: Apparel
+ option_type_labels: []
meta:
page: 1
limit: 25
@@ -13289,317 +13570,176 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/Fulfillment"
+ "$ref": "#/components/schemas/ProductType"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
required:
- data
- "/api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill":
- parameters:
- - name: order_id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
- - name: id
- in: path
- description: Prefixed fulfillment ID
- required: true
- schema:
- type: string
- patch:
- summary: Fulfill (ship) a parcel
+ - meta
+ "/api/v3/seller/product_types/{id}":
+ get:
+ summary: Get a product type
tags:
- - Fulfillments
+ - Product Types
security:
- bearer_auth: []
- description: |
- Marks the parcel shipped.
-
- This is the same workflow the marketplace operator runs, so the
- customer's dispatch email, the label purchase and any extension hooks
- happen exactly as they would had the operator shipped it.
-
- `items` narrows the dispatch to part of what the fulfillment holds; the
- remainder splits onto a new one. Omit it to ship the lot.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
schema:
type: string
- responses:
- '200':
- description: parcel shipped
- content:
- application/json:
- example:
- id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: fulfilled
- tracking: TRACK-1
- tracking_url:
- fulfilled_at: '2026-01-15T12:00:00.000Z'
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 82
- stock_location_name: Mirta Herman
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 187961
- sku: SKU-253
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 82
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: TRACK-1
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
- schema:
- "$ref": "#/components/schemas/Fulfillment"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- tracking:
- type: string
- description: Carrier tracking number
- tracking_carrier:
- type: string
- description: Carrier name
- notify_customer:
- type: boolean
- description: Send the dispatch email (default true)
- items:
- type: array
- description: Ship only these lines; the rest split onto a new fulfillment
- items:
- type: object
- properties:
- item_id:
- type: string
- description: Prefixed line item ID
- quantity:
- type: integer
- required:
- - item_id
- - quantity
- "/api/v3/seller/orders/{order_id}/fulfillments/{id}":
- parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Update tracking
- tags:
- - Fulfillments
- security:
- - bearer_auth: []
- description: |
- Adds or corrects the tracking number and its carrier.
-
- Deliberately narrow: where a parcel ships from and which service
- carries it are the marketplace's arrangements, so they are not
- editable here.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
+ - name: id
+ in: path
required: true
+ description: Product type ID
schema:
type: string
responses:
'200':
- description: tracking recorded
+ description: product type found
content:
application/json:
example:
- id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: unfulfilled
- tracking: TRACK-2
- tracking_url: https://www.ups.com/track?tracknum=TRACK-2
- fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 83
- stock_location_name: Eugena Schultz
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 1883170
- sku: SKU-254
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 83
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: TRACK-2
- carrier: ups
- carrier_name: UPS
- service:
- status: pending
- tracking_url: https://www.ups.com/track?tracknum=TRACK-2
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
+ id: pt_UkLWZg9DAJ
+ name: Apparel
+ option_type_labels: []
schema:
- "$ref": "#/components/schemas/Fulfillment"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- tracking:
- type: string
- nullable: true
- tracking_carrier:
- type: string
- nullable: true
- "/api/v3/seller/orders/{order_id}/fulfillments/{id}/cancel":
- parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Cancel a parcel
+ "$ref": "#/components/schemas/ProductType"
+ "/api/v3/seller/products":
+ get:
+ summary: List products
tags:
- - Fulfillments
+ - Products
security:
- bearer_auth: []
description: |
- A parcel this seller is not going to send after all. The goods go back
- on the shelf and the carrier is stood down.
+ The seller's own catalog — the products they own outright.
+
+ Every call is rooted in the acting seller server-side, so this can never
+ return another seller's product or one the marketplace operator sells
+ first-party.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
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 (max 100)
+ schema:
+ type: integer
+ - name: sort
+ in: query
+ required: false
+ description: Sort field; prefix with `-` for descending
+ schema:
+ type: string
responses:
'200':
- description: parcel canceled
+ description: products listed
content:
application/json:
example:
- id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: canceled
- tracking: U10000
- tracking_url:
- fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 84
- stock_location_name: Karyn Moore
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 1897276
- sku: SKU-255
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 84
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
+ data:
+ - id: prod_UkLWZg9DAJ
+ name: Product 2053250
+ slug: product-2053250
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 1
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Maiores ut qui dolores ab autem. Architecto quos sequi
+ minus debitis tempora molestiae. Quasi officiis minus voluptatum
+ eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati
+ ducimus. Provident quo amet nostrum sed assumenda cum odio. Distinctio
+ perferendis quasi nisi exercitationem veritatis minima esse. In
+ velit at corporis nobis. Voluptate mollitia nam pariatur enim.
+ Recusandae necessitatibus earum deserunt sapiente eveniet quidem
+ unde. Consectetur ab perspiciatis veniam dolor tempora. Omnis
+ odit autem quae repellat. Delectus corrupti ea nisi reiciendis
+ atque iure a molestias. Repellendus laboriosam sint molestias
+ debitis in. Minima omnis accusantium modi accusamus doloribus
+ fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.
+ description_html: |-
+ Maiores ut qui dolores ab autem. Architecto quos sequi minus debitis tempora molestiae. Quasi officiis minus voluptatum eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati ducimus. Provident quo amet nostrum sed assumenda cum odio.
+ Distinctio perferendis quasi nisi exercitationem veritatis minima esse. In velit at corporis nobis. Voluptate mollitia nam pariatur enim. Recusandae necessitatibus earum deserunt sapiente eveniet quidem unde.
+ Consectetur ab perspiciatis veniam dolor tempora. Omnis odit autem quae repellat. Delectus corrupti ea nisi reiciendis atque iure a molestias.
+ Repellendus laboriosam sint molestias debitis in. Minima omnis accusantium modi accusamus doloribus fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: active
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/Fulfillment"
- "/api/v3/seller/tracking_carriers":
- get:
- summary: List tracking carriers
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Product"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ post:
+ summary: Create a product
tags:
- - Fulfillments
+ - Products
security:
- bearer_auth: []
description: |
- The carriers a tracking number can be pinned to, from the registry —
- so a carrier an extension adds appears without a client change.
+ Creates a product owned by the acting seller.
+
+ The seller and the store are taken from the request context whatever the
+ payload says, so a product cannot be created against another seller.
+
+ The operator's own settings — tax category, delivery profile and whether
+ the product is promotionable — are not writable here; they belong to the
+ marketplace, not the seller.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -13607,211 +13747,312 @@ paths:
schema:
type: string
responses:
- '200':
- description: carriers listed
+ '201':
+ description: product created
content:
application/json:
example:
- data:
- - id: australia_post
- name: Australia Post
- - id: canada_post
- name: Canada Post
- - id: chronopost
- name: Chronopost
- - id: colissimo
- name: Colissimo
- - id: dhl
- name: DHL Express
- - id: dpd
- name: DPD
- - id: deutsche_post
- name: Deutsche Post DHL
- - id: evri
- name: Evri
- - id: fedex
- name: FedEx
- - id: gls
- name: GLS
- - id: inpost
- name: InPost
- - id: poczta_polska
- name: Poczta Polska
- - id: postnl
- name: PostNL
- - id: royal_mail
- name: Royal Mail
- - id: ups
- name: UPS
- - id: usps
- name: USPS
+ id: prod_gbHJdmfrXB
+ name: Hand-thrown mug
+ slug: hand-thrown-mug
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 0
+ available_on:
+ preorder_ships_at:
+ purchasable: false
+ preorder: false
+ in_stock: false
+ backorderable: false
+ available: false
+ description:
+ description_html:
+ default_variant_id: variant_gbHJdmfrXB
+ buy_box_variant_id: variant_gbHJdmfrXB
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_gbHJdmfrXB
+ amount: '24.0'
+ amount_in_cents: 2400
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$24.00"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: draft
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
schema:
- type: object
- properties:
- data:
- type: array
- items:
- type: object
- properties:
- id:
- type: string
- name:
- type: string
- required:
- - id
- - name
- required:
- - data
- "/api/v3/seller/auth/invitations/{id}/lookup":
+ "$ref": "#/components/schemas/Product"
+ '422':
+ description: validation failed
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Hand-thrown mug
+ description:
+ type: string
+ slug:
+ type: string
+ example: hand-thrown-mug
+ status:
+ type: string
+ example: draft
+ meta_title:
+ type: string
+ meta_description:
+ type: string
+ meta_keywords:
+ type: string
+ product_type_id:
+ type: string
+ example: ptype_abc123
+ tags:
+ type: array
+ items:
+ type: string
+ example:
+ - ceramics
+ - handmade
+ category_ids:
+ type: array
+ items:
+ type: string
+ example:
+ - cat_abc123
+ metadata:
+ type: object
+ additionalProperties: true
+ prices:
+ type: array
+ items:
+ type: object
+ properties:
+ amount:
+ type: string
+ example: '24.00'
+ compare_at_amount:
+ type: string
+ example: '30.00'
+ currency:
+ type: string
+ example: USD
+ required:
+ - name
+ "/api/v3/seller/products/{id}":
parameters:
- name: id
in: path
- description: Invitation ID from the emailed link
+ description: Product ID
required: true
schema:
type: string
get:
- summary: Look up an invitation
+ summary: Get a product
tags:
- - Authentication
+ - Products
+ security:
+ - bearer_auth: []
description: |
- Reads an invitation from the emailed link, before anyone signs in.
-
- The acceptance page needs the invited address to decide whether it is
- asking someone to set a new password or to confirm one they already have.
+ A product the acting seller owns.
- Unauthenticated — the ID and token in the emailed link are the
- credential. A wrong token is indistinguishable from an unknown
- invitation: both answer `404`, so the endpoint cannot be used to
- enumerate. An invitation onto the store's own staff rather than a seller
- answers `404` here too.
+ An id belonging to another seller answers `404`, not `403` — the seller
+ is not told the record exists.
parameters:
- - name: token
- in: query
+ - name: X-Spree-Seller-Id
+ in: header
required: true
- description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: invitation found
+ description: product returned
content:
application/json:
example:
- id: inv_UkLWZg9DAJ
+ id: prod_UkLWZg9DAJ
+ name: Product 2086710
+ slug: product-2086710
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 1
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Aliquid voluptate laudantium necessitatibus quidem eaque.
+ Sapiente at autem eveniet exercitationem odio in dolores. Laborum
+ accusantium nulla autem tempora qui inventore assumenda molestiae.
+ Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi
+ eius provident unde neque in. Earum pariatur enim odit delectus
+ accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam
+ ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident
+ at itaque temporibus. Adipisci iste beatae quibusdam perferendis
+ ea blanditiis saepe facilis.
+ description_html: |-
+ Aliquid voluptate laudantium necessitatibus quidem eaque. Sapiente at autem eveniet exercitationem odio in dolores. Laborum accusantium nulla autem tempora qui inventore assumenda molestiae. Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi eius provident unde neque in.
+ Earum pariatur enim odit delectus accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident at itaque temporibus. Adipisci iste beatae quibusdam perferendis ea blanditiis saepe facilis.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: active
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
- expires_at: '2026-01-29T12:00:00.000Z'
- accepted_at:
- status: pending
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=RgGhNP1euUCS75Nc3V1Y7YQF"
+ updated_at: '2026-01-15T12:00:00.000Z'
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/Invitation"
+ "$ref": "#/components/schemas/Product"
'404':
- description: wrong token, or an invitation that can no longer be accepted
+ description: another seller's product
content:
application/json:
example:
error:
code: record_not_found
- message: Invitation not found, expired, or already accepted.
+ message: Product not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/auth/invitations/{id}/accept":
- parameters:
- - name: id
- in: path
- description: Invitation ID from the emailed link
- required: true
- schema:
- type: string
- post:
- summary: Accept an invitation
+ patch:
+ summary: Update a product
tags:
- - Authentication
- description: |
- Accepts the invitation and returns a signed-in seller session, so the new
- member lands in the panel rather than on a login form.
-
- The email is never taken from the request — it always comes from the
- invitation, which is what stops the link being redirected to another
- address.
-
- `password` is required when no account exists for the invited address, in
- which case it sets one. When an account already exists, the same field is
- how the person proves the account is theirs.
+ - Products
+ security:
+ - bearer_auth: []
+ description: Edits a product the acting seller owns.
parameters:
- - name: token
- in: query
+ - name: X-Spree-Seller-Id
+ in: header
required: true
- description: The token from the emailed link
schema:
type: string
responses:
'200':
- description: invitation accepted, session issued
- content:
- application/json:
- example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoyLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6IjRmYzVlNzBmLWU1ODAtNDExNi1hOWU5LTBjNDliMGExYjMxNCIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.H0mJ1zDqTi6mNs_BZBRTJ77OMsWAqeUXvQM09YPLefs
- user:
- id: adm_gbHJdmfrXB
- first_name: Robin
- last_name: Ellis
- full_name: Robin Ellis
- created_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- selected_locale:
- sellers:
- - id: sel_UkLWZg9DAJ
- name: Seller 44
- status: approved
- schema:
- "$ref": "#/components/schemas/AuthResponse"
- '404':
- description: wrong token, or an invitation that can no longer be accepted
+ description: product updated
content:
application/json:
example:
- error:
- code: record_not_found
- message: Invitation not found, expired, or already accepted.
+ id: prod_UkLWZg9DAJ
+ name: Hand-thrown mug, large
+ slug: product-2118212
+ meta_title:
+ meta_description:
+ meta_keywords:
+ variant_count: 1
+ available_on:
+ preorder_ships_at:
+ purchasable: true
+ preorder: false
+ in_stock: false
+ backorderable: true
+ available: true
+ description: Vel minima recusandae iure deserunt non. Corrupti soluta
+ pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto
+ animi. Eum facilis veniam a consequatur minus. Dolor iure facilis
+ repellendus tenetur. Nobis harum perferendis ab maiores labore eius
+ eum quo.
+ description_html: |-
+ Vel minima recusandae iure deserunt non. Corrupti soluta pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto animi.
+ Eum facilis veniam a consequatur minus. Dolor iure facilis repellendus tenetur. Nobis harum perferendis ab maiores labore eius eum quo.
+ default_variant_id: variant_UkLWZg9DAJ
+ buy_box_variant_id: variant_UkLWZg9DAJ
+ thumbnail_url:
+ tags: []
+ price:
+ id: price_UkLWZg9DAJ
+ amount: '19.99'
+ amount_in_cents: 1999
+ compare_at_amount:
+ compare_at_amount_in_cents:
+ currency: USD
+ display_amount: "$19.99"
+ display_compare_at_amount:
+ price_list_id:
+ original_price:
+ seller_id: sel_UkLWZg9DAJ
+ status: active
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ product_type_id:
+ delivery_profile_id: fp_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/Product"
requestBody:
content:
application/json:
schema:
type: object
properties:
- password:
+ name:
type: string
- example: password123
- password_confirmation:
+ example: Hand-thrown mug, large
+ description:
type: string
- example: password123
- first_name:
+ slug:
type: string
- example: Robin
- last_name:
+ status:
type: string
- example: Ellis
- "/api/v3/seller/invitations":
- get:
- summary: List pending invitations
+ example: active
+ tags:
+ type: array
+ items:
+ type: string
+ category_ids:
+ type: array
+ items:
+ type: string
+ metadata:
+ type: object
+ additionalProperties: true
+ delete:
+ summary: Delete a product
tags:
- - Team
+ - Products
security:
- bearer_auth: []
- description: |
- Offers nobody has accepted yet, newest first.
-
- Pending only — an accepted invitation is a team member, and shows up on
- `GET /api/v3/seller/team` instead.
-
- Sending an invitation lives on `team`, because that is hiring. Chasing or
- withdrawing one is bookkeeping on the offer itself, so it lives here.
+ description: Deletes a product the acting seller owns.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -13819,46 +14060,21 @@ paths:
schema:
type: string
responses:
- '200':
- description: invitations listed
- content:
- application/json:
- example:
- data:
- - id: inv_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- expires_at: '2026-01-29T12:00:00.000Z'
- accepted_at:
- status: pending
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=gybGAXxVP79yKWNTZLAC94ui"
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Invitation"
- required:
- - data
- "/api/v3/seller/invitations/{id}/resend":
- parameters:
- - name: id
- in: path
- description: Invitation ID
- required: true
- schema:
- type: string
- patch:
- summary: Resend an invitation
+ '204':
+ description: product deleted
+ "/api/v3/seller/profile":
+ get:
+ summary: Get profile
tags:
- - Team
+ - Profile
security:
- bearer_auth: []
description: |
- Sends the invitation email again, for a colleague who never got the first
- one. An invitation whose window has closed is refused rather than
- re-sent.
+ The seller's own record.
+
+ Singular by nature: the seller in play is always the one named by
+ `X-Spree-Seller-Id`, never an id in the path — so a seller cannot address
+ another seller here even by guessing one.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -13867,44 +14083,71 @@ paths:
type: string
responses:
'200':
- description: invitation resent
+ description: profile returned
content:
application/json:
example:
- id: inv_UkLWZg9DAJ
+ id: sel_UkLWZg9DAJ
+ name: Seller 101
+ slug: seller-101
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ preferred_timezone: UTC
+ status: approved
+ legal_name:
+ registration_number:
+ contact_email:
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ holiday_mode_until:
+ terms_accepted_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
- expires_at: '2026-01-29T12:00:00.000Z'
- accepted_at:
- status: pending
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3uJFfKUSiHtnc9TGAXMJUXsB"
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: true
+ default_currency: USD
+ supported_currencies:
+ - USD
+ - EUR
+ - GBP
+ products_count: 0
schema:
- "$ref": "#/components/schemas/Invitation"
- '404':
- description: another seller's invitation
+ "$ref": "#/components/schemas/Profile"
+ '403':
+ description: no seller named, or not a member of it
content:
application/json:
example:
error:
- code: record_not_found
- message: Invitation not found
+ code: access_denied
+ message: You do not have access to this seller.
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/invitations/{id}":
- parameters:
- - name: id
- in: path
- description: Invitation ID
- required: true
- schema:
- type: string
- delete:
- summary: Revoke an invitation
+ patch:
+ summary: Update profile
tags:
- - Team
+ - Profile
security:
- bearer_auth: []
- description: Withdraws an offer that has not been accepted.
+ description: |
+ Edits presentation, contact details and addresses.
+
+ Readable but **not** writable, by design: `status` — the lifecycle belongs
+ to the marketplace operator's workflows — the settlement terms, and
+ `slug`, since a seller renaming their own storefront address would break
+ every link pointing at it.
+
+ `accept_terms: true` stamps the moment the seller accepted the
+ marketplace's terms, which is what the matching onboarding requirement
+ reads. One-way — sending `false` does not unmake the stamp.
+
+ `custom_fields` is narrowed server-side to the definitions this
+ marketplace's onboarding actually asks this seller for; a field nothing
+ asked for is ignored rather than written.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -13912,387 +14155,461 @@ paths:
schema:
type: string
responses:
- '204':
- description: invitation revoked
- '404':
- description: another seller's invitation
+ '200':
+ description: profile updated
+ content:
+ application/json:
+ example:
+ id: sel_UkLWZg9DAJ
+ name: Acme Supplies
+ slug: seller-103
+ about: ''
+ about_html: ''
+ logo_url:
+ square_logo_url:
+ cover_photo_url:
+ preferred_timezone: UTC
+ status: approved
+ legal_name:
+ registration_number:
+ contact_email: [email protected]
+ billing_email:
+ tax_remittance: seller
+ payouts_schedule_interval:
+ holiday_mode_until:
+ terms_accepted_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ minimum_payout_amount:
+ on_holiday: false
+ sellable: true
+ default_currency: USD
+ supported_currencies:
+ - USD
+ - EUR
+ - GBP
+ products_count: 0
+ schema:
+ "$ref": "#/components/schemas/Profile"
+ '422':
+ description: validation failed
content:
application/json:
example:
error:
- code: record_not_found
- message: Invitation not found
+ code: validation_error
+ message: Name can't be blank
+ details:
+ name:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/me":
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Acme Supplies
+ contact_email:
+ type: string
+ format: email
+ nullable: true
+ billing_email:
+ type: string
+ format: email
+ nullable: true
+ about:
+ type: string
+ nullable: true
+ description: Sanitized HTML — the seller's public description
+ legal_name:
+ type: string
+ nullable: true
+ description: The business a commission invoice is made out to
+ registration_number:
+ type: string
+ nullable: true
+ logo:
+ type: string
+ nullable: true
+ description: ActiveStorage signed id; `null` removes the attachment
+ square_logo:
+ type: string
+ nullable: true
+ cover_photo:
+ type: string
+ nullable: true
+ accept_terms:
+ type: boolean
+ description: Stamps acceptance of the marketplace terms
+ billing_address:
+ type: object
+ additionalProperties: true
+ custom_fields:
+ type: array
+ items:
+ type: object
+ properties:
+ custom_field_definition_id:
+ type: string
+ example: cfd_abc123
+ value:
+ description: Any JSON value the definition accepts
+ "/api/v3/seller/stock_locations":
get:
- summary: Current user
+ summary: List stock locations
tags:
- - Account
+ - Stock Locations
security:
- bearer_auth: []
description: |
- The signed-in user, the sellers they may act for, and what they may do on
- the selected one.
+ Where this seller keeps stock, and so where their returns are sent.
- This is the one authenticated endpoint that answers without
- `X-Spree-Seller-Id` — it is what tells the panel which seller to name.
- Sending the header narrows `permission_keys` and `permissions` to that
- seller; without it both are empty, because capability is per seller and
- there is no answer spanning all of them.
+ Rooted in the acting seller, so the marketplace operator's own warehouses
+ never appear here.
parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: false
- description: The seller to report capability for. Omit to list sellers without
- narrowing permissions.
- schema:
- type: string
- responses:
- '200':
- description: current user returned
- content:
- application/json:
- example:
- user:
- id: adm_UkLWZg9DAJ
- first_name: Nadia
- last_name: Effertz
- full_name: Nadia Effertz
- created_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- selected_locale:
- sellers:
- - id: sel_UkLWZg9DAJ
- name: Seller 53
- slug: seller-53
- status: approved
- permissions:
- - allow: true
- actions:
- - read
- subjects:
- - Spree::Country
- has_conditions: false
- - allow: true
- actions:
- - read
- subjects:
- - Spree::State
- has_conditions: false
- - allow: true
- actions:
- - read
- subjects:
- - Spree::Store
- has_conditions: true
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::Product
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::Variant
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::OptionType
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::OptionValue
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::Price
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::PriceList
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::PriceRule
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::Catalog
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::CatalogProduct
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::CatalogAssignment
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::CustomField
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::DigitalAsset
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::Import
- has_conditions: false
- - allow: true
- actions:
- - read
- - admin
- subjects:
- - Spree::ImportRow
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::Product
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::Variant
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::OptionType
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::OptionValue
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::Price
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::PriceList
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::PriceRule
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::Catalog
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::CatalogProduct
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::CatalogAssignment
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::CustomField
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::DigitalAsset
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::Import
- has_conditions: false
- - allow: true
- actions:
- - manage
- subjects:
- - Spree::ImportRow
- has_conditions: false
- permission_keys:
- - read_products
- - write_products
- schema:
- "$ref": "#/components/schemas/SellerMeResponse"
- '401':
- description: missing or invalid token
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ 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 (max 100)
+ schema:
+ type: integer
+ - name: sort
+ in: query
+ required: false
+ description: Sort field; prefix with `-` for descending
+ schema:
+ type: string
+ responses:
+ '200':
+ description: stock locations listed
content:
application/json:
example:
- error:
- code: authentication_required
- message: Authentication required
+ data:
+ - id: sloc_UkLWZg9DAJ
+ name: Lesha Stroman
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ returns_enabled: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update your account
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/StockLocation"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ post:
+ summary: Create a stock location
tags:
- - Account
+ - Stock Locations
security:
- bearer_auth: []
description: |
- Edits the signed-in person's own account — the name and photo their team
- sees, and the language their panel displays.
-
- This is the person, not the business: the seller they act for is
- `PATCH /profile`. Like `GET /me` it answers without
- `X-Spree-Seller-Id`, because the account is the same whichever seller
- they are acting for.
+ Adds a place this seller ships from.
- `avatar` takes an ActiveStorage direct-upload signed id to set the
- photo, or `null` to remove it; omit it to leave the current one alone.
- `email` is identity-bound and cannot be changed here.
- parameters: []
+ The seller and the store come from the request context whatever the
+ payload says.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
responses:
- '200':
- description: account updated
+ '201':
+ description: stock location created
content:
application/json:
example:
- user:
- id: adm_UkLWZg9DAJ
- first_name: Ada
- last_name: Lovelace
- full_name: Ada Lovelace
- created_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- selected_locale:
- sellers:
- - id: sel_UkLWZg9DAJ
- name: Seller 55
- slug: seller-55
- status: approved
- permissions: []
- permission_keys: []
+ id: sloc_gbHJdmfrXB
+ name: Main warehouse
+ address1:
+ city: Portland
+ zipcode:
+ country_code: US
+ country_name: United States
+ state_code:
+ state_text:
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone:
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ returns_enabled: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
schema:
- "$ref": "#/components/schemas/SellerMeResponse"
+ "$ref": "#/components/schemas/StockLocation"
'422':
- description: the photo is not a web image
+ description: validation failed
content:
application/json:
example:
error:
code: validation_error
- message: Avatar has an invalid content type (authorized content
- types are PNG, JPG, GIF, WEBP)
+ message: Name can't be blank
details:
- avatar:
- - has an invalid content type (authorized content types are PNG,
- JPG, GIF, WEBP)
+ name:
+ - can't be blank
schema:
"$ref": "#/components/schemas/ErrorResponse"
- '401':
- description: missing or invalid token
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ example: Main warehouse
+ company:
+ type: string
+ nullable: true
+ address1:
+ type: string
+ nullable: true
+ example: 1 Kiln Lane
+ address2:
+ type: string
+ nullable: true
+ city:
+ type: string
+ nullable: true
+ example: Portland
+ zipcode:
+ type: string
+ nullable: true
+ example: '97205'
+ country_code:
+ type: string
+ nullable: true
+ example: US
+ state_code:
+ type: string
+ nullable: true
+ example: OR
+ state_name:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ active:
+ type: boolean
+ description: Set `false` to retire a location — there is no delete
+ default:
+ type: boolean
+ kind:
+ type: string
+ example: warehouse
+ required:
+ - name
+ "/api/v3/seller/stock_locations/{id}":
+ parameters:
+ - name: id
+ in: path
+ description: Stock location ID
+ required: true
+ schema:
+ type: string
+ get:
+ summary: Get a stock location
+ tags:
+ - Stock Locations
+ security:
+ - bearer_auth: []
+ description: |
+ A stock location the acting seller owns. An id belonging to another
+ seller — or to the marketplace operator — answers `404`.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: stock location returned
+ content:
+ application/json:
+ example:
+ id: sloc_UkLWZg9DAJ
+ name: Marsha Turner
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ returns_enabled: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
+ '404':
+ description: another seller's stock location
content:
application/json:
example:
error:
- code: authentication_required
- message: Authentication required
+ code: record_not_found
+ message: Stock location not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
+ patch:
+ summary: Update a stock location
+ tags:
+ - Stock Locations
+ security:
+ - bearer_auth: []
+ description: |
+ Edits a stock location the acting seller owns.
+
+ There is no delete: a location holds stock levels and is named on
+ historical fulfillments, so a seller retires one by setting `active` to
+ `false`.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: stock location updated
+ content:
+ application/json:
+ example:
+ id: sloc_UkLWZg9DAJ
+ name: Kiln Lane warehouse
+ address1: 1600 Pennsylvania Ave NW
+ city: Washington
+ zipcode: '20500'
+ country_code: US
+ country_name: United States
+ state_code: AL
+ state_text: AL
+ pickup_ready_in_minutes:
+ pickup_instructions:
+ address2:
+ state_name:
+ phone: "(202) 456-1111"
+ company:
+ active: true
+ default: false
+ kind: warehouse
+ returns_enabled: true
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ schema:
+ "$ref": "#/components/schemas/StockLocation"
requestBody:
content:
application/json:
schema:
type: object
properties:
- first_name:
+ name:
type: string
- example: Ada
- last_name:
+ example: Main warehouse
+ address1:
type: string
- example: Lovelace
- selected_locale:
+ nullable: true
+ city:
type: string
- example: de
- description: Panel display language, as a code the panel ships.
- avatar:
+ nullable: true
+ zipcode:
type: string
nullable: true
- description: Direct-upload signed id, or `null` to remove the photo.
- "/api/v3/seller/onboarding":
+ country_code:
+ type: string
+ nullable: true
+ state_code:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ active:
+ type: boolean
+ default:
+ type: boolean
+ "/api/v3/seller/invitations":
get:
- summary: Get onboarding checklist
+ summary: List pending invitations
tags:
- - Onboarding
+ - Team
security:
- bearer_auth: []
description: |
- What this marketplace asks of the seller before it will admit them.
-
- Singular: the checklist is always the acting seller's. Every answer is
- computed server-side by the same evaluator the operator's own view uses,
- so the panel and the operator can never show different progress.
+ Offers nobody has accepted yet, newest first.
- `progress` counts optional requirements too — it is how far along the
- checklist is, not how close to approval. Read `blocking` on each
- requirement for that.
+ Pending only — an accepted invitation is a team member, and shows up on
+ `GET /api/v3/seller/team` instead.
- Each requirement's `id` is what a submission is posted against. A
- marketplace that asks for nothing returns an empty list, which is a
- complete answer rather than a missing one.
+ Sending an invitation lives on `team`, because that is hiring. Chasing or
+ withdrawing one is bookkeeping on the offer itself, so it lives here.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -14301,42 +14618,78 @@ paths:
type: string
responses:
'200':
- description: checklist returned
+ description: invitations listed
content:
application/json:
example:
- status: approved
- progress:
- done: 0
- total: 0
- requirements: []
+ data:
+ - id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
schema:
- "$ref": "#/components/schemas/SellerOnboardingResponse"
- '403':
- description: no seller named, or not a member of it
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Invitation"
+ required:
+ - data
+ "/api/v3/seller/invitations/{invitation_id}/acceptance_link":
+ parameters:
+ - name: invitation_id
+ in: path
+ description: Invitation ID
+ required: true
+ schema:
+ type: string
+ get:
+ summary: Get an invitation acceptance link
+ tags:
+ - Team
+ security:
+ - bearer_auth: []
+ description: |
+ The link a colleague opens to join the team. It carries the invitation's
+ token, so the listing never includes it; fetch it when someone asks to
+ copy the link.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: acceptance link found
content:
application/json:
example:
- error:
- code: access_denied
- message: You do not have access to this seller.
+ id: inv_UkLWZg9DAJ
+ acceptance_url: http://www.example.com:3000/accept-invitation/inv_UkLWZg9DAJ?token=7La4K2PLxW8oLoXjmz46QYEJ
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/onboarding/submit_for_review":
- post:
- summary: Submit for review
+ "$ref": "#/components/schemas/InvitationAcceptanceLink"
+ "/api/v3/seller/invitations/{id}/resend":
+ parameters:
+ - name: id
+ in: path
+ description: Invitation ID
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Resend an invitation
tags:
- - Onboarding
+ - Team
security:
- bearer_auth: []
description: |
- Says the seller is ready, moving them from `onboarding` to
- `ready_for_review`.
-
- Refused with `422` when something required is still outstanding — the
- message names the blocking requirements, and the seller's status is
- unchanged. Returns the same payload as the checklist so the panel can
- re-render from one response.
+ Sends the invitation email again, for a colleague who never got the first
+ one. An invitation whose window has closed is refused rather than
+ re-sent.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -14345,264 +14698,185 @@ paths:
type: string
responses:
'200':
- description: submitted for review
+ description: invitation resent
content:
application/json:
example:
- status: ready_for_review
- progress:
- done: 0
- total: 0
- requirements: []
+ id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
schema:
- "$ref": "#/components/schemas/SellerOnboardingResponse"
- '422':
- description: something required is still outstanding
+ "$ref": "#/components/schemas/Invitation"
+ '404':
+ description: another seller's invitation
content:
application/json:
example:
error:
- code: processing_error
- message: Requirements Accept terms is not complete
+ code: record_not_found
+ message: Invitation not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/orders":
- get:
- summary: List orders
+ "/api/v3/seller/invitations/{id}":
+ parameters:
+ - name: id
+ in: path
+ description: Invitation ID
+ required: true
+ schema:
+ type: string
+ delete:
+ summary: Revoke an invitation
tags:
- - Orders
+ - Team
security:
- bearer_auth: []
- description: |
- What this seller has sold.
-
- On a marketplace a basket spanning several sellers is split into one
- order each, so these are the seller's own orders rather than a filtered
- view of somebody else's — another seller's order is never reachable,
- whatever id is sent.
-
- Checkouts still in flight are left out: until one completes it is
- nobody's order.
+ description: Withdraws an offer that has not been accepted.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
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 (max 100)
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: Sort field; prefix with `-` for descending
+ responses:
+ '204':
+ description: invitation revoked
+ '404':
+ description: another seller's invitation
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Invitation not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/team":
+ get:
+ summary: List team members
+ tags:
+ - Team
+ security:
+ - bearer_auth: []
+ description: |
+ The people who run this seller.
+
+ Rooted at the acting seller throughout, so a seller only ever sees their
+ own team. Unpaginated — a seller's team is small by nature.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: orders listed
+ description: team members listed
content:
application/json:
example:
data:
- - id: or_UkLWZg9DAJ
- number: R1001
- customer_note:
- currency: USD
- total_quantity: 1
- status: placed
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
+ - id: adm_UkLWZg9DAJ
+ first_name: Bill
+ last_name: Towne
+ full_name: Bill Towne
created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- internal_note:
- internal_note_html:
- item_total: '10.0'
- display_item_total: "$10.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- payment_total: '0.0'
- display_payment_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
- canceled_at:
- cancel_reason_name:
- cancel_note:
- items:
- - id: li_UkLWZg9DAJ
- name: Product 19195
- options_text: ''
- quantity: 1
- currency: USD
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- variant_id: variant_UkLWZg9DAJ
- sku: SKU-257
- thumbnail_url:
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: unfulfilled
- tracking: U10000
- tracking_url:
- fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 86
- stock_location_name: Roseline Roberts
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 19195
- sku: SKU-257
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 86
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
- shipping_address:
- id: addr_gbHJdmfrXB
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 167 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
- billing_address:
- id: addr_UkLWZg9DAJ
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 166 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ avatar_url:
schema:
type: object
properties:
data:
type: array
items:
- "$ref": "#/components/schemas/Order"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
+ "$ref": "#/components/schemas/TeamMember"
required:
- data
- - meta
- "/api/v3/seller/orders/{id}":
+ post:
+ summary: Invite a team member
+ tags:
+ - Team
+ security:
+ - bearer_auth: []
+ description: |
+ Invites a colleague onto this seller's team. They join when they accept,
+ on the same invitation rail — and the same email — the marketplace
+ operator's own invitations use.
+
+ Hiring is not a lifecycle transition: a trading seller's status is
+ untouched by taking someone on.
+
+ The role is not a parameter. Every member holds the seller's own seeded
+ role, which already carries the whole seller vocabulary.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: invitation sent
+ content:
+ application/json:
+ example:
+ id: inv_UkLWZg9DAJ
+ created_at: '2026-01-15T12:00:00.000Z'
+ expires_at: '2026-01-29T12:00:00.000Z'
+ accepted_at:
+ status: pending
+ schema:
+ "$ref": "#/components/schemas/Invitation"
+ '422':
+ description: validation failed
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Email is invalid and Email can't be blank
+ details:
+ email:
+ - is invalid
+ - can't be blank
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ email:
+ type: string
+ format: email
+ required:
+ - email
+ "/api/v3/seller/team/{id}":
parameters:
- name: id
in: path
- description: Prefixed order ID
+ description: Team member (user) ID
required: true
schema:
type: string
- get:
- summary: Get an order
+ delete:
+ summary: Remove a team member
tags:
- - Orders
+ - Team
security:
- bearer_auth: []
description: |
- One order, as the seller needs it to pack and post the parcel: the
- lines with their SKUs, where it ships to, and a fulfillment per parcel.
+ Revokes a member's access, removing every role they hold on this seller.
- How the customer paid the marketplace is deliberately absent — that is
- between the buyer and the operator.
+ The team can never reach zero: emptying it would leave a seller nobody
+ can sign in to, and only the marketplace operator could put someone back.
+ The last remaining member is refused with `422`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -14610,196 +14884,114 @@ paths:
schema:
type: string
responses:
- '200':
- description: order found
+ '204':
+ description: member removed
+ '422':
+ description: cannot remove the last remaining member
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R1001
- customer_note:
- currency: USD
- total_quantity: 1
- status: placed
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- internal_note:
- internal_note_html:
- item_total: '10.0'
- display_item_total: "$10.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- payment_total: '0.0'
- display_payment_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
- canceled_at:
- cancel_reason_name:
- cancel_note:
- items:
- - id: li_UkLWZg9DAJ
- name: Product 1929755
- options_text: ''
- quantity: 1
- currency: USD
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- variant_id: variant_UkLWZg9DAJ
- sku: SKU-258
- thumbnail_url:
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: unfulfilled
- tracking: U10000
- tracking_url:
- fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 87
- stock_location_name: Woodrow Hand
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 1929755
- sku: SKU-258
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 87
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
- shipping_address:
- id: addr_gbHJdmfrXB
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 169 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
- billing_address:
- id: addr_UkLWZg9DAJ
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 168 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
+ error:
+ code: processing_error
+ message: A seller needs at least one team member. Invite someone
+ else before removing this one.
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/ErrorResponse"
'404':
- description: another seller's order
+ description: not a member of this seller
content:
application/json:
example:
error:
- code: order_not_found
- message: Order not found
+ code: record_not_found
+ message: Admin user not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/orders/{id}/cancel":
- parameters:
- - name: id
- in: path
- description: Prefixed order ID
- required: true
- schema:
- type: string
- patch:
- summary: Cancel an order
+ "/api/v3/seller/direct_uploads":
+ post:
+ summary: Create a direct upload
tags:
- - Orders
+ - Uploads
+ security:
+ - bearer_auth: []
+ description: |
+ Presigns an upload target for a file the seller is about to send.
+
+ Three steps: post the file's metadata here, `PUT` the bytes to the
+ returned `direct_upload.url` with the headers it names, then send the
+ returned `signed_id` wherever the file belongs — as a requirement
+ submission's `file`, or as `logo`, `square_logo` or `cover_photo` on the
+ profile.
+
+ The blob is attached to nothing at this point. The endpoint that consumes
+ the `signed_id` is the one that checks ownership.
+
+ `checksum` is the file's MD5 digest, base64-encoded — the storage service
+ verifies the upload against it.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: upload target created
+ content:
+ application/json:
+ example:
+ direct_upload:
+ url: http://www.example.com/rails/active_storage/disk/eyJfcmFpbHMiOnsiZGF0YSI6eyJrZXkiOiJuem5oOGdra3VxendvbDc1ODBxNHNwZmpmMjVxIiwiY29udGVudF90eXBlIjoiYXBwbGljYXRpb24vcGRmIiwiY29udGVudF9sZW5ndGgiOjUxMjM0LCJjaGVja3N1bSI6IlZqaHowNGxRdUVHdXY0bkR2aHNhTlE9PSIsInNlcnZpY2VfbmFtZSI6InRlc3QifSwiZXhwIjoiMjAyNi0wMS0xNVQxMjowNTowMC4wMDBaIiwicHVyIjoiYmxvYl90b2tlbiJ9fQ==--484d46dd60be3523918976c0cc622ec8eb33a9be
+ headers:
+ Content-Type: application/pdf
+ signed_id: eyJfcmFpbHMiOnsiZGF0YSI6MSwicHVyIjoiYmxvYl9pZCJ9fQ==--118079e2383257795a7c941f07809ce1d921cedc
+ schema:
+ "$ref": "#/components/schemas/DirectUploadResponse"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ blob:
+ type: object
+ properties:
+ filename:
+ type: string
+ example: registration.pdf
+ byte_size:
+ type: integer
+ example: 51234
+ checksum:
+ type: string
+ description: Base64-encoded MD5 digest of the file
+ example: rL0Y20zC+Fzt72VPzMSk2A==
+ content_type:
+ type: string
+ example: application/pdf
+ required:
+ - filename
+ - byte_size
+ - checksum
+ - content_type
+ required:
+ - blob
+ "/api/v3/seller/balances":
+ get:
+ summary: List balances
+ tags:
+ - Earnings
security:
- bearer_auth: []
description: |
- Withdraws from an order this seller cannot fulfil, naming a reason from
- the marketplace's own list.
-
- The goods go back on the shelf and the payment authorization is
- released either way. `refund_payments` also hands back what the buyer
- paid for these goods — a seller is merchant of record for their own
- child order, and on a split checkout only that order's share of the
- group's payment is settled.
+ Where this seller stands with the marketplace, one row per currency
+ they have earned or been paid in: what they have earned (settled
+ transfers, refund reversals included), what has reached them, what the
+ marketplace still owes, and earnings the payout provider has not yet
+ confirmed.
- There is no `refund_amount`: withdrawing from the whole order returns
- what that order was paid, and a partial figure is a return.
+ Computed from the ledger rather than stored, so the rows carry no id
+ and there is nothing to page.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -14808,54 +15000,48 @@ paths:
type: string
responses:
'200':
- description: order canceled
+ description: balances listed
content:
application/json:
+ example:
+ data:
+ - currency: USD
+ settlement_currency: USD
+ converted: false
+ earned: '40.0'
+ display_earned: "$40.00"
+ payable: '40.0'
+ display_payable: "$40.00"
+ paid: '15.0'
+ display_paid: "$15.00"
+ balance: '25.0'
+ display_balance: "$25.00"
+ pending: '0.0'
+ display_pending: "$0.00"
schema:
- "$ref": "#/components/schemas/Order"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- cancel_reason_id:
- type: string
- nullable: true
- description: A reason from GET /order_cancellation_reasons
- cancel_note:
- type: string
- nullable: true
- description: Free text beside the reason
- refund_payments:
- type: boolean
- description: Hand back what the buyer paid for this order's goods
- notify_customer:
- type: boolean
- description: Email the customer about the cancellation
- "/api/v3/seller/orders/{id}/address":
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Balance"
+ required:
+ - data
+ "/api/v3/seller/orders/{order_id}/claims":
parameters:
- - name: id
+ - name: order_id
in: path
description: Prefixed order ID
required: true
schema:
type: string
- patch:
- summary: Correct an order address
+ get:
+ summary: List claims
tags:
- - Orders
+ - Claims
security:
- bearer_auth: []
- description: |
- Corrects where the goods go or who the invoice names.
-
- The seller is merchant of record for their own child order, so a
- delivery address the buyer got wrong is theirs to fix. Send only the
- lines that change — the rest of the address is carried over.
-
- This is the only write against the order itself besides cancelling:
- nothing else about it, its totals included, is the seller's to change.
+ description: Problems reported on one of this seller's orders.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -14864,246 +15050,334 @@ paths:
type: string
responses:
'200':
- description: address corrected
+ description: claims listed
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R1001
- customer_note:
- currency: USD
- total_quantity: 1
- status: placed
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- internal_note:
- internal_note_html:
- item_total: '10.0'
- display_item_total: "$10.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- payment_total: '0.0'
- display_payment_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
- canceled_at:
- cancel_reason_name:
- cancel_note:
- items:
- - id: li_UkLWZg9DAJ
- name: Product 1965038
- options_text: ''
- quantity: 1
- currency: USD
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- variant_id: variant_UkLWZg9DAJ
- sku: SKU-262
- thumbnail_url:
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: unfulfilled
- tracking: U10000
- tracking_url:
- fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 91
- stock_location_name: Rudy Mosciski
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 1965038
- sku: SKU-262
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 91
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
- shipping_address:
- id: addr_EfhxLZ9ck8
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 9 Corrected Way
- address2: Northwest
- postal_code: '10118'
- city: Fixedton
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: true
- state_abbr: NY
- country_iso: US
- state_name: New York
- billing_address:
- id: addr_UkLWZg9DAJ
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 176 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
+ data:
+ - id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: open
+ resolution:
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '0.0'
+ display_refund_total: "$0.00"
+ approved_at:
+ resolved_at:
+ denied_at:
+ canceled_at:
+ memo:
+ 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/Claim"
+ required:
+ - data
+ post:
+ summary: Open a claim
+ tags:
+ - Claims
+ security:
+ - bearer_auth: []
+ description: |
+ Reports that something went wrong with a delivery, to be put right
+ without necessarily asking for the goods back.
+
+ A replacement variant, if one is offered, comes from this seller's own
+ catalogue — a rival's is not theirs to promise.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: claim opened
+ content:
+ application/json:
+ example:
+ id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: open
+ resolution:
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '0.0'
+ display_refund_total: "$0.00"
+ approved_at:
+ resolved_at:
+ denied_at:
+ canceled_at:
+ memo:
schema:
- "$ref": "#/components/schemas/Order"
- '422':
- description: neither address named
+ "$ref": "#/components/schemas/Claim"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ items:
+ type: array
+ items:
+ type: object
+ properties:
+ line_item_id:
+ type: string
+ quantity:
+ type: integer
+ description:
+ type: string
+ nullable: true
+ send_replacement:
+ type: boolean
+ replacement_variant_id:
+ type: string
+ nullable: true
+ refund_amount:
+ type: string
+ nullable: true
+ required:
+ - line_item_id
+ - quantity
+ reason_id:
+ type: string
+ nullable: true
+ memo:
+ type: string
+ nullable: true
+ required:
+ - items
+ "/api/v3/seller/orders/{order_id}/claims/{id}/approve":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Approve a claim
+ tags:
+ - Claims
+ security:
+ - bearer_auth: []
+ description: Accepts that the claim is good.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: claim approved
content:
application/json:
example:
- error:
- code: validation_error
- message: shipping_address or billing_address is required
- details:
- base:
- - shipping_address or billing_address is required
+ id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: approved
+ resolution:
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '0.0'
+ display_refund_total: "$0.00"
+ approved_at: '2026-01-15T12:00:00Z'
+ resolved_at:
+ denied_at:
+ canceled_at:
+ memo:
+ schema:
+ "$ref": "#/components/schemas/Claim"
+ "/api/v3/seller/orders/{order_id}/claims/{id}/resolve":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Resolve a claim
+ tags:
+ - Claims
+ security:
+ - bearer_auth: []
+ description: |
+ Puts the claim right: money back, a replacement shipment, or both.
+
+ A refund is bounded by this order's share of the payment, so one
+ seller can never settle out of a sibling's money.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: claim resolved
+ content:
+ application/json:
+ example:
+ id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: resolved
+ resolution: refund
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '0.0'
+ display_refund_total: "$0.00"
+ approved_at: '2026-01-15T12:00:00Z'
+ resolved_at: '2026-01-15T12:00:00Z'
+ denied_at:
+ canceled_at:
+ memo:
+ schema:
+ "$ref": "#/components/schemas/Claim"
requestBody:
content:
application/json:
schema:
type: object
properties:
- shipping_address:
- type: object
- description: Only the lines that change; the rest is carried over
- properties:
- first_name:
- type: string
- last_name:
- type: string
- company:
- type: string
- nullable: true
- address1:
- type: string
- address2:
- type: string
- nullable: true
- city:
- type: string
- postal_code:
- type: string
- country_code:
- type: string
- state_code:
- type: string
- nullable: true
- state_name:
- type: string
- nullable: true
- phone:
- type: string
- nullable: true
- label:
- type: string
- nullable: true
- billing_address:
- type: object
- description: Only the lines that change; the rest is carried over
- properties:
- first_name:
- type: string
- last_name:
- type: string
- company:
- type: string
- nullable: true
- address1:
- type: string
- address2:
- type: string
- nullable: true
- city:
- type: string
- postal_code:
- type: string
- country_code:
- type: string
- state_code:
- type: string
- nullable: true
- state_name:
- type: string
- nullable: true
- phone:
- type: string
- nullable: true
- label:
- type: string
- nullable: true
+ resolution:
+ type: string
+ enum:
+ - refund
+ - replacement
+ - refund_and_replacement
+ refund_method:
+ type: string
+ enum:
+ - original_payment
+ - store_credit
+ amount:
+ type: string
+ nullable: true
+ replacement_line_item_ids:
+ type: array
+ items:
+ type: string
+ required:
+ - resolution
+ "/api/v3/seller/orders/{order_id}/claims/{id}/deny":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Deny a claim
+ tags:
+ - Claims
+ security:
+ - bearer_auth: []
+ description: Turns the claim down.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
required: true
- "/api/v3/seller/orders/{order_id}/notes":
+ schema:
+ type: string
+ responses:
+ '200':
+ description: claim denied
+ content:
+ application/json:
+ example:
+ id: claim_UkLWZg9DAJ
+ number: CLM1001
+ status: denied
+ resolution:
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '0.0'
+ display_refund_total: "$0.00"
+ approved_at:
+ resolved_at:
+ denied_at: '2026-01-15T12:00:00Z'
+ canceled_at:
+ memo:
+ schema:
+ "$ref": "#/components/schemas/Claim"
+ "/api/v3/seller/claim_reasons":
+ get:
+ summary: List claim reasons
+ tags:
+ - Claims
+ security:
+ - bearer_auth: []
+ description: |
+ What can go wrong with a delivery, as the marketplace defines it.
+
+ Read-only: a seller picks from the operator's vocabulary.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: reasons listed
+ content:
+ application/json:
+ example:
+ data:
+ - id: clr_UkLWZg9DAJ
+ name: Arrived damaged
+ active: true
+ 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/Reason"
+ required:
+ - data
+ "/api/v3/seller/orders/{order_id}/exchanges":
parameters:
- name: order_id
in: path
@@ -15112,17 +15386,12 @@ paths:
schema:
type: string
get:
- summary: Get order notes
+ summary: List exchanges
tags:
- - Orders
+ - Exchanges
security:
- bearer_auth: []
- description: |
- The instructions the buyer left, and the seller's own working note.
-
- A marketplace basket splits into one order per seller, so the internal
- note here is this seller's alone rather than the operator's note about
- the whole sale.
+ description: Goods swapped for different ones on one of this seller's orders.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -15131,171 +15400,135 @@ paths:
type: string
responses:
'200':
- description: notes
+ description: exchanges listed
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R1001
- customer_note:
- currency: USD
- total_quantity: 1
- status: placed
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- internal_note:
- internal_note_html:
- item_total: '10.0'
- display_item_total: "$10.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- payment_total: '0.0'
- display_payment_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
- canceled_at:
- cancel_reason_name:
- cancel_note:
- items:
- - id: li_UkLWZg9DAJ
- name: Product 1983962
- options_text: ''
- quantity: 1
- currency: USD
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- variant_id: variant_UkLWZg9DAJ
- sku: SKU-264
- thumbnail_url:
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: unfulfilled
- tracking: U10000
- tracking_url:
+ data:
+ - id: exch_UkLWZg9DAJ
+ number: EX1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ price_difference: '9.99'
+ display_price_difference: "$9.99"
+ approved_at:
+ received_at:
fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 93
- stock_location_name: Kecia Pollich
+ canceled_at:
+ memo:
stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 1983962
- sku: SKU-264
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 93
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
- shipping_address:
- id: addr_gbHJdmfrXB
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 181 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
- billing_address:
- id: addr_UkLWZg9DAJ
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 180 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
+ 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/Exchange"
+ required:
+ - data
+ post:
+ summary: Open an exchange
+ tags:
+ - Exchanges
+ security:
+ - bearer_auth: []
+ description: |
+ Swaps goods for different ones.
+
+ The replacement comes from this seller's own catalogue: it is stock
+ they will send, so a variant belonging to another seller is not theirs
+ to promise and reads as missing.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: exchange opened
+ content:
+ application/json:
+ example:
+ id: exch_UkLWZg9DAJ
+ number: EX1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ price_difference: '9.99'
+ display_price_difference: "$9.99"
+ approved_at:
+ received_at:
+ fulfilled_at:
+ canceled_at:
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Exchange"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ items:
+ type: array
+ items:
+ type: object
+ properties:
+ fulfillment_item_id:
+ type: string
+ new_variant_id:
+ type: string
+ quantity:
+ type: integer
+ required:
+ - fulfillment_item_id
+ - new_variant_id
+ - quantity
+ reason_id:
+ type: string
+ nullable: true
+ stock_location_id:
+ type: string
+ nullable: true
+ memo:
+ type: string
+ nullable: true
+ required:
+ - items
+ "/api/v3/seller/orders/{order_id}/exchanges/{id}/fulfill":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
patch:
- summary: Update order notes
+ summary: Send the replacement
tags:
- - Orders
+ - Exchanges
security:
- bearer_auth: []
description: |
- Send only the note that changes: an absent key leaves the other alone,
- while an empty string clears it.
-
- `internal_note` accepts HTML and is sanitized on save;
- `internal_note_html` reads it back.
+ Sends the replacement goods, settling any price difference at the same
+ time — which is why it takes a refund method.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -15304,197 +15537,135 @@ paths:
type: string
responses:
'200':
- description: notes updated
+ description: replacement sent
content:
application/json:
example:
- id: or_UkLWZg9DAJ
- number: R1001
- customer_note:
- currency: USD
- total_quantity: 1
- status: placed
- fulfillment_status:
- payment_status:
- completed_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- internal_note: Packed with the fragile insert.
- internal_note_html: "<p>Packed with the fragile insert.</p>"
- item_total: '10.0'
- display_item_total: "$10.00"
- delivery_total: '100.0'
- display_delivery_total: "$100.00"
- discount_total: '0.0'
- display_discount_total: "$0.00"
- adjustment_total: '0.0'
- display_adjustment_total: "$0.00"
- included_tax_total: '0.0'
- display_included_tax_total: "$0.00"
- additional_tax_total: '0.0'
- display_additional_tax_total: "$0.00"
- tax_total: '0.0'
- display_tax_total: "$0.00"
- total: '110.0'
- display_total: "$110.00"
- payment_total: '0.0'
- display_payment_total: "$0.00"
- amount_due: '110.0'
- display_amount_due: "$110.00"
- commission_amount_total: '0.0'
- display_commission_amount_total: "$0.00"
- commission_tax_total: '0.0'
- display_commission_tax_total: "$0.00"
- commission_total: '0.0'
- display_commission_total: "$0.00"
+ id: exch_UkLWZg9DAJ
+ number: EX1001
+ status: fulfilled
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ price_difference: '9.99'
+ display_price_difference: "$9.99"
+ approved_at: '2026-01-15T12:00:00Z'
+ received_at: '2026-01-15T12:00:00Z'
+ fulfilled_at: '2026-01-15T12:00:00Z'
canceled_at:
- cancel_reason_name:
- cancel_note:
- items:
- - id: li_UkLWZg9DAJ
- name: Product 1995749
- options_text: ''
- quantity: 1
- currency: USD
- price: '10.0'
- display_price: "$10.00"
- total: '10.0'
- display_total: "$10.00"
- variant_id: variant_UkLWZg9DAJ
- sku: SKU-265
- thumbnail_url:
- fulfillments:
- - id: ful_UkLWZg9DAJ
- number: R1001-F1
- status: unfulfilled
- tracking: U10000
- tracking_url:
- fulfilled_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- fulfillment_type: shipping
- delivery_method_name: UPS Ground 94
- stock_location_name: Ophelia Hartmann
- stock_location_id: sloc_UkLWZg9DAJ
- fulfillment_items:
- - id: fi_UkLWZg9DAJ
- quantity: 1
- line_item_id: li_UkLWZg9DAJ
- variant_id: variant_UkLWZg9DAJ
- name: Product 1995749
- sku: SKU-265
- options_text: ''
- selected_delivery_rate_id: dr_gbHJdmfrXB
- delivery_rates:
- - id: dr_gbHJdmfrXB
- name: UPS Ground 94
- selected: true
- cost: '10.0'
- total: '10.0'
- carrier:
- service_level:
- estimated_delivery_date:
- display_cost: "$10.00"
- display_total: "$10.00"
- deliveries:
- - id: dlv_UkLWZg9DAJ
- tracking_number: U10000
- carrier:
- carrier_name:
- service:
- status: pending
- tracking_url:
- estimated_delivery_at:
- delivered_at:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- shipping_label_id:
- labels: []
- shipping_address:
- id: addr_gbHJdmfrXB
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 183 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
- billing_address:
- id: addr_UkLWZg9DAJ
- label:
- first_name: John
- last_name: Doe
- full_name: John Doe
- address1: 182 Lovely Street
- address2: Northwest
- postal_code: '10118'
- city: New York
- phone: 555-555-0199
- company: Company
- country_name: United States
- country_code: US
- state_text: NY
- state_code: NY
- quick_checkout: false
- is_default_billing: false
- is_default_shipping: false
- state_abbr: NY
- country_iso: US
- state_name: New York
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
+ schema:
+ "$ref": "#/components/schemas/Exchange"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ refund_method:
+ type: string
+ enum:
+ - original_payment
+ - store_credit
+ "/api/v3/seller/exports":
+ post:
+ summary: Create an export
+ tags:
+ - Exports
+ security:
+ - bearer_auth: []
+ description: |
+ Queues a CSV of this seller's own records.
+
+ Only datasets that can be narrowed to a single seller are offered, so
+ an export can never contain another seller's rows however it is
+ filtered. The seller and the store come from the request context
+ whatever the payload says.
+
+ Generation runs in the background: poll `GET /api/v3/seller/exports/{id}`
+ until `done` is true, then fetch `download_url`.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: export queued
+ content:
+ application/json:
+ example:
+ id: exp_UkLWZg9DAJ
+ number: EF1001
+ format: csv
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: orders
+ user_id: adm_UkLWZg9DAJ
+ done: false
+ filename:
+ byte_size:
+ download_url:
schema:
- "$ref": "#/components/schemas/Order"
+ "$ref": "#/components/schemas/Export"
'422':
- description: neither note named
+ description: type cannot be scoped to one seller
content:
application/json:
example:
error:
code: validation_error
- message: customer_note or internal_note is required
- details:
- base:
- - customer_note or internal_note is required
+ message: 'Unsupported export type. Supported types: orders, products'
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
schema:
type: object
properties:
- customer_note:
+ type:
type: string
- nullable: true
- description: What the buyer asked for
- internal_note:
+ enum:
+ - orders
+ - products
+ description: Which dataset to export.
+ record_selection:
type: string
- nullable: true
- description: The seller's own working note, as HTML
- required: true
- "/api/v3/seller/order_cancellation_reasons":
+ enum:
+ - filtered
+ - all
+ description: "`filtered` (default) honours `search_params`; `all`
+ exports everything this seller owns."
+ search_params:
+ type: object
+ description: Ransack predicates, the same shape the list endpoints
+ take. Ignored when `record_selection` is `all`.
+ additionalProperties: true
+ results_url:
+ type: string
+ description: Panel URL the export-done email links back to. Honoured
+ only when it matches one of the store's allowed origins.
+ required:
+ - type
+ "/api/v3/seller/exports/{id}":
+ parameters:
+ - name: id
+ in: path
+ description: Export ID
+ required: true
+ schema:
+ type: string
get:
- summary: List order cancellation reasons
+ summary: Get an export
tags:
- - Orders
+ - Exports
security:
- bearer_auth: []
description: |
- Why an order was called off, as the marketplace defines it.
-
- Read-only: a seller picks one when cancelling, and the operator decides
- what the list holds. Retired reasons are left out.
+ Reads one of this seller's exports. Poll this until `done` is true,
+ then fetch `download_url`.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -15503,126 +15674,169 @@ paths:
type: string
responses:
'200':
- description: reasons listed
+ description: export found
content:
application/json:
example:
- data:
- - id: ocr_UkLWZg9DAJ
- name: Out of stock
- active: true
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ id: exp_UkLWZg9DAJ
+ number: EF1001
+ format: csv
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ type: orders
+ user_id: adm_UkLWZg9DAJ
+ done: false
+ filename:
+ byte_size:
+ download_url:
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Reason"
- required:
- - data
- "/api/v3/seller/package_types":
+ "$ref": "#/components/schemas/Export"
+ '404':
+ description: another seller's export
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Export not found
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/exports/{id}/download":
+ parameters:
+ - name: id
+ in: path
+ description: Export ID
+ required: true
+ schema:
+ type: string
get:
- summary: List package types
+ summary: Download an export
tags:
- - Package Types
+ - Exports
security:
- bearer_auth: []
description: |
- What this seller packs their goods into: the boxes their parcels ship
- in, the cartons their products are packed into, the pallets a
- wholesale order leaves on.
-
- The list carries the marketplace's own packaging alongside the
- seller's, so a seller can pack into the operator's standard cartons
- rather than measuring them again. Those rows report `editable: false`
- and are refused by every write.
+ Streams the finished CSV.
- The row marked `default` is the box this seller's parcels are quoted
- with — its size and weight are added to every rate.
+ The bytes are served by this endpoint rather than through a redirect,
+ so the seller's own session authorizes every download.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
schema:
type: string
- - name: owner
- in: query
- required: false
+ responses:
+ '422':
+ description: export is still being written
+ content:
+ application/json:
+ example:
+ error:
+ code: export_not_ready
+ message: Export is not ready yet
+ text/csv:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ '404':
+ description: another seller's export
+ content:
+ application/json:
+ example:
+ error:
+ code: record_not_found
+ message: Export not found
+ text/csv:
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/orders/{order_id}/fulfillments":
+ parameters:
+ - name: order_id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
+ get:
+ summary: List fulfillments
+ tags:
+ - Fulfillments
+ security:
+ - bearer_auth: []
+ description: |
+ The parcels this seller owes on one order.
+
+ Reached through the order, which is itself fetched through the acting
+ seller — so a fulfillment on somebody else's order is unreachable
+ whatever ids are sent.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
schema:
type: string
- enum:
- - mine
- description: Narrows the list to the seller's own packaging, leaving out the
- marketplace's shared rows
- - name: page
- in: query
- required: false
- description: Page number
- schema:
- type: integer
- - name: limit
- in: query
- required: false
- description: Records per page (max 100)
- schema:
- type: integer
responses:
'200':
- description: package types listed
+ description: fulfillments listed
content:
application/json:
example:
data:
- - id: pkgtype_UkLWZg9DAJ
- name: Standard mailer
- kind: box
- length: '30.0'
- width: '20.0'
- height: '15.0'
- weight: '0.4'
- max_weight:
- default: true
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- dimensions_unit: cm
- weight_unit: kg
- volume: '0.009'
- editable: true
- - id: pkgtype_gbHJdmfrXB
- name: Marketplace carton
- kind: carton
- length: '40.0'
- width: '30.0'
- height: '25.0'
- weight:
- max_weight: '20.0'
- default: false
- metadata: {}
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- dimensions_unit: cm
- weight_unit: kg
- volume: '0.03'
- editable: false
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 81
+ stock_location_name: Vernie Lehner
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1869315
+ sku: SKU-252
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 81
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
meta:
page: 1
limit: 25
- count: 2
+ count: 1
pages: 1
from: 1
- to: 2
- in: 2
+ to: 1
+ in: 1
previous:
next:
schema:
@@ -15631,23 +15845,38 @@ paths:
data:
type: array
items:
- "$ref": "#/components/schemas/PackageType"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
+ "$ref": "#/components/schemas/Fulfillment"
required:
- data
- - meta
- post:
- summary: Create a package type
+ "/api/v3/seller/orders/{order_id}/fulfillments/{id}/fulfill":
+ parameters:
+ - name: order_id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ description: Prefixed fulfillment ID
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Fulfill (ship) a parcel
tags:
- - Package Types
+ - Fulfillments
security:
- bearer_auth: []
description: |
- Records a piece of the seller's own packaging. Marking it `default`
- makes it the box their parcels are quoted with, and demotes whichever
- of their rows held the flag before — the marketplace's default is a
- different owner's row and is left alone.
+ Marks the parcel shipped.
+
+ This is the same workflow the marketplace operator runs, so the
+ customer's dispatch email, the label purchase and any extension hooks
+ happen exactly as they would had the operator shipped it.
+
+ `items` narrows the dispatch to part of what the fulfillment holds; the
+ remainder splits onto a new one. Omit it to ship the lot.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -15655,106 +15884,207 @@ paths:
schema:
type: string
responses:
- '201':
- description: package type created
+ '200':
+ description: parcel shipped
content:
application/json:
example:
- id: pkgtype_EfhxLZ9ck8
- name: Large mailer
- kind: box
- length: '40.0'
- width: '30.0'
- height: '20.0'
- weight: '0.6'
- max_weight:
- default: false
- metadata: {}
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: fulfilled
+ tracking: TRACK-1
+ tracking_url:
+ fulfilled_at: '2026-01-15T12:00:00.000Z'
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- dimensions_unit: cm
- weight_unit: kg
- volume: '0.024'
- editable: true
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 82
+ stock_location_name: Mirta Herman
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 187961
+ sku: SKU-253
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 82
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: TRACK-1
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
schema:
- "$ref": "#/components/schemas/PackageType"
- '422':
- description: validation error
+ "$ref": "#/components/schemas/Fulfillment"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ tracking:
+ type: string
+ description: Carrier tracking number
+ tracking_carrier:
+ type: string
+ description: Carrier name
+ notify_customer:
+ type: boolean
+ description: Send the dispatch email (default true)
+ items:
+ type: array
+ description: Ship only these lines; the rest split onto a new fulfillment
+ items:
+ type: object
+ properties:
+ item_id:
+ type: string
+ description: Prefixed line item ID
+ quantity:
+ type: integer
+ required:
+ - item_id
+ - quantity
+ "/api/v3/seller/orders/{order_id}/fulfillments/{id}":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Update tracking
+ tags:
+ - Fulfillments
+ security:
+ - bearer_auth: []
+ description: |
+ Adds or corrects the tracking number and its carrier.
+
+ Deliberately narrow: where a parcel ships from and which service
+ carries it are the marketplace's arrangements, so they are not
+ editable here.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '200':
+ description: tracking recorded
content:
application/json:
example:
- error:
- code: validation_error
- message: Kind is not included in the list
- details:
- kind:
- - is not included in the list
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: TRACK-2
+ tracking_url: https://www.ups.com/track?tracknum=TRACK-2
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 83
+ stock_location_name: Eugena Schultz
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1883170
+ sku: SKU-254
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 83
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: TRACK-2
+ carrier: ups
+ carrier_name: UPS
+ service:
+ status: pending
+ tracking_url: https://www.ups.com/track?tracknum=TRACK-2
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/Fulfillment"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- kind:
- type: string
- enum:
- - box
- - envelope
- - carton
- - pallet
- - container
- length:
- type: number
- nullable: true
- width:
- type: number
- nullable: true
- height:
- type: number
- nullable: true
- dimensions_unit:
+ tracking:
type: string
nullable: true
- weight:
- type: number
- nullable: true
- description: The empty package's own weight, added to every quote
- max_weight:
- type: number
- nullable: true
- weight_unit:
+ tracking_carrier:
type: string
nullable: true
- default:
- type: boolean
- metadata:
- type: object
- nullable: true
- required:
- - name
- - kind
- required: true
- "/api/v3/seller/package_types/{id}":
+ "/api/v3/seller/orders/{order_id}/fulfillments/{id}/cancel":
parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
- name: id
in: path
required: true
- description: Package type ID
schema:
type: string
- get:
- summary: Get a package type
+ patch:
+ summary: Cancel a parcel
tags:
- - Package Types
+ - Fulfillments
security:
- bearer_auth: []
description: |
- Returns one package type by prefixed ID — the seller's own, or a
- marketplace row they may pack into.
+ A parcel this seller is not going to send after all. The goods go back
+ on the shelf and the carrier is stood down.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -15763,47 +16093,69 @@ paths:
type: string
responses:
'200':
- description: package type found
+ description: parcel canceled
content:
application/json:
example:
- id: pkgtype_UkLWZg9DAJ
- name: Standard mailer
- kind: box
- length: '30.0'
- width: '20.0'
- height: '15.0'
- weight: '0.4'
- max_weight:
- default: true
- metadata: {}
+ id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: canceled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- dimensions_unit: cm
- weight_unit: kg
- volume: '0.009'
- editable: true
- schema:
- "$ref": "#/components/schemas/PackageType"
- '404':
- description: package type not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Package type not found
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 84
+ stock_location_name: Karyn Moore
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1897276
+ sku: SKU-255
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 84
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a package type
+ "$ref": "#/components/schemas/Fulfillment"
+ "/api/v3/seller/tracking_carriers":
+ get:
+ summary: List tracking carriers
tags:
- - Package Types
+ - Fulfillments
security:
- bearer_auth: []
description: |
- Changes the seller's own packaging. A marketplace row is not theirs to
- edit and answers 404.
+ The carriers a tracking number can be pinned to, from the registry —
+ so a carrier an extension adds appears without a client change.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -15812,306 +16164,494 @@ paths:
type: string
responses:
'200':
- description: package type updated
+ description: carriers listed
content:
application/json:
example:
- id: pkgtype_UkLWZg9DAJ
- name: Standard mailer
- kind: box
- length: '30.0'
- width: '20.0'
- height: '15.0'
- weight: '0.4'
- max_weight: '25.0'
- default: true
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- dimensions_unit: cm
- weight_unit: kg
- volume: '0.009'
- editable: true
+ data:
+ - id: australia_post
+ name: Australia Post
+ - id: canada_post
+ name: Canada Post
+ - id: chronopost
+ name: Chronopost
+ - id: colissimo
+ name: Colissimo
+ - id: dhl
+ name: DHL Express
+ - id: dpd
+ name: DPD
+ - id: deutsche_post
+ name: Deutsche Post DHL
+ - id: evri
+ name: Evri
+ - id: fedex
+ name: FedEx
+ - id: gls
+ name: GLS
+ - id: inpost
+ name: InPost
+ - id: poczta_polska
+ name: Poczta Polska
+ - id: postnl
+ name: PostNL
+ - id: royal_mail
+ name: Royal Mail
+ - id: ups
+ name: UPS
+ - id: usps
+ name: USPS
schema:
- "$ref": "#/components/schemas/PackageType"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- kind:
- type: string
- enum:
- - box
- - envelope
- - carton
- - pallet
- - container
- length:
- type: number
- nullable: true
- width:
- type: number
- nullable: true
- height:
- type: number
- nullable: true
- dimensions_unit:
- type: string
- nullable: true
- weight:
- type: number
- nullable: true
- max_weight:
- type: number
- nullable: true
- weight_unit:
- type: string
- nullable: true
- default:
- type: boolean
- metadata:
- type: object
- nullable: true
- required: true
- delete:
- summary: Delete a package type
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ type: object
+ properties:
+ id:
+ type: string
+ name:
+ type: string
+ required:
+ - id
+ - name
+ required:
+ - data
+ "/api/v3/seller/orders":
+ get:
+ summary: List orders
tags:
- - Package Types
+ - Orders
security:
- bearer_auth: []
description: |
- Retires one of the seller's own package types. The default box is
- refused — name another default first, or every parcel silently falls
- back to the marketplace's box.
+ What this seller has sold.
+
+ On a marketplace a basket spanning several sellers is split into one
+ order each, so these are the seller's own orders rather than a filtered
+ view of somebody else's — another seller's order is never reachable,
+ whatever id is sent.
+
+ Checkouts still in flight are left out: until one completes it is
+ nobody's order.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
schema:
type: string
- responses:
- '204':
- description: package type deleted
- "/api/v3/seller/auth/password_resets":
- post:
- summary: Request password reset
- tags:
- - Authentication
- description: |
- Requests a password reset email for a seller.
-
- Unauthenticated. Always answers `202`, whether or not the address
- belongs to a seller, so this cannot be used to discover which accounts
- exist. A store staff member who runs no seller is treated as no match:
- they have no seller panel to be sent to.
-
- `redirect_url` is where the emailed link should point, with the reset
- token appended as a `token` query param. It is honoured only when it
- matches one of the store's allowed origins; otherwise it is silently
- ignored and the server resolves the seller panel origin itself. The
- email is delivered by Spree via the
- `seller_user.password_reset_requested` event, which is never forwarded
- to webhook endpoints.
- parameters: []
- responses:
- '202':
- description: reset requested
- content:
- application/json:
- example:
- message: If an account exists for that email, password reset instructions
- have been sent.
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- redirect_url:
- type: string
- example: https://sellers.your-store.com/reset-password
- description: Must match an allowed origin of the store; ignored
- otherwise.
- required:
- - email
- "/api/v3/seller/auth/password_resets/{id}":
- patch:
- summary: Reset password
- tags:
- - Authentication
- description: |
- Spends a password reset token (the `token` query param from the emailed
- link), sets the new password and signs the seller in: the response
- carries a seller JWT and the rotatable refresh token is set in an
- HttpOnly cookie, so they land in the panel rather than on a login form.
-
- The token is single-use, and resetting revokes every other session the
- account holds. A token whose seller membership has since been revoked is
- refused exactly as an expired one.
- parameters:
- - name: id
- in: path
- description: The reset token from the emailed link
- required: true
+ - name: page
+ in: query
+ required: false
+ description: Page number
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: Records per page (max 100)
+ schema:
+ type: integer
+ - name: sort
+ in: query
+ required: false
+ description: Sort field; prefix with `-` for descending
schema:
type: string
responses:
'200':
- description: password reset
+ description: orders listed
content:
application/json:
example:
- token: eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoxLCJ1c2VyX3R5cGUiOiJhZG1pbiIsImp0aSI6ImJjMDM3NTNhLTEzN2MtNGM1Zi1hMzM2LWUzMjBlZTNiMjQ5YyIsImlzcyI6InNwcmVlIiwiYXVkIjoic2VsbGVyX2FwaSIsImV4cCI6MTc2ODQ3ODcwMH0.EASrzbGpJVyAl10SJyzs8na68Wmvedkm7G66wTBq_0k
- user:
- id: adm_UkLWZg9DAJ
- first_name: Ariana
- last_name: Wiza
- full_name: Ariana Wiza
+ data:
+ - id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: placed
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- selected_locale:
- sellers:
- - id: sel_UkLWZg9DAJ
- name: Seller 80
- status: approved
- schema:
- "$ref": "#/components/schemas/AuthResponse"
- '422':
- description: invalid or expired token
- content:
- application/json:
- example:
- error:
- code: password_reset_token_invalid
- message: Password reset token is invalid or has expired.
+ updated_at: '2026-01-15T12:00:00.000Z'
+ internal_note:
+ internal_note_html:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ commission_amount_total: '0.0'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.0'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.0'
+ display_commission_total: "$0.00"
+ canceled_at:
+ cancel_reason_name:
+ cancel_note:
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 19195
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-257
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 86
+ stock_location_name: Roseline Roberts
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 19195
+ sku: SKU-257
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 86
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 167 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 166 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- password:
- type: string
- example: new-password-123
- password_confirmation:
- type: string
- example: new-password-123
- required:
- - password
- - password_confirmation
- "/api/v3/seller/payouts":
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Order"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ "/api/v3/seller/orders/{id}":
+ parameters:
+ - name: id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
get:
- summary: List payouts
+ summary: Get an order
tags:
- - Earnings
+ - Orders
security:
- bearer_auth: []
description: |
- Settlements to this seller: each one batches the transfers that had
- accumulated since the last, on the seller's payout schedule. `pending`
- and `processing` rows are owed; `completed` ones reached the seller's
- bank. `transfers_count` says how many earnings a settlement covers —
- list them with `GET /api/v3/seller/transfers?q[payout_id_eq]=…`.
+ One order, as the seller needs it to pack and post the parcel: the
+ lines with their SKUs, where it ships to, and a fulfillment per parcel.
- Read-only: a payout is created by the marketplace's sweep and
- confirmed by the payout provider or the operator.
+ How the customer paid the marketplace is deliberately absent — that is
+ between the buyer and the operator.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
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 (max 100)
- schema:
- type: integer
- - name: q[status_eq]
- in: query
- required: false
- schema:
- type: string
- enum:
- - pending
- - processing
- - completed
- - failed
- - unresolved
responses:
'200':
- description: payouts listed
+ description: order found
+ content:
+ application/json:
+ example:
+ id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: placed
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ internal_note:
+ internal_note_html:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ commission_amount_total: '0.0'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.0'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.0'
+ display_commission_total: "$0.00"
+ canceled_at:
+ cancel_reason_name:
+ cancel_note:
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 1929755
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-258
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 87
+ stock_location_name: Woodrow Hand
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1929755
+ sku: SKU-258
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 87
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 169 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 168 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ schema:
+ "$ref": "#/components/schemas/Order"
+ '404':
+ description: another seller's order
content:
application/json:
example:
- data:
- - id: vpo_UkLWZg9DAJ
- status: pending
- currency: USD
- provider: Spree::PayoutProvider::System
- reference:
- period_start:
- period_end:
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- amount: '120.0'
- display_amount: "$120.00"
- transfers_count: 1
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ error:
+ code: order_not_found
+ message: Order not found
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Payout"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- "/api/v3/seller/payouts/{id}":
+ "$ref": "#/components/schemas/ErrorResponse"
+ "/api/v3/seller/orders/{id}/cancel":
parameters:
- name: id
in: path
+ description: Prefixed order ID
required: true
- description: Payout prefixed ID
schema:
type: string
- get:
- summary: Get a payout
+ patch:
+ summary: Cancel an order
tags:
- - Earnings
+ - Orders
security:
- bearer_auth: []
- description: One of this seller's settlements. Another seller's is not found,
- whatever id is sent.
+ description: |
+ Withdraws from an order this seller cannot fulfil, naming a reason from
+ the marketplace's own list.
+
+ The goods go back on the shelf and the payment authorization is
+ released either way. `refund_payments` also hands back what the buyer
+ paid for these goods — a seller is merchant of record for their own
+ child order, and on a split checkout only that order's share of the
+ group's payment is settled.
+
+ There is no `refund_amount`: withdrawing from the whole order returns
+ what that order was paid, and a partial figure is a return.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -16120,167 +16660,202 @@ paths:
type: string
responses:
'200':
- description: payout found
+ description: order canceled
content:
application/json:
example:
- id: vpo_UkLWZg9DAJ
- status: pending
+ id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
currency: USD
- provider: Spree::PayoutProvider::System
- reference:
- period_start:
- period_end:
+ total_quantity: 1
+ status: canceled
+ fulfillment_status: canceled
+ payment_status: none
+ completed_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- amount: '120.0'
- display_amount: "$120.00"
- transfers_count: 1
- schema:
- "$ref": "#/components/schemas/Payout"
- '404':
- description: payout not found
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Seller payout not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- "/api/v3/seller/policies":
- get:
- summary: List policies
- tags:
- - Policies
- security:
- - bearer_auth: []
- description: |
- This seller's own policy documents.
-
- Rooted in the acting seller, so the marketplace operator's store
- policies and every other seller's are invisible here. A seller starts
- with none: what they are expected to publish is decided by the
- marketplace's onboarding checklist.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- 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 (max 100)
- schema:
- type: integer
- responses:
- '200':
- description: policies listed
- content:
- application/json:
- example:
- data:
- - id: pol_uw2YK1rnl0
- name: Returns Policy
- slug: returns-policy
- body: Send anything back within 30 days.
- body_html: "<p>Send anything back within 30 days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
+ internal_note:
+ internal_note_html:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ amount_due: "-0.0"
+ display_amount_due: "$0.00"
+ commission_amount_total: '0.0'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.0'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.0'
+ display_commission_total: "$0.00"
+ canceled_at: '2026-01-15T12:00:00Z'
+ cancel_reason_name:
+ cancel_note:
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 1956554
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-261
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: canceled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
- 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/Policy"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- post:
- summary: Create a policy
- tags:
- - Policies
- security:
- - bearer_auth: []
- description: |
- Publishes one of this seller's policies. `body` accepts HTML and is
- sanitized before it is stored.
-
- When the marketplace requires a named policy, use that exact name —
- the onboarding check matches on it.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '201':
- description: policy created
- content:
- application/json:
- example:
- id: pol_OIJLhNcSbf
- name: Shipping Policy
- slug: shipping-policy
- body: Orders leave the workshop within two working days.
- body_html: "<p>Orders leave the workshop within two working days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 90
+ stock_location_name: Ricky Kutch
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1956554
+ sku: SKU-261
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 90
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 175 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 174 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
schema:
- "$ref": "#/components/schemas/Policy"
+ "$ref": "#/components/schemas/Order"
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Shipping Policy
- slug:
+ cancel_reason_id:
type: string
- example: shipping-policy
- body:
+ nullable: true
+ description: A reason from GET /order_cancellation_reasons
+ cancel_note:
type: string
- example: "<p>Orders leave the workshop within two working days.</p>"
- required:
- - name
- "/api/v3/seller/policies/{id}":
+ nullable: true
+ description: Free text beside the reason
+ refund_payments:
+ type: boolean
+ description: Hand back what the buyer paid for this order's goods
+ notify_customer:
+ type: boolean
+ description: Email the customer about the cancellation
+ "/api/v3/seller/orders/{id}/address":
parameters:
- name: id
in: path
+ description: Prefixed order ID
required: true
- description: Policy prefixed ID or slug
schema:
type: string
- get:
- summary: Get a policy
+ patch:
+ summary: Correct an order address
tags:
- - Policies
+ - Orders
security:
- bearer_auth: []
- description: Returns one of this seller's policies, by prefixed ID or slug.
+ description: |
+ Corrects where the goods go or who the invoice names.
+
+ The seller is merchant of record for their own child order, so a
+ delivery address the buyer got wrong is theirs to fix. Send only the
+ lines that change — the rest of the address is carried over.
+
+ This is the only write against the order itself besides cancelling:
+ nothing else about it, its totals included, is the seller's to change.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -16289,313 +16864,438 @@ paths:
type: string
responses:
'200':
- description: policy found
+ description: address corrected
content:
application/json:
example:
- id: pol_uw2YK1rnl0
- name: Returns Policy
- slug: returns-policy
- body: Send anything back within 30 days.
- body_html: "<p>Send anything back within 30 days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
+ id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: placed
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ internal_note:
+ internal_note_html:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ commission_amount_total: '0.0'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.0'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.0'
+ display_commission_total: "$0.00"
+ canceled_at:
+ cancel_reason_name:
+ cancel_note:
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 1965038
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-262
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 91
+ stock_location_name: Rudy Mosciski
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1965038
+ sku: SKU-262
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 91
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
+ shipping_address:
+ id: addr_EfhxLZ9ck8
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 9 Corrected Way
+ address2: Northwest
+ postal_code: '10118'
+ city: Fixedton
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 176 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
schema:
- "$ref": "#/components/schemas/Policy"
- '404':
- description: policy not found
+ "$ref": "#/components/schemas/Order"
+ '422':
+ description: neither address named
content:
application/json:
example:
error:
- code: record_not_found
- message: Policy not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a policy
- tags:
- - Policies
- security:
- - bearer_auth: []
- description: Rewrites one of this seller's policies.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: policy updated
- content:
- application/json:
- example:
- id: pol_uw2YK1rnl0
- name: Returns Policy
- slug: returns-policy
- body: Send anything back within 60 days.
- body_html: "<p>Send anything back within 60 days.</p>"
- updated_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/Policy"
+ code: validation_error
+ message: shipping_address or billing_address is required
+ details:
+ base:
+ - shipping_address or billing_address is required
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- slug:
- type: string
- body:
- type: string
- delete:
- summary: Delete a policy
- tags:
- - Policies
- security:
- - bearer_auth: []
- description: Withdraws one of this seller's policies.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '204':
- description: policy deleted
- "/api/v3/seller/product_types":
- get:
- summary: List product types
- tags:
- - Product Types
- security:
- - bearer_auth: []
- description: |
- The product types a seller may list a product against.
-
- Read only. A type is the template that hands a product its option types
- and its delivery profile, so a seller picks one when listing; defining
- types is the marketplace's. Send the chosen `id` as `product_type_id`
- on the product.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- 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 (max 100)
- schema:
- type: integer
- responses:
- '200':
- description: product types listed
- content:
- application/json:
- example:
- data:
- - id: pt_UkLWZg9DAJ
- name: Apparel
- option_type_labels: []
- 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/ProductType"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- "/api/v3/seller/product_types/{id}":
- get:
- summary: Get a product type
- tags:
- - Product Types
- security:
- - bearer_auth: []
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- - name: id
- in: path
+ shipping_address:
+ type: object
+ description: Only the lines that change; the rest is carried over
+ properties:
+ first_name:
+ type: string
+ last_name:
+ type: string
+ company:
+ type: string
+ nullable: true
+ address1:
+ type: string
+ address2:
+ type: string
+ nullable: true
+ city:
+ type: string
+ postal_code:
+ type: string
+ country_code:
+ type: string
+ state_code:
+ type: string
+ nullable: true
+ state_name:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ label:
+ type: string
+ nullable: true
+ billing_address:
+ type: object
+ description: Only the lines that change; the rest is carried over
+ properties:
+ first_name:
+ type: string
+ last_name:
+ type: string
+ company:
+ type: string
+ nullable: true
+ address1:
+ type: string
+ address2:
+ type: string
+ nullable: true
+ city:
+ type: string
+ postal_code:
+ type: string
+ country_code:
+ type: string
+ state_code:
+ type: string
+ nullable: true
+ state_name:
+ type: string
+ nullable: true
+ phone:
+ type: string
+ nullable: true
+ label:
+ type: string
+ nullable: true
required: true
- description: Product type ID
- schema:
- type: string
- responses:
- '200':
- description: product type found
- content:
- application/json:
- example:
- id: pt_UkLWZg9DAJ
- name: Apparel
- option_type_labels: []
- schema:
- "$ref": "#/components/schemas/ProductType"
- "/api/v3/seller/products":
+ "/api/v3/seller/orders/{order_id}/notes":
+ parameters:
+ - name: order_id
+ in: path
+ description: Prefixed order ID
+ required: true
+ schema:
+ type: string
get:
- summary: List products
+ summary: Get order notes
tags:
- - Products
+ - Orders
security:
- bearer_auth: []
description: |
- The seller's own catalog — the products they own outright.
+ The instructions the buyer left, and the seller's own working note.
- Every call is rooted in the acting seller server-side, so this can never
- return another seller's product or one the marketplace operator sells
- first-party.
+ A marketplace basket splits into one order per seller, so the internal
+ note here is this seller's alone rather than the operator's note about
+ the whole sale.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
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 (max 100)
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: Sort field; prefix with `-` for descending
- schema:
- type: string
responses:
'200':
- description: products listed
+ description: notes
content:
application/json:
example:
- data:
- - id: prod_UkLWZg9DAJ
- name: Product 2053250
- slug: product-2053250
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 1
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: Maiores ut qui dolores ab autem. Architecto quos sequi
- minus debitis tempora molestiae. Quasi officiis minus voluptatum
- eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati
- ducimus. Provident quo amet nostrum sed assumenda cum odio. Distinctio
- perferendis quasi nisi exercitationem veritatis minima esse. In
- velit at corporis nobis. Voluptate mollitia nam pariatur enim.
- Recusandae necessitatibus earum deserunt sapiente eveniet quidem
- unde. Consectetur ab perspiciatis veniam dolor tempora. Omnis
- odit autem quae repellat. Delectus corrupti ea nisi reiciendis
- atque iure a molestias. Repellendus laboriosam sint molestias
- debitis in. Minima omnis accusantium modi accusamus doloribus
- fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.
- description_html: |-
- Maiores ut qui dolores ab autem. Architecto quos sequi minus debitis tempora molestiae. Quasi officiis minus voluptatum eveniet incidunt. Nisi laboriosam a aliquam eveniet occaecati ducimus. Provident quo amet nostrum sed assumenda cum odio.
- Distinctio perferendis quasi nisi exercitationem veritatis minima esse. In velit at corporis nobis. Voluptate mollitia nam pariatur enim. Recusandae necessitatibus earum deserunt sapiente eveniet quidem unde.
- Consectetur ab perspiciatis veniam dolor tempora. Omnis odit autem quae repellat. Delectus corrupti ea nisi reiciendis atque iure a molestias.
- Repellendus laboriosam sint molestias debitis in. Minima omnis accusantium modi accusamus doloribus fugit. Accusamus autem sequi perferendis saepe quos perspiciatis.
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
+ id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: placed
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ internal_note:
+ internal_note_html:
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ commission_amount_total: '0.0'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.0'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.0'
+ display_commission_total: "$0.00"
+ canceled_at:
+ cancel_reason_name:
+ cancel_note:
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 1983962
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-264
thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id: sel_UkLWZg9DAJ
- status: active
- metadata: {}
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- product_type_id:
- delivery_profile_id: fp_UkLWZg9DAJ
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 93
+ stock_location_name: Kecia Pollich
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1983962
+ sku: SKU-264
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 93
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 181 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 180 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/Product"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- post:
- summary: Create a product
+ "$ref": "#/components/schemas/Order"
+ patch:
+ summary: Update order notes
tags:
- - Products
+ - Orders
security:
- bearer_auth: []
description: |
- Creates a product owned by the acting seller.
-
- The seller and the store are taken from the request context whatever the
- payload says, so a product cannot be created against another seller.
+ Send only the note that changes: an absent key leaves the other alone,
+ while an empty string clears it.
- The operator's own settings — tax category, delivery profile and whether
- the product is promotionable — are not writable here; they belong to the
- marketplace, not the seller.
+ `internal_note` accepts HTML and is sanitized on save;
+ `internal_note_html` reads it back.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -16603,141 +17303,198 @@ paths:
schema:
type: string
responses:
- '201':
- description: product created
+ '200':
+ description: notes updated
content:
application/json:
example:
- id: prod_gbHJdmfrXB
- name: Hand-thrown mug
- slug: hand-thrown-mug
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 0
- available_on:
- preorder_ships_at:
- purchasable: false
- preorder: false
- in_stock: false
- backorderable: false
- available: false
- description:
- description_html:
- default_variant_id: variant_gbHJdmfrXB
- buy_box_variant_id: variant_gbHJdmfrXB
- thumbnail_url:
- tags: []
- price:
- id: price_gbHJdmfrXB
- amount: '24.0'
- amount_in_cents: 2400
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$24.00"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id: sel_UkLWZg9DAJ
- status: draft
- metadata: {}
+ id: or_UkLWZg9DAJ
+ number: R1001
+ customer_note:
+ currency: USD
+ total_quantity: 1
+ status: placed
+ fulfillment_status:
+ payment_status:
+ completed_at: '2026-01-15T12:00:00.000Z'
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- product_type_id:
- delivery_profile_id: fp_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/Product"
- '422':
- description: validation failed
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Hand-thrown mug
- description:
- type: string
- slug:
- type: string
- example: hand-thrown-mug
- status:
- type: string
- example: draft
- meta_title:
- type: string
- meta_description:
- type: string
- meta_keywords:
- type: string
- product_type_id:
- type: string
- example: ptype_abc123
- tags:
- type: array
- items:
- type: string
- example:
- - ceramics
- - handmade
- category_ids:
- type: array
- items:
- type: string
- example:
- - cat_abc123
- metadata:
- type: object
- additionalProperties: true
- prices:
- type: array
- items:
- type: object
- properties:
- amount:
- type: string
- example: '24.00'
- compare_at_amount:
- type: string
- example: '30.00'
- currency:
- type: string
- example: USD
- required:
- - name
- "/api/v3/seller/products/{id}":
- parameters:
- - name: id
- in: path
- description: Product ID
- required: true
- schema:
- type: string
+ internal_note: Packed with the fragile insert.
+ internal_note_html: "<p>Packed with the fragile insert.</p>"
+ item_total: '10.0'
+ display_item_total: "$10.00"
+ delivery_total: '100.0'
+ display_delivery_total: "$100.00"
+ discount_total: '0.0'
+ display_discount_total: "$0.00"
+ adjustment_total: '0.0'
+ display_adjustment_total: "$0.00"
+ included_tax_total: '0.0'
+ display_included_tax_total: "$0.00"
+ additional_tax_total: '0.0'
+ display_additional_tax_total: "$0.00"
+ tax_total: '0.0'
+ display_tax_total: "$0.00"
+ total: '110.0'
+ display_total: "$110.00"
+ payment_total: '0.0'
+ display_payment_total: "$0.00"
+ amount_due: '110.0'
+ display_amount_due: "$110.00"
+ commission_amount_total: '0.0'
+ display_commission_amount_total: "$0.00"
+ commission_tax_total: '0.0'
+ display_commission_tax_total: "$0.00"
+ commission_total: '0.0'
+ display_commission_total: "$0.00"
+ canceled_at:
+ cancel_reason_name:
+ cancel_note:
+ items:
+ - id: li_UkLWZg9DAJ
+ name: Product 1995749
+ options_text: ''
+ quantity: 1
+ currency: USD
+ price: '10.0'
+ display_price: "$10.00"
+ total: '10.0'
+ display_total: "$10.00"
+ variant_id: variant_UkLWZg9DAJ
+ sku: SKU-265
+ thumbnail_url:
+ fulfillments:
+ - id: ful_UkLWZg9DAJ
+ number: R1001-F1
+ status: unfulfilled
+ tracking: U10000
+ tracking_url:
+ fulfilled_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ fulfillment_type: shipping
+ delivery_method_name: UPS Ground 94
+ stock_location_name: Ophelia Hartmann
+ stock_location_id: sloc_UkLWZg9DAJ
+ fulfillment_items:
+ - id: fi_UkLWZg9DAJ
+ quantity: 1
+ line_item_id: li_UkLWZg9DAJ
+ variant_id: variant_UkLWZg9DAJ
+ name: Product 1995749
+ sku: SKU-265
+ options_text: ''
+ selected_delivery_rate_id: dr_gbHJdmfrXB
+ delivery_rates:
+ - id: dr_gbHJdmfrXB
+ name: UPS Ground 94
+ selected: true
+ cost: '10.0'
+ total: '10.0'
+ carrier:
+ service_level:
+ estimated_delivery_date:
+ display_cost: "$10.00"
+ display_total: "$10.00"
+ deliveries:
+ - id: dlv_UkLWZg9DAJ
+ tracking_number: U10000
+ carrier:
+ carrier_name:
+ service:
+ status: pending
+ tracking_url:
+ estimated_delivery_at:
+ delivered_at:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ shipping_label_id:
+ labels: []
+ shipping_address:
+ id: addr_gbHJdmfrXB
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 183 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ billing_address:
+ id: addr_UkLWZg9DAJ
+ label:
+ first_name: John
+ last_name: Doe
+ full_name: John Doe
+ address1: 182 Lovely Street
+ address2: Northwest
+ postal_code: '10118'
+ city: New York
+ phone: 555-555-0199
+ company: Company
+ country_name: United States
+ country_code: US
+ state_text: NY
+ state_code: NY
+ quick_checkout: false
+ is_default_billing: false
+ is_default_shipping: false
+ state_abbr: NY
+ country_iso: US
+ state_name: New York
+ schema:
+ "$ref": "#/components/schemas/Order"
+ '422':
+ description: neither note named
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: customer_note or internal_note is required
+ details:
+ base:
+ - customer_note or internal_note is required
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ customer_note:
+ type: string
+ nullable: true
+ description: What the buyer asked for
+ internal_note:
+ type: string
+ nullable: true
+ description: The seller's own working note, as HTML
+ required: true
+ "/api/v3/seller/order_cancellation_reasons":
get:
- summary: Get a product
+ summary: List order cancellation reasons
tags:
- - Products
+ - Orders
security:
- bearer_auth: []
description: |
- A product the acting seller owns.
+ Why an order was called off, as the marketplace defines it.
- An id belonging to another seller answers `404`, not `403` — the seller
- is not told the record exists.
+ Read-only: a seller picks one when cancelling, and the operator decides
+ what the list holds. Retired reasons are left out.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -16746,135 +17503,194 @@ paths:
type: string
responses:
'200':
- description: product returned
- content:
- application/json:
- example:
- id: prod_UkLWZg9DAJ
- name: Product 2086710
- slug: product-2086710
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 1
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: Aliquid voluptate laudantium necessitatibus quidem eaque.
- Sapiente at autem eveniet exercitationem odio in dolores. Laborum
- accusantium nulla autem tempora qui inventore assumenda molestiae.
- Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi
- eius provident unde neque in. Earum pariatur enim odit delectus
- accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam
- ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident
- at itaque temporibus. Adipisci iste beatae quibusdam perferendis
- ea blanditiis saepe facilis.
- description_html: |-
- Aliquid voluptate laudantium necessitatibus quidem eaque. Sapiente at autem eveniet exercitationem odio in dolores. Laborum accusantium nulla autem tempora qui inventore assumenda molestiae. Quisquam voluptas delectus ipsum totam ab incidunt. Sunt excepturi eius provident unde neque in.
- Earum pariatur enim odit delectus accusamus recusandae. Dolorem eligendi debitis iste voluptate laboriosam ab. Ab aut suscipit illo occaecati. Dolores libero cupiditate provident at itaque temporibus. Adipisci iste beatae quibusdam perferendis ea blanditiis saepe facilis.
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id: sel_UkLWZg9DAJ
- status: active
- metadata: {}
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- product_type_id:
- delivery_profile_id: fp_UkLWZg9DAJ
- schema:
- "$ref": "#/components/schemas/Product"
- '404':
- description: another seller's product
+ description: reasons listed
content:
application/json:
example:
- error:
- code: record_not_found
- message: Product not found
+ data:
+ - id: ocr_UkLWZg9DAJ
+ name: Out of stock
+ active: true
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a product
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Reason"
+ required:
+ - data
+ "/api/v3/seller/package_types":
+ get:
+ summary: List package types
tags:
- - Products
+ - Package Types
security:
- bearer_auth: []
- description: Edits a product the acting seller owns.
+ description: |
+ What this seller packs their goods into: the boxes their parcels ship
+ in, the cartons their products are packed into, the pallets a
+ wholesale order leaves on.
+
+ The list carries the marketplace's own packaging alongside the
+ seller's, so a seller can pack into the operator's standard cartons
+ rather than measuring them again. Those rows report `editable: false`
+ and are refused by every write.
+
+ The row marked `default` is the box this seller's parcels are quoted
+ with — its size and weight are added to every rate.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
schema:
type: string
+ - name: owner
+ in: query
+ required: false
+ schema:
+ type: string
+ enum:
+ - mine
+ description: Narrows the list to the seller's own packaging, leaving out the
+ marketplace's shared rows
+ - name: page
+ in: query
+ required: false
+ description: Page number
+ schema:
+ type: integer
+ - name: limit
+ in: query
+ required: false
+ description: Records per page (max 100)
+ schema:
+ type: integer
responses:
'200':
- description: product updated
+ description: package types listed
content:
application/json:
example:
- id: prod_UkLWZg9DAJ
- name: Hand-thrown mug, large
- slug: product-2118212
- meta_title:
- meta_description:
- meta_keywords:
- variant_count: 1
- available_on:
- preorder_ships_at:
- purchasable: true
- preorder: false
- in_stock: false
- backorderable: true
- available: true
- description: Vel minima recusandae iure deserunt non. Corrupti soluta
- pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto
- animi. Eum facilis veniam a consequatur minus. Dolor iure facilis
- repellendus tenetur. Nobis harum perferendis ab maiores labore eius
- eum quo.
- description_html: |-
- Vel minima recusandae iure deserunt non. Corrupti soluta pariatur recusandae saepe eveniet. Sequi deserunt fugiat architecto animi.
- Eum facilis veniam a consequatur minus. Dolor iure facilis repellendus tenetur. Nobis harum perferendis ab maiores labore eius eum quo.
- default_variant_id: variant_UkLWZg9DAJ
- buy_box_variant_id: variant_UkLWZg9DAJ
- thumbnail_url:
- tags: []
- price:
- id: price_UkLWZg9DAJ
- amount: '19.99'
- amount_in_cents: 1999
- compare_at_amount:
- compare_at_amount_in_cents:
- currency: USD
- display_amount: "$19.99"
- display_compare_at_amount:
- price_list_id:
- original_price:
- seller_id: sel_UkLWZg9DAJ
- status: active
+ data:
+ - id: pkgtype_UkLWZg9DAJ
+ name: Standard mailer
+ kind: box
+ length: '30.0'
+ width: '20.0'
+ height: '15.0'
+ weight: '0.4'
+ max_weight:
+ default: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ dimensions_unit: cm
+ weight_unit: kg
+ volume: '0.009'
+ editable: true
+ - id: pkgtype_gbHJdmfrXB
+ name: Marketplace carton
+ kind: carton
+ length: '40.0'
+ width: '30.0'
+ height: '25.0'
+ weight:
+ max_weight: '20.0'
+ default: false
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ dimensions_unit: cm
+ weight_unit: kg
+ volume: '0.03'
+ editable: false
+ meta:
+ page: 1
+ limit: 25
+ count: 2
+ pages: 1
+ from: 1
+ to: 2
+ in: 2
+ previous:
+ next:
+ schema:
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/PackageType"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ post:
+ summary: Create a package type
+ tags:
+ - Package Types
+ security:
+ - bearer_auth: []
+ description: |
+ Records a piece of the seller's own packaging. Marking it `default`
+ makes it the box their parcels are quoted with, and demotes whichever
+ of their rows held the flag before — the marketplace's default is a
+ different owner's row and is left alone.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '201':
+ description: package type created
+ content:
+ application/json:
+ example:
+ id: pkgtype_EfhxLZ9ck8
+ name: Large mailer
+ kind: box
+ length: '40.0'
+ width: '30.0'
+ height: '20.0'
+ weight: '0.6'
+ max_weight:
+ default: false
metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
updated_at: '2026-01-15T12:00:00.000Z'
- product_type_id:
- delivery_profile_id: fp_UkLWZg9DAJ
+ dimensions_unit: cm
+ weight_unit: kg
+ volume: '0.024'
+ editable: true
schema:
- "$ref": "#/components/schemas/Product"
+ "$ref": "#/components/schemas/PackageType"
+ '422':
+ description: validation error
+ content:
+ application/json:
+ example:
+ error:
+ code: validation_error
+ message: Kind is not included in the list
+ details:
+ kind:
+ - is not included in the list
+ schema:
+ "$ref": "#/components/schemas/ErrorResponse"
requestBody:
content:
application/json:
@@ -16883,54 +17699,62 @@ paths:
properties:
name:
type: string
- example: Hand-thrown mug, large
- description:
+ kind:
type: string
- slug:
+ enum:
+ - box
+ - envelope
+ - carton
+ - pallet
+ - container
+ length:
+ type: number
+ nullable: true
+ width:
+ type: number
+ nullable: true
+ height:
+ type: number
+ nullable: true
+ dimensions_unit:
type: string
- status:
+ nullable: true
+ weight:
+ type: number
+ nullable: true
+ description: The empty package's own weight, added to every quote
+ max_weight:
+ type: number
+ nullable: true
+ weight_unit:
type: string
- example: active
- tags:
- type: array
- items:
- type: string
- category_ids:
- type: array
- items:
- type: string
+ nullable: true
+ default:
+ type: boolean
metadata:
type: object
- additionalProperties: true
- delete:
- summary: Delete a product
- tags:
- - Products
- security:
- - bearer_auth: []
- description: Deletes a product the acting seller owns.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
+ nullable: true
+ required:
+ - name
+ - kind
required: true
- schema:
- type: string
- responses:
- '204':
- description: product deleted
- "/api/v3/seller/profile":
+ "/api/v3/seller/package_types/{id}":
+ parameters:
+ - name: id
+ in: path
+ required: true
+ description: Package type ID
+ schema:
+ type: string
get:
- summary: Get profile
+ summary: Get a package type
tags:
- - Profile
+ - Package Types
security:
- bearer_auth: []
description: |
- The seller's own record.
-
- Singular by nature: the seller in play is always the one named by
- `X-Spree-Seller-Id`, never an id in the path — so a seller cannot address
- another seller here even by guessing one.
+ Returns one package type by prefixed ID — the seller's own, or a
+ marketplace row they may pack into.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -16939,71 +17763,47 @@ paths:
type: string
responses:
'200':
- description: profile returned
+ description: package type found
content:
application/json:
example:
- id: sel_UkLWZg9DAJ
- name: Seller 100
- slug: seller-100
- about: ''
- about_html: ''
- logo_url:
- square_logo_url:
- cover_photo_url:
- preferred_timezone: UTC
- status: approved
- legal_name:
- registration_number:
- contact_email:
- billing_email:
- tax_remittance: seller
- payouts_schedule_interval:
- holiday_mode_until:
- terms_accepted_at: '2026-01-15T12:00:00.000Z'
+ id: pkgtype_UkLWZg9DAJ
+ name: Standard mailer
+ kind: box
+ length: '30.0'
+ width: '20.0'
+ height: '15.0'
+ weight: '0.4'
+ max_weight:
+ default: true
+ metadata: {}
created_at: '2026-01-15T12:00:00.000Z'
- minimum_payout_amount:
- on_holiday: false
- sellable: true
- default_currency: USD
- supported_currencies:
- - USD
- - EUR
- - GBP
- products_count: 0
+ updated_at: '2026-01-15T12:00:00.000Z'
+ dimensions_unit: cm
+ weight_unit: kg
+ volume: '0.009'
+ editable: true
schema:
- "$ref": "#/components/schemas/Profile"
- '403':
- description: no seller named, or not a member of it
+ "$ref": "#/components/schemas/PackageType"
+ '404':
+ description: package type not found
content:
application/json:
example:
error:
- code: access_denied
- message: You do not have access to this seller.
+ code: record_not_found
+ message: Package type not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
patch:
- summary: Update profile
+ summary: Update a package type
tags:
- - Profile
+ - Package Types
security:
- bearer_auth: []
description: |
- Edits presentation, contact details and addresses.
-
- Readable but **not** writable, by design: `status` — the lifecycle belongs
- to the marketplace operator's workflows — the settlement terms, and
- `slug`, since a seller renaming their own storefront address would break
- every link pointing at it.
-
- `accept_terms: true` stamps the moment the seller accepted the
- marketplace's terms, which is what the matching onboarding requirement
- reads. One-way — sending `false` does not unmake the stamp.
-
- `custom_fields` is narrowed server-side to the definitions this
- marketplace's onboarding actually asks this seller for; a field nothing
- asked for is ignored rather than written.
+ Changes the seller's own packaging. A marketplace row is not theirs to
+ edit and answers 404.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -17011,54 +17811,29 @@ paths:
schema:
type: string
responses:
- '200':
- description: profile updated
- content:
- application/json:
- example:
- id: sel_UkLWZg9DAJ
- name: Acme Supplies
- slug: seller-102
- about: ''
- about_html: ''
- logo_url:
- square_logo_url:
- cover_photo_url:
- preferred_timezone: UTC
- status: approved
- legal_name:
- registration_number:
- contact_email: [email protected]
- billing_email:
- tax_remittance: seller
- payouts_schedule_interval:
- holiday_mode_until:
- terms_accepted_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- minimum_payout_amount:
- on_holiday: false
- sellable: true
- default_currency: USD
- supported_currencies:
- - USD
- - EUR
- - GBP
- products_count: 0
- schema:
- "$ref": "#/components/schemas/Profile"
- '422':
- description: validation failed
+ '200':
+ description: package type updated
content:
application/json:
example:
- error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
+ id: pkgtype_UkLWZg9DAJ
+ name: Standard mailer
+ kind: box
+ length: '30.0'
+ width: '20.0'
+ height: '15.0'
+ weight: '0.4'
+ max_weight: '25.0'
+ default: true
+ metadata: {}
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ dimensions_unit: cm
+ weight_unit: kg
+ volume: '0.009'
+ editable: true
schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ "$ref": "#/components/schemas/PackageType"
requestBody:
content:
application/json:
@@ -17067,153 +17842,162 @@ paths:
properties:
name:
type: string
- example: Acme Supplies
- contact_email:
- type: string
- format: email
- nullable: true
- billing_email:
+ kind:
type: string
- format: email
+ enum:
+ - box
+ - envelope
+ - carton
+ - pallet
+ - container
+ length:
+ type: number
nullable: true
- about:
- type: string
+ width:
+ type: number
nullable: true
- description: Sanitized HTML — the seller's public description
- legal_name:
- type: string
+ height:
+ type: number
nullable: true
- description: The business a commission invoice is made out to
- registration_number:
+ dimensions_unit:
type: string
nullable: true
- logo:
- type: string
+ weight:
+ type: number
nullable: true
- description: ActiveStorage signed id; `null` removes the attachment
- square_logo:
- type: string
+ max_weight:
+ type: number
nullable: true
- cover_photo:
+ weight_unit:
type: string
nullable: true
- accept_terms:
+ default:
type: boolean
- description: Stamps acceptance of the marketplace terms
- billing_address:
+ metadata:
type: object
- additionalProperties: true
- custom_fields:
- type: array
- items:
- type: object
- properties:
- custom_field_definition_id:
- type: string
- example: cfd_abc123
- value:
- description: Any JSON value the definition accepts
- "/api/v3/seller/requirements/{requirement_id}/submissions":
- parameters:
- - name: requirement_id
- in: path
- description: Requirement ID, as returned by `GET /api/v3/seller/onboarding`
- required: true
- schema:
- type: string
- post:
- summary: Submit against a requirement
+ nullable: true
+ required: true
+ delete:
+ summary: Delete a package type
tags:
- - Onboarding
+ - Package Types
security:
- bearer_auth: []
description: |
- What the seller says about one requirement: an attestation they tick, a
- document they upload, a reference they paste.
-
- Create only. A submission records what was said and when, so a seller who
- needs to correct something submits again rather than editing, and the
- latest one counts.
-
- `file` is **not** a multipart upload — it is the `signed_id` returned by
- `POST /api/v3/seller/direct_uploads`, so the bytes are already in storage
- by the time this runs.
+ Retires one of the seller's own package types. The default box is
+ refused — name another default first, or every parcel silently falls
+ back to the marketplace's box.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: package type deleted
+ "/api/v3/seller/payouts":
+ get:
+ summary: List payouts
+ tags:
+ - Earnings
+ security:
+ - bearer_auth: []
+ description: |
+ Settlements to this seller: each one batches the transfers that had
+ accumulated since the last, on the seller's payout schedule. `pending`
+ and `processing` rows are owed; `completed` ones reached the seller's
+ bank. `transfers_count` says how many earnings a settlement covers —
+ list them with `GET /api/v3/seller/transfers?q[payout_id_eq]=…`.
- An attestation is accepted on the spot; a requirement the operator
- reviews comes back `pending`.
+ Read-only: a payout is created by the marketplace's sweep and
+ confirmed by the payout provider or the operator.
parameters:
- name: X-Spree-Seller-Id
in: header
required: true
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 (max 100)
+ schema:
+ type: integer
+ - name: q[status_eq]
+ in: query
+ required: false
+ schema:
+ type: string
+ enum:
+ - pending
+ - processing
+ - completed
+ - failed
+ - unresolved
responses:
- '201':
- description: submission recorded
- content:
- application/json:
- example:
- id: selsub_UkLWZg9DAJ
- status: accepted
- note: Confirmed.
- review_note:
- reference:
- reviewed_at: '2026-01-15T12:00:00.000Z'
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- file_url:
- file_name:
- schema:
- "$ref": "#/components/schemas/RequirementSubmission"
- '404':
- description: a requirement belonging to another marketplace
+ '200':
+ description: payouts listed
content:
application/json:
example:
- error:
- code: record_not_found
- message: Seller requirement not found
+ data:
+ - id: vpo_UkLWZg9DAJ
+ status: pending
+ currency: USD
+ provider: Spree::PayoutProvider::System
+ reference:
+ period_start:
+ period_end:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '120.0'
+ display_amount: "$120.00"
+ transfers_count: 1
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- note:
- type: string
- description: Anything the seller wants to say alongside the submission
- reference:
- type: string
- description: A reference number or external identifier, for requirements
- that ask for one
- file:
- type: string
- description: A direct-upload `signed_id`, for requirements that
- ask for a document
- "/api/v3/seller/requirement_submissions/{id}/download":
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Payout"
+ meta:
+ "$ref": "#/components/schemas/PaginationMeta"
+ required:
+ - data
+ - meta
+ "/api/v3/seller/payouts/{id}":
parameters:
- name: id
in: path
- description: Submission ID
required: true
+ description: Payout prefixed ID
schema:
type: string
get:
- summary: Download a submitted document
+ summary: Get a payout
tags:
- - Onboarding
+ - Earnings
security:
- bearer_auth: []
- description: |
- Streams the file attached to one of this seller's submissions.
-
- Served through the API rather than from a storage URL on purpose: these
- are identity and registration documents, so every read is authorized
- against the acting seller. Another seller's submission answers `404`.
+ description: One of this seller's settlements. Another seller's is not found,
+ whatever id is sent.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -17221,15 +18005,33 @@ paths:
schema:
type: string
responses:
+ '200':
+ description: payout found
+ content:
+ application/json:
+ example:
+ id: vpo_UkLWZg9DAJ
+ status: pending
+ currency: USD
+ provider: Spree::PayoutProvider::System
+ reference:
+ period_start:
+ period_end:
+ created_at: '2026-01-15T12:00:00.000Z'
+ updated_at: '2026-01-15T12:00:00.000Z'
+ amount: '120.0'
+ display_amount: "$120.00"
+ transfers_count: 1
+ schema:
+ "$ref": "#/components/schemas/Payout"
'404':
- description: another seller's submission
+ description: payout not found
content:
application/json:
example:
error:
code: record_not_found
- message: Seller requirement submission not found
- application/octet-stream:
+ message: Seller payout not found
schema:
"$ref": "#/components/schemas/ErrorResponse"
"/api/v3/seller/orders/{order_id}/returns":
@@ -17263,6 +18065,34 @@ paths:
description: returns listed
content:
application/json:
+ example:
+ data:
+ - id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.0'
+ display_refund_total: "$10.00"
+ approved_at:
+ received_at:
+ refunded_at:
+ canceled_at:
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
+ refunded_total: '0.0'
+ refundable_total: '10.0'
+ display_refunded_total: "$0.00"
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
type: object
properties:
@@ -17296,6 +18126,23 @@ paths:
description: return opened
content:
application/json:
+ example:
+ id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: requested
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.0'
+ display_refund_total: "$10.00"
+ approved_at:
+ received_at:
+ refunded_at:
+ canceled_at:
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
+ refunded_total: '0.0'
+ refundable_total: '10.0'
+ display_refunded_total: "$0.00"
schema:
"$ref": "#/components/schemas/Return"
'422':
@@ -17365,6 +18212,23 @@ paths:
description: return approved
content:
application/json:
+ example:
+ id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: approved
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.0'
+ display_refund_total: "$10.00"
+ approved_at: '2026-01-15T12:00:00Z'
+ received_at:
+ refunded_at:
+ canceled_at:
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
+ refunded_total: '0.0'
+ refundable_total: '10.0'
+ display_refunded_total: "$0.00"
schema:
"$ref": "#/components/schemas/Return"
"/api/v3/seller/orders/{order_id}/returns/{id}/receive":
@@ -17382,276 +18246,88 @@ paths:
patch:
summary: Receive a return
tags:
- - Returns
- security:
- - bearer_auth: []
- description: |
- Records what actually arrived, and whether it can be sold again.
-
- Omitting `items` receives everything as requested and resellable.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: return received
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Return"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- items:
- type: array
- items:
- type: object
- properties:
- return_line_item_id:
- type: string
- quantity:
- type: integer
- resellable:
- type: boolean
- required:
- - return_line_item_id
- - quantity
- "/api/v3/seller/orders/{order_id}/returns/{id}/refund":
- parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Refund a return
- tags:
- - Returns
- security:
- - bearer_auth: []
- description: |
- Gives the customer their money back.
-
- The seller is merchant of record for their own child order, so this is
- theirs to do. The amount is bounded by what the return is owed and, on
- a basket split between sellers, by this order's share of the payment —
- never a sibling's.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: return refunded
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Return"
- '422':
- description: more than the return is owed
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- amount:
- type: string
- nullable: true
- refund_method:
- type: string
- enum:
- - original_payment
- - store_credit
- "/api/v3/seller/orders/{order_id}/returns/{id}/cancel":
- parameters:
- - name: order_id
- in: path
- required: true
- schema:
- type: string
- - name: id
- in: path
- required: true
- schema:
- type: string
- patch:
- summary: Cancel a return
- tags:
- - Returns
- security:
- - bearer_auth: []
- description: Calls the return off.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: return canceled
- content:
- application/json:
- schema:
- "$ref": "#/components/schemas/Return"
- "/api/v3/seller/return_reasons":
- get:
- summary: List return reasons
- tags:
- - Returns
- security:
- - bearer_auth: []
- description: |
- Why goods come back, as the marketplace defines it.
-
- Read-only: the vocabulary is the operator's, and a seller picks from
- it. Retired reasons are left out.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: reasons listed
- content:
- application/json:
- example:
- data:
- - id: rar_UkLWZg9DAJ
- name: Damaged in transit
- active: true
- 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/Reason"
- required:
- - data
- "/api/v3/seller/stock_locations":
- get:
- summary: List stock locations
- tags:
- - Stock Locations
- security:
- - bearer_auth: []
- description: |
- Where this seller keeps stock, and so where their returns are sent.
-
- Rooted in the acting seller, so the marketplace operator's own warehouses
- never appear here.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- 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 (max 100)
- schema:
- type: integer
- - name: sort
- in: query
- required: false
- description: Sort field; prefix with `-` for descending
+ - Returns
+ security:
+ - bearer_auth: []
+ description: |
+ Records what actually arrived, and whether it can be sold again.
+
+ Omitting `items` receives everything as requested and resellable.
+ parameters:
+ - name: X-Spree-Seller-Id
+ in: header
+ required: true
schema:
type: string
responses:
'200':
- description: stock locations listed
+ description: return received
content:
application/json:
example:
- data:
- - id: sloc_UkLWZg9DAJ
- name: Lesha Stroman
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- address2:
- state_name:
- phone: "(202) 456-1111"
- company:
- active: true
- default: false
- kind: warehouse
- returns_enabled: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- meta:
- page: 1
- limit: 25
- count: 1
- pages: 1
- from: 1
- to: 1
- in: 1
- previous:
- next:
+ id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: received
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.0'
+ display_refund_total: "$10.00"
+ approved_at: '2026-01-15T12:00:00Z'
+ received_at: '2026-01-15T12:00:00Z'
+ refunded_at:
+ canceled_at:
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
+ refunded_total: '0.0'
+ refundable_total: '10.0'
+ display_refunded_total: "$0.00"
schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/StockLocation"
- meta:
- "$ref": "#/components/schemas/PaginationMeta"
- required:
- - data
- - meta
- post:
- summary: Create a stock location
+ "$ref": "#/components/schemas/Return"
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ items:
+ type: array
+ items:
+ type: object
+ properties:
+ return_line_item_id:
+ type: string
+ quantity:
+ type: integer
+ resellable:
+ type: boolean
+ required:
+ - return_line_item_id
+ - quantity
+ "/api/v3/seller/orders/{order_id}/returns/{id}/refund":
+ parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: id
+ in: path
+ required: true
+ schema:
+ type: string
+ patch:
+ summary: Refund a return
tags:
- - Stock Locations
+ - Returns
security:
- bearer_auth: []
description: |
- Adds a place this seller ships from.
+ Gives the customer their money back.
- The seller and the store come from the request context whatever the
- payload says.
+ The seller is merchant of record for their own child order, so this is
+ theirs to do. The amount is bounded by what the return is owed and, on
+ a basket split between sellers, by this order's share of the payment —
+ never a sibling's.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -17659,115 +18335,70 @@ paths:
schema:
type: string
responses:
- '201':
- description: stock location created
+ '200':
+ description: return refunded
content:
application/json:
example:
- id: sloc_gbHJdmfrXB
- name: Main warehouse
- address1:
- city: Portland
- zipcode:
- country_code: US
- country_name: United States
- state_code:
- state_text:
- pickup_ready_in_minutes:
- pickup_instructions:
- address2:
- state_name:
- phone:
- company:
- active: true
- default: false
- kind: warehouse
- returns_enabled: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
+ id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: refunded
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.0'
+ display_refund_total: "$10.00"
+ approved_at: '2026-01-15T12:00:00Z'
+ received_at: '2026-01-15T12:00:00Z'
+ refunded_at: '2026-01-15T12:00:00Z'
+ canceled_at:
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
+ refunded_total: '10.0'
+ refundable_total: '0.0'
+ display_refunded_total: "$10.00"
schema:
- "$ref": "#/components/schemas/StockLocation"
+ "$ref": "#/components/schemas/Return"
'422':
- description: validation failed
+ description: more than the return is owed
content:
application/json:
example:
error:
- code: validation_error
- message: Name can't be blank
- details:
- name:
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
+ code: processing_error
+ message: That is more than the amount still refundable.
requestBody:
content:
application/json:
schema:
type: object
properties:
- name:
- type: string
- example: Main warehouse
- company:
- type: string
- nullable: true
- address1:
- type: string
- nullable: true
- example: 1 Kiln Lane
- address2:
- type: string
- nullable: true
- city:
- type: string
- nullable: true
- example: Portland
- zipcode:
- type: string
- nullable: true
- example: '97205'
- country_code:
- type: string
- nullable: true
- example: US
- state_code:
- type: string
- nullable: true
- example: OR
- state_name:
- type: string
- nullable: true
- phone:
+ amount:
type: string
nullable: true
- active:
- type: boolean
- description: Set `false` to retire a location — there is no delete
- default:
- type: boolean
- kind:
+ refund_method:
type: string
- example: warehouse
- required:
- - name
- "/api/v3/seller/stock_locations/{id}":
+ enum:
+ - original_payment
+ - store_credit
+ "/api/v3/seller/orders/{order_id}/returns/{id}/cancel":
parameters:
+ - name: order_id
+ in: path
+ required: true
+ schema:
+ type: string
- name: id
in: path
- description: Stock location ID
required: true
schema:
type: string
- get:
- summary: Get a stock location
+ patch:
+ summary: Cancel a return
tags:
- - Stock Locations
+ - Returns
security:
- bearer_auth: []
- description: |
- A stock location the acting seller owns. An id belonging to another
- seller — or to the marketplace operator — answers `404`.
+ description: Calls the return off.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -17776,55 +18407,40 @@ paths:
type: string
responses:
'200':
- description: stock location returned
- content:
- application/json:
- example:
- id: sloc_UkLWZg9DAJ
- name: Marsha Turner
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- address2:
- state_name:
- phone: "(202) 456-1111"
- company:
- active: true
- default: false
- kind: warehouse
- returns_enabled: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
- schema:
- "$ref": "#/components/schemas/StockLocation"
- '404':
- description: another seller's stock location
+ description: return canceled
content:
application/json:
example:
- error:
- code: record_not_found
- message: Stock location not found
+ id: ret_UkLWZg9DAJ
+ number: RET1001
+ status: canceled
+ order_id: or_UkLWZg9DAJ
+ reason_id:
+ refund_total: '10.0'
+ display_refund_total: "$10.00"
+ approved_at:
+ received_at:
+ refunded_at:
+ canceled_at: '2026-01-15T12:00:00Z'
+ memo:
+ stock_location_id: sloc_UkLWZg9DAJ
+ refunded_total: '0.0'
+ refundable_total: '10.0'
+ display_refunded_total: "$0.00"
schema:
- "$ref": "#/components/schemas/ErrorResponse"
- patch:
- summary: Update a stock location
+ "$ref": "#/components/schemas/Return"
+ "/api/v3/seller/return_reasons":
+ get:
+ summary: List return reasons
tags:
- - Stock Locations
+ - Returns
security:
- bearer_auth: []
description: |
- Edits a stock location the acting seller owns.
+ Why goods come back, as the marketplace defines it.
- There is no delete: a location holds stock levels and is named on
- historical fulfillments, so a seller retires one by setting `active` to
- `false`.
+ Read-only: the vocabulary is the operator's, and a seller picks from
+ it. Retired reasons are left out.
parameters:
- name: X-Spree-Seller-Id
in: header
@@ -17833,64 +18449,33 @@ paths:
type: string
responses:
'200':
- description: stock location updated
+ description: reasons listed
content:
application/json:
example:
- id: sloc_UkLWZg9DAJ
- name: Kiln Lane warehouse
- address1: 1600 Pennsylvania Ave NW
- city: Washington
- zipcode: '20500'
- country_code: US
- country_name: United States
- state_code: AL
- state_text: AL
- pickup_ready_in_minutes:
- pickup_instructions:
- address2:
- state_name:
- phone: "(202) 456-1111"
- company:
- active: true
- default: false
- kind: warehouse
- returns_enabled: true
- created_at: '2026-01-15T12:00:00.000Z'
- updated_at: '2026-01-15T12:00:00.000Z'
+ data:
+ - id: rar_UkLWZg9DAJ
+ name: Damaged in transit
+ active: true
+ meta:
+ page: 1
+ limit: 25
+ count: 1
+ pages: 1
+ from: 1
+ to: 1
+ in: 1
+ previous:
+ next:
schema:
- "$ref": "#/components/schemas/StockLocation"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- name:
- type: string
- example: Main warehouse
- address1:
- type: string
- nullable: true
- city:
- type: string
- nullable: true
- zipcode:
- type: string
- nullable: true
- country_code:
- type: string
- nullable: true
- state_code:
- type: string
- nullable: true
- phone:
- type: string
- nullable: true
- active:
- type: boolean
- default:
- type: boolean
+ type: object
+ properties:
+ data:
+ type: array
+ items:
+ "$ref": "#/components/schemas/Reason"
+ required:
+ - data
"/api/v3/seller/tax_identifiers":
get:
summary: List tax registrations
@@ -18086,160 +18671,6 @@ paths:
code: tax_id_not_validatable
message: No registry validator is installed for tax identifier kind
'eu_vat'
- "/api/v3/seller/team":
- get:
- summary: List team members
- tags:
- - Team
- security:
- - bearer_auth: []
- description: |
- The people who run this seller.
-
- Rooted at the acting seller throughout, so a seller only ever sees their
- own team. Unpaginated — a seller's team is small by nature.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '200':
- description: team members listed
- content:
- application/json:
- example:
- data:
- - id: adm_UkLWZg9DAJ
- first_name: Bill
- last_name: Towne
- full_name: Bill Towne
- created_at: '2026-01-15T12:00:00.000Z'
- avatar_url:
- schema:
- type: object
- properties:
- data:
- type: array
- items:
- "$ref": "#/components/schemas/TeamMember"
- required:
- - data
- post:
- summary: Invite a team member
- tags:
- - Team
- security:
- - bearer_auth: []
- description: |
- Invites a colleague onto this seller's team. They join when they accept,
- on the same invitation rail — and the same email — the marketplace
- operator's own invitations use.
-
- Hiring is not a lifecycle transition: a trading seller's status is
- untouched by taking someone on.
-
- The role is not a parameter. Every member holds the seller's own seeded
- role, which already carries the whole seller vocabulary.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '201':
- description: invitation sent
- content:
- application/json:
- example:
- id: inv_UkLWZg9DAJ
- created_at: '2026-01-15T12:00:00.000Z'
- expires_at: '2026-01-29T12:00:00.000Z'
- accepted_at:
- status: pending
- acceptance_url: "/accept-invitation/inv_UkLWZg9DAJ?token=3K6BfBtHGFeQgToPE45qUDWE"
- schema:
- "$ref": "#/components/schemas/Invitation"
- '422':
- description: validation failed
- content:
- application/json:
- example:
- error:
- code: validation_error
- message: Email is invalid and Email can't be blank
- details:
- email:
- - is invalid
- - can't be blank
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- requestBody:
- content:
- application/json:
- schema:
- type: object
- properties:
- email:
- type: string
- format: email
- required:
- - email
- "/api/v3/seller/team/{id}":
- parameters:
- - name: id
- in: path
- description: Team member (user) ID
- required: true
- schema:
- type: string
- delete:
- summary: Remove a team member
- tags:
- - Team
- security:
- - bearer_auth: []
- description: |
- Revokes a member's access, removing every role they hold on this seller.
-
- The team can never reach zero: emptying it would leave a seller nobody
- can sign in to, and only the marketplace operator could put someone back.
- The last remaining member is refused with `422`.
- parameters:
- - name: X-Spree-Seller-Id
- in: header
- required: true
- schema:
- type: string
- responses:
- '204':
- description: member removed
- '422':
- description: cannot remove the last remaining member
- content:
- application/json:
- example:
- error:
- code: processing_error
- message: A seller needs at least one team member. Invite someone
- else before removing this one.
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
- '404':
- description: not a member of this seller
- content:
- application/json:
- example:
- error:
- code: record_not_found
- message: Admin user not found
- schema:
- "$ref": "#/components/schemas/ErrorResponse"
"/api/v3/seller/transfers":
get:
summary: List transfers
@@ -20127,6 +20558,17 @@ components:
- sample_row
- mappings
x-typelizer: true
+ InvitationAcceptanceLink:
+ type: object
+ properties:
+ id:
+ type: string
+ acceptance_url:
+ type: string
+ required:
+ - id
+ - acceptance_url
+ x-typelizer: true
Invitation:
type: object
properties:
@@ -20151,8 +20593,6 @@ components:
- type: string
description: The values listed are the built-in ones; extensions may add
more.
- acceptance_url:
- type: string
required:
- id
- email
@@ -20160,7 +20600,6 @@ components:
- expires_at
- accepted_at
- status
- - acceptance_url
x-typelizer: true
Media:
type: object
diff --git a/docs/api-reference/store.yaml b/docs/api-reference/store.yaml
index 90448c6531..7a76d43fa4 100644
--- a/docs/api-reference/store.yaml
+++ b/docs/api-reference/store.yaml
@@ -1615,6 +1615,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
- id: cart_gbHJdmfrXB
@@ -1734,6 +1736,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
meta:
@@ -1885,6 +1889,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -2085,6 +2091,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -2283,6 +2291,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -2611,6 +2621,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -2926,6 +2938,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -3122,6 +3136,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -3321,6 +3337,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -3607,6 +3625,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -3851,6 +3871,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -4084,6 +4106,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -4305,6 +4329,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -4535,6 +4561,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -4688,6 +4716,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -5396,6 +5426,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -5583,6 +5615,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -5890,6 +5924,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -7014,6 +7050,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
meta:
@@ -7336,6 +7374,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
schema:
@@ -8955,6 +8995,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
- es
@@ -8973,6 +9015,9 @@ paths:
country_codes:
- DE
- FR
+ country_isos:
+ - DE
+ - FR
supported_locales:
- de
- en
@@ -9060,6 +9105,9 @@ paths:
country_codes:
- DE
- FR
+ country_isos:
+ - DE
+ - FR
supported_locales:
- de
- en
@@ -9143,6 +9191,9 @@ paths:
country_codes:
- DE
- FR
+ country_isos:
+ - DE
+ - FR
supported_locales:
- de
- en
@@ -10570,9 +10621,11 @@ paths:
- api_key: []
bearer_auth: []
description: |
- Adds a person to the node by email. An email that already belongs to a customer of
- this store becomes a membership immediately (a `cmem_...` id); any other email
- becomes an invitation (a `cinv_...` id) and the invite email goes out.
+ Invites a person to the node by email (a `cinv_...` id) and sends the invite email.
+ This is an invitation even when the email already belongs to a customer: they join
+ by accepting the emailed token, which proves they own the address and agree to join.
+ The response is the same either way, so it does not reveal whether the email has an
+ account.
x-codeSamples:
- lang: javascript
label: Spree SDK
@@ -10584,9 +10637,8 @@ paths:
publishableKey: '<api-key>',
})
- // An existing customer joins immediately (cmem_…); anyone else is emailed an
- // invitation (cinv_…).
- const member = await client.companies.members.create(
+ // Always an emailed invitation (cinv_…), even for an existing customer.
+ const invitation = await client.companies.members.create(
'comp_86Rf07xd4z',
{ customer_email: '[email protected]' },
{ token: '<token>' },
@@ -10604,14 +10656,15 @@ paths:
type: string
responses:
'201':
- description: member added or invitation sent
+ description: invitation sent
content:
application/json:
example:
- id: cmem_gbHJdmfrXB
- company_id: comp_UkLWZg9DAJ
- customer_id: cust_gbHJdmfrXB
+ id: cinv_UkLWZg9DAJ
+ expires_at: '2026-02-14T12:00:00.000Z'
+ company_id: comp_UkLWZg9DAJ
+ status: pending
requestBody:
content:
application/json:
@@ -10936,7 +10989,6 @@ paths:
compare_at_amount:
thumbnail_url:
option_values: []
- digital_links: []
fulfillments:
- id: ful_UkLWZg9DAJ
number: R1001-F1
@@ -11080,6 +11132,8 @@ paths:
default: true
country_codes:
- US
+ country_isos:
+ - US
supported_locales:
- en
meta:
@@ -13668,7 +13722,6 @@ components:
- compare_at_amount
- thumbnail_url
- option_values
- - digital_links
x-typelizer: true
Locale:
type: object
@@ -13706,6 +13759,10 @@ components:
type: array
items:
type: string
+ country_isos:
+ type: array
+ items:
+ type: string
supported_locales:
type: array
items:
@@ -13722,6 +13779,7 @@ components:
- tax_inclusive
- default
- country_codes
+ - country_isos
- supported_locales
x-typelizer: true
MediaEvent:
diff --git a/packages/cli/src/generated/admin-spec.json b/packages/cli/src/generated/admin-spec.json
index 9056e9d726..b1b3e9d489 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."},"sample_data":{"type":"boolean","description":"Load the demo catalog, customers and orders in the background once the admin account exists."}}}}}}}},"/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 products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\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":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\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":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/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 token (`short_text`, `long_text`, `rich_text`, `number`, …). An extension type that has no token is named by its registered class instead."},"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/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\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":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\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":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/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., 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"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"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 / 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"},"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","price_list_prices","purchase_orders"]},"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. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","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}/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}/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[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_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[status_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 `customer_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},"customer_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},"customer_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","price_list_prices","purchase_orders"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"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."},"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."},"shipping_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"}}},"billing_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\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\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":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"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}/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)","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"},"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 shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","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"},"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_levels:` (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_levels":{"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_levels:` (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_levels":{"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/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\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":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\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":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\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":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\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":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\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":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\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":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\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":"claim reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason 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"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\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":"order cancellation reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason 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"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\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":"refund reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason 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"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\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":"return reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason 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"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"return reason deleted"}}}},"/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`).\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`).\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":{"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/store_credits":{"get":{"summary":"List store credits","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every store credit in the current store, across all customers.\nRead-only: issuing, editing and deleting a credit stays nested under\nthe customer that holds it.\n\n`meta.totals` carries the outstanding balance as one row per currency,\nsummed over the same filter this request used — so filtering by a\ncustomer answers that customer's balance and no filter answers the\nstore's liability.\n\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,"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[customer_id_eq]","in":"query","required":false,"description":"Filter by the customer holding the credit","schema":{"type":"string"}},{"name":"q[customer_email_cont]","in":"query","required":false,"description":"Filter by customer email (contains)","schema":{"type":"string"}},{"name":"q[currency_eq]","in":"query","required":false,"description":"Filter by currency","schema":{"type":"string"}},{"name":"q[memo_cont]","in":"query","required":false,"description":"Filter by the free-text reason (contains)","schema":{"type":"string"}},{"name":"q[outstanding]","in":"query","required":false,"description":"True for credits with money left, false for credits already spent","schema":{"type":"boolean"}},{"name":"q[from_gift_card]","in":"query","required":false,"description":"True for credits a gift card redemption created, false for every other origin","schema":{"type":"boolean"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","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":"store credits found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a store credit","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**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":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCredit"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{store_credit_id}/events":{"parameters":[{"name":"store_credit_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List a store credit's ledger","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every movement of the credit's balance, newest first: allocated when\nissued, authorized when a checkout starts against it, captured when\nthat order is paid, and voided or credited back if it is cancelled.\n\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":"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":"events found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/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_levels, 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_levels":{"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_levels, 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_levels":{"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/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\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"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key 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":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"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":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\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":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\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":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\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":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\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":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/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 products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\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":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\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":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"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 members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/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 company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\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"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue back verbatim rather than deriving it from the name.\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"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\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":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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[kind_eq]","in":"query","required":false,"description":"Filter by kind (`box`, `envelope`, `carton`, `pallet`, `container`)","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":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\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":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/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/purchase_orders":{"get":{"summary":"List purchase orders","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock bought from suppliers. A purchase order carries what a purchase\nhas and a stock transfer does not: a supplier, a unit cost per line and\nan expected arrival date.\n\nOrdered units never count toward availability. Nothing here changes\n`count_on_hand` until `receive` runs, because a merchant who has\nordered stock does not have it.\n\nStatuses are `draft`, `ordered`, `partially_received`, `received`, `over_received` and\n`canceled`. Each move between them is its own endpoint, not a `PATCH`\nthat writes `status`.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[supplier_id_eq]` or `q[expected_at_lteq]`. Expand `items`,\n`supplier` and `destination_location`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ordered', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase orders found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts an order. Nothing is on order and nothing touches availability\nuntil the order is marked as ordered and then received.\n\n`currency` defaults to the store's; set it for a foreign-currency\norder. `expected_at` is a calendar date (`yyyy-mm-dd`) — the day the\nsupplier promised means the same day in every timezone.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"purchase order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"supplier belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_id":{"type":"string"},"destination_location_id":{"type":"string"},"currency":{"type":"string","nullable":true},"expected_at":{"type":"string","format":"date","nullable":true},"reference":{"type":"string","nullable":true,"description":"The supplier's own order number"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_ordered":{"type":"integer"},"unit_cost":{"type":"string"}},"required":["variant_id","quantity_ordered"]}},"metadata":{"type":"object","nullable":true}},"required":["supplier_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/purchase_orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"Get a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"purchase order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_ordered":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Place the order with the supplier","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is\nstamped. Availability is still untouched — ordered stock is not stock\nthe merchant has.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"purchase order placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{purchase_order_id}/stock_receipts":{"parameters":[{"name":"purchase_order_id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries booked against an order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the dock counted in, newest first — with its packing-slip reference and what it accepted and refused.\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Book in a delivery","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment purchased goods first count toward availability. Records\none delivery as a stock receipt: what this delivery brought, per line,\nnot a running total — a second delivery adds to the first.\n\n`quantity_accepted` reaches the shelf; `quantity_rejected` is refused\nand recorded with a `rejection_reason` (`damaged`, `wrong_item`,\n`expired` or `other`), never stocked. Omit `items` to book in\neverything still outstanding, intact.\n\nEach `received` stock movement carries the line's `unit_cost` and\nnames the receipt, so a delivery can be reconciled against the ledger.\n\nThe order stays `partially_received` while any line is still owed,\nsettles in `received` once every line has what it expected, and in\n`over_received` once any line has more.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"delivery booked in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"order has not been placed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true,"description":"The supplier's delivery note or packing slip"},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Take an order back to draft","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reopens a placed order for editing. Only while no delivery has been booked against it; `ordered_at` is cleared.\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"order back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Close an order short","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received order whose balance the supplier will not\ndeliver. Nothing moves: what arrived stays on the shelf, the\noutstanding count stays on each line, and the order settles in\n`received` with `closed_short_at` and the `reason` recorded.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"order closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/purchase_orders/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Closes what is still outstanding. Nothing is unwound: a purchase order\nnever moved stock until units were received, and units already received\nstay on the shelf because the merchant has them.\n\nA `reason` is appended to the order's notes.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"purchase order cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{seller_id}/balances":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's balances","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Where one seller stands with the marketplace, one row per currency:\nwhat they have earned (completed transfers, refund reversals\nincluded), what has been paid to them, what is still owed, and\nearnings the payout provider has not yet confirmed.\n\nComputed from the ledger rather than stored, so the rows carry no id.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"balances listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerBalance"}}},"required":["data"]}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/payouts":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Settle a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sweeps everything this seller is owed into a payout — one per currency,\nsince nothing is ever converted between them.\n\nThis is what the `manual` payout interval means: the scheduled sweep\nruns on each seller's own interval and skips anyone set to `manual`,\nleaving the operator to decide when. It also settles any other seller\nearly.\n\nIt records the settlement rather than sending money: the built-in\nprovider waits to be told the bank transfer went out, which is\n`PATCH /api/v3/admin/seller_payouts/{id}/complete`.\n\nAnswers `422` when there is nothing to settle — no payout account,\nnothing unsettled, or a balance below the seller's minimum.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller settled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}}},"required":["data"]}}}},"422":{"description":"nothing to settle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/seller_payouts/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller payout prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a payout paid","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the money reached the seller, which is what debits their\nbalance — a balance is earnings less *completed* settlements.\n\nThis is the step the built-in provider waits for: it files the\nsettlement when the payout is created and expects an operator to say\nthe bank transfer went out. A connected provider marks its own payouts\npaid when its webhook reports the money landed.\n\nSend the provider's own id for the transfer as `reference` when there\nis one. Completing a payout that is already complete answers `200`\nwithout recording it twice, so a redelivered webhook or a double click\nis safe.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"payout completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPayout"}}}},"404":{"description":"payout not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The provider's own id for the settlement, when one made it"}}}}}}}},"/api/v3/admin/stock_levels":{"get":{"summary":"List stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One row per variant per stock location, carrying every figure the\nInventory page shows: `count_on_hand` (on hand), `allocated_count`\n(committed to placed orders), `reserved_count` (held by checkouts in\nprogress), `available_count` (on hand minus committed) and\n`incoming_count` (on its way on an open purchase order or a transfer\nin transit). The variant and location are named flat on the row\n(`variant_name`, `variant_sku`, `stock_location_name`, `thumbnail_url`)\nso a list needs no expansion.\n\nFilter with `q[stock_location_id_eq]`, `q[variant_id_eq]` or\n`q[variant_sku_or_variant_product_name_cont]`.\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,"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[stock_location_id_eq]","in":"query","required":false,"description":"Only levels at this stock location","schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"description":"Only levels for this variant","schema":{"type":"string"}},{"name":"q[variant_sku_or_variant_product_name_cont]","in":"query","required":false,"description":"Only levels whose variant SKU or product name contains this text","schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\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,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\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[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","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 movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement 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 movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_transfers":{"get":{"summary":"List stock transfers","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock moving between two of the merchant's own warehouses.\n\nA transfer is a trip, not an instant. Units leave the source when the\ntransfer is marked in transit and land at the destination when somebody\ncounts them in — in between they are in flight, gone from one shelf and\nnot yet on the other.\n\nStatuses are `draft`, `ready_to_ship`, `in_transit`,\n`partially_received`, `received`, `over_received` and `canceled`. Each move between them\nis its own endpoint, not a `PATCH` that writes `status`.\n\nReceiving from a supplier is a purchase order, not a transfer with a\nmissing source.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[source_location_id_eq]` or `q[number_or_reference_cont]`. Expand\n`items`, `source_location` and `destination_location`.\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[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ready_to_ship', 'in_transit', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Persists a draft — a packing list the merchant can still edit. Nothing\nmoves until the transfer is marked in transit.\n\nA draft may legitimately open empty and gain lines as the merchant\npacks. Both warehouses are required and must belong to the same store.\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 transfer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"warehouse belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"reference":{"type":"string","nullable":true,"description":"The merchant's own label for the trip"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_shipped":{"type":"integer"}},"required":["variant_id","quantity_shipped"]}},"metadata":{"type":"object","nullable":true}},"required":["source_location_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/stock_transfers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**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":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"stock transfer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts only. Past `draft` the transfer describes a box that physically\nexists, so it is cancelled rather than deleted — a 422 says so.\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 transfer deleted"}}}},"/api/v3/admin/stock_transfers/{id}/mark_ready":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a transfer ready to ship","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Freezes the lines so the warehouse and the merchant are looking at the\nsame list. Nothing leaves the shelf yet.\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":"transfer is ready to ship","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_in_transit":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Send a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment stock leaves the source warehouse: `shipped` movements are\nwritten against the source's levels and `shipped_at` is stamped. The\ndestination is deliberately untouched — the units are in flight.\n\nRefused with a 422 when the source does not hold enough. Pass\n`force: true` to record the departure anyway: a merchant forcing it has\ndecided the box left whatever the ledger claims.\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":"transfer is in transit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Ship even if it drives the source below zero"}}}}}}}},"/api/v3/admin/stock_transfers/{stock_transfer_id}/stock_receipts":{"parameters":[{"name":"stock_transfer_id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries counted in against a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the destination counted in, with what it accepted and refused.\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"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Count a delivery in","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records one delivery the destination warehouse counted in, as a stock\nreceipt. Partial receipt is the normal case: ten left, eight arrived,\ntwo were crushed in transit. Quantities are this delivery's counts —\na second box adds to the first rather than restating it.\n\n`quantity_accepted` lands on the destination's shelf;\n`quantity_rejected` is refused and recorded with a `rejection_reason`\n(`damaged`, `wrong_item`, `expired` or `other`), never stocked. A\nrefused unit still arrived, so it counts toward the trip being over.\nOmit `items` to count in everything still outstanding, intact.\n\nThe transfer stays `partially_received` while units are still on the\nroad, settles in `received` once everything has arrived, and in\n`over_received` once more arrived than was shipped.\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":"delivery counted in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"transfer has not shipped yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Take a transfer back to draft","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unfreezes a ready-to-ship transfer so its lines can be changed. Nothing has left the source, so nothing is undone.\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":"transfer back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Close a transfer short","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received transfer whose missing units are not going\nto turn up. Nothing moves — they already left the source — and the\ntransfer settles in `received` with `closed_short_at` and the\n`reason` recorded, the outstanding count left on each line.\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":"transfer closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/stock_transfers/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Calls the trip off.\n\nCancelling a draft or a packed transfer costs nothing — no stock has\nmoved. Cancelling one already in transit needs `on_in_transit`, because\nthe units are physically gone from the source: either they come back\n(`restock`, as if the transfer had never shipped) or they are written\noff as lost (`write_off`). There is no default — guessing would either\ninvent stock or destroy it — so an in-flight cancellation without it is\nrefused with a 422.\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":"transfer cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"422":{"description":"in-transit cancellation needs a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"on_in_transit":{"type":"string","enum":["restock","write_off"],"description":"Required once the units have left the source"},"reason":{"type":"string","nullable":true,"description":"Recorded against the written-off lines"}}}}}}}},"/api/v3/admin/suppliers":{"get":{"summary":"List suppliers","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Who the merchant buys stock from. A supplier is an address-book entry\nwith a purchasing history — not a party that sells on the store, which\nis a seller.\n\nSuppliers belong to one store, and are soft-deleted so the purchase\norders that name them stay readable.\n\nFilter with Ransack predicates such as\n`q[name_or_contact_name_or_email_cont]` or `q[country_code_eq]`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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_or_contact_name_or_email_cont]","in":"query","required":false,"description":"Search by name, contact name or email","schema":{"type":"string"}}],"responses":{"200":{"description":"suppliers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a supplier to this store's address book. The address is inline —\nstreet, city, state and country live on the supplier itself, the same\nshape a stock location uses.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"required":["name"]}}},"required":true}}},"/api/v3/admin/suppliers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Supplier ID","schema":{"type":"string"}}],"get":{"summary":"Get a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"404":{"description":"supplier not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}}}},"required":true}},"delete":{"summary":"Delete a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the supplier, so the purchase orders naming it stay\nreadable. Refused with a 422 while a purchase order still points at it.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier deleted"}}}}},"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"]},"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"]},"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"]},"Actor":{"type":"object","properties":{"id":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"label":{"type":"string","nullable":true}},"required":["id","type","label"],"x-typelizer":true},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"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},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","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","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"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","enum":["publishable","secret"]},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by_label":{"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","created_by_type","created_by_label"],"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},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"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"}},"order_minimum":{"type":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"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","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","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","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string","enum":["explicit","automatic","base"]},"break_count":{"type":"number"},"amount":{"type":"string"},"display_amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","display_amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"display_amount":{"type":"string"},"amount":{"type":"string"}},"required":["min_quantity","display_amount","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"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"}},"external_references":{"type":"object"},"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","external_references","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"}},"default_catalog_id":{"type":"string","nullable":true}},"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","default_catalog_id"],"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":{"anyOf":[{"type":"string","enum":["open","approved","resolved","denied","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"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","created_by_type"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["is_equal_to","is_not_equal_to","contains","does_not_contain"]},"type":{"type":"string","description":"Rule type. Built-in: tag, available_on, sale. Extensions may register more."}},"required":["id","value","match_policy","type"],"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","enum":["all","any"]},"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","enum":["percentage","fixed"]},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string","enum":["percentage","fixed"]},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more."},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"object","nullable":true},"seller_ids":{"type":"object","nullable":true},"category_ids":{"type":"object","nullable":true},"sellers":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","product_ids","seller_ids","category_ids"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"]},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string","enum":["checkout","registration","account","admin","newsletter","anonymization","unknown","import","storefront"]},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"object"}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"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","description":"Class name of the resource the field attaches to, for example Spree::Product, Spree::Order or Spree::Customer. Extensions may register more."},"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"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"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"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"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"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","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},"DashboardCounter":{"type":"object","properties":{"key":{"type":"string","description":"Registered counter name. The dashboard translates it; built-in: orders_to_fulfill, payments_to_collect, open_returns, open_exchanges, open_claims, low_stock_items, out_of_stock_items."},"value":{"type":"number"},"link":{"type":"object","nullable":true,"description":"The list filter that shows exactly the rows counted, or null when no list can."},"nav":{"type":"string","nullable":true,"description":"Sidebar entry key this count badges, or null."}},"required":["key","value","link","nav"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string","enum":["access","erasure"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more."},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","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},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"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","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","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","description":"Profile kind. Built-in: shipping, digital. Extensions may register more."},"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},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"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","unpriced","freight_summary","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","pre_transit","in_transit","out_for_delivery","available_for_pickup","delivered","return_to_sender","failure","unknown"]},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"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},"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},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string","description":"Digital asset provider name. Built-in: File. Extensions may register more."},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_type","provider_settings","created_at","updated_at","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"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"},"expires_at":{"type":"string","nullable":true},"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","expires_at","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","enum":["promotion","manual"]},"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":{"anyOf":[{"type":"string","enum":["requested","approved","received","fulfilled","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"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","created_by_type"],"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"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"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","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"anyOf":[{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"]},{"type":"string"}],"description":"What sort of charge this is. `duty` is a customs duty on a cross-border order and is not taxed; the other kinds are. Extensions may register further kinds."},"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},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["on_hand","backordered","shipped","returned"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"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":{"anyOf":[{"type":"string","enum":["unfulfilled","fulfilled","delivered","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"fulfilled_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"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"},"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"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"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","pickup_point_data","selected_delivery_rate_id","unpriced","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","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","labels","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":{"anyOf":[{"type":"string","enum":["active","partially_redeemed","redeemed","canceled","expired"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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,"description":"Import type. Built-in: products, product_translations, customers, price_list_prices. Extensions may register more."},"status":{"anyOf":[{"type":"string","enum":["pending","mapping","completed_mapping","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"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"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"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","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","price_list_id","seller_name","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","description":"Integration type, registered by the provider gem that owns it (for example the EasyPost provider). Core ships none."},"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":{"anyOf":[{"type":"string","enum":["pending","accepted"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"type":"string"},"acceptance_url":{"type":"string"},"invitee_exists":{"type":"boolean"},"store":{"type":"object"}},"required":["id","email","status","created_at","updated_at","expires_at","role_id","role_name","inviter_email","acceptance_url","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","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","enum":["image","video","external_video"]},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"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","enum":["dropdown","color_swatch","buttons"]},"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},"OrderCancellationReason":{"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},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","created_at","updated_at","payments"],"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","description":"Rule type. Built-in: preferred_location, default_location, minimize_splits. Extensions may register more."},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"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,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"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},"external_references":{"type":"object"},"status":{"type":"string","enum":["draft","placed","canceled"]},"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"},"cancel_note":{"type":"string","nullable":true},"commission_amount_total":{"type":"string"},"display_commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"display_commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"display_commission_total":{"type":"string"},"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},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_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},"approver_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"approver":{"$ref":"#/components/schemas/Actor"},"canceler_id":{"type":"string","nullable":true},"canceler_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"canceler":{"$ref":"#/components/schemas/Actor"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}},"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"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","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","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","commission_amount_total","display_commission_amount_total","commission_tax_total","display_commission_tax_total","commission_total","display_commission_total","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","approver_type","canceler_id","canceler_type","created_by_id","created_by_type","cancel_reason_id","cancel_reason_name","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"volume":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume","seller_id","seller_name"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","description":"Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe."},"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"},"status":{"anyOf":[{"type":"string","enum":["checkout","processing","pending","completed","failed","void","invalid"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"amount":{"type":"string"},"display_amount":{"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"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","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},"PaymentSplit":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"authorized_amount":{"type":"string"},"display_authorized_amount":{"type":"string"},"captured_amount":{"type":"string"},"display_captured_amount":{"type":"string"},"refunded_amount":{"type":"string"},"display_refunded_amount":{"type":"string"},"claimed_amount":{"type":"string"},"display_claimed_amount":{"type":"string"},"net_captured_amount":{"type":"string"},"display_net_captured_amount":{"type":"string"},"refundable_amount":{"type":"string"},"display_refundable_amount":{"type":"string"},"payment_id":{"type":"string"},"payment_number":{"type":"string","nullable":true},"order_id":{"type":"string"},"order_number":{"type":"string","nullable":true}},"required":["id","currency","created_at","updated_at","authorized_amount","display_authorized_amount","captured_amount","display_captured_amount","refunded_amount","display_refunded_amount","claimed_amount","display_claimed_amount","net_captured_amount","display_net_captured_amount","refundable_amount","display_refundable_amount","payment_id","payment_number","order_id","order_number"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"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},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"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},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["draft","active","inactive","scheduled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"position":{"type":"number"},"match_policy":{"type":"string","enum":["all","any"]},"adjust_compare_at":{"type":"boolean"},"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"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: channel_rule, customer_group_rule, market_rule, user_rule, volume_rule, zone_rule. Extensions may register more."},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"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"],"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},"min_quantity":{"type":"number"},"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","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"anyOf":[{"type":"string","enum":["draft","active","archived","proposed","rejected"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","withdrawn"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"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","description":"Action type. Built-in: create_adjustment, create_item_adjustments, create_line_items, free_shipping. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"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","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: currency, country, channel, market, item_total, product, customer, customer_group, first_order, customer_logged_in, one_use_per_user, category, option_value. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"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},"option_value_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"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","product_ids","category_ids","customer_ids","option_value_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},"PurchaseOrderItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_ordered":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"currency":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"unit_cost":{"type":"string"},"total_cost":{"type":"string"},"display_unit_cost":{"type":"string"},"display_total_cost":{"type":"string"},"purchase_order_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_ordered","quantity_received","quantity_rejected","quantity_over","outstanding","currency","created_at","updated_at","unit_cost","total_cost","display_unit_cost","display_total_cost","purchase_order_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"PurchaseOrder":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"ordered_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expected_at":{"type":"string","nullable":true},"cancel_by":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_ordered_total":{"type":"number"},"editable":{"type":"boolean"},"subtotal":{"type":"string"},"display_subtotal":{"type":"string"},"supplier_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"supplier":{"$ref":"#/components/schemas/Supplier"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","currency","reference","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","ordered_at","received_at","closed_short_at","created_at","updated_at","expected_at","cancel_by","closed_short","quantity_ordered_total","editable","subtotal","display_subtotal","supplier_id","destination_location_id"],"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"},"refunder_id":{"type":"string","nullable":true},"refunder_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"refunder":{"$ref":"#/components/schemas/Actor"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at","refunder_id","refunder_type"],"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":{"anyOf":[{"type":"string","enum":["requested","approved","received","refunded","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"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"}},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"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","created_by_type","refunded_total","refundable_total","documents","labels","deliveries"],"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},"SavedReport":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"query":{"type":"object"},"seeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"author_name":{"type":"string","nullable":true}},"required":["id","name","description","query","seeded","created_at","updated_at","user_id","author_name"],"x-typelizer":true},"SellerBalance":{"type":"object","properties":{"currency":{"type":"string"},"settlement_currency":{"type":"string"},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"earned":{"type":"string"},"display_earned":{"type":"string"},"payable":{"type":"string"},"display_payable":{"type":"string"},"paid":{"type":"string"},"display_paid":{"type":"string"},"balance":{"type":"string"},"display_balance":{"type":"string"},"pending":{"type":"string"},"display_pending":{"type":"string"}},"required":["currency","settlement_currency","converted","seller_id","earned","display_earned","payable","display_payable","paid","display_paid","balance","display_balance","pending","display_pending"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"provider":{"type":"string","description":"Payout provider class name. Built-in: Spree::PayoutProvider::System. Provider gems register more."},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string","enum":["complete","incomplete","pending","rejected"]},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted","rejected","waived"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["pending","invited","canceled","onboarding","ready_for_review","approved","rejected","suspended"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"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","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"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},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["earning","refund_reversal"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"provider":{"type":"string","description":"Payout provider class name. Built-in: Spree::PayoutProvider::System. Provider gems register more."},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"settled_amount":{"type":"string","nullable":true},"settled_currency":{"type":"string","nullable":true},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","settled_amount","settled_currency","converted","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["purchased","uploaded"]},"status":{"anyOf":[{"type":"string","enum":["purchased","refund_requested","refunded"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string","enum":["Spree::Fulfillment","Spree::Return"]},"cost":{"type":"string"},"display_cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","display_cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"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},"external_references":{"type":"object"},"metadata":{"type":"object"},"reserved_count":{"type":"number"},"incoming_count":{"type":"number"},"purchasable_count":{"type":"number"},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_name":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"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","external_references","metadata","reserved_count","incoming_count","purchasable_count","variant_name","variant_sku","created_at","updated_at","stock_location_name","product_id","options_text","thumbnail_url","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},"external_references":{"type":"object"},"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":{"anyOf":[{"type":"string","enum":["warehouse","store","fulfillment_center"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true,"enum":["received","allocated","shipped","released","adjusted"]},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"stock_location_name":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true},"stock_receipt_id":{"type":"string","nullable":true},"purchase_order_id":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"return_number":{"type":"string","nullable":true},"exchange_number":{"type":"string","nullable":true},"stock_transfer_number":{"type":"string","nullable":true},"purchase_order_number":{"type":"string","nullable":true},"unit_cost":{"type":"string","nullable":true},"display_unit_cost":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","stock_location_id","stock_location_name","variant_id","variant_name","variant_sku","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id","stock_receipt_id","purchase_order_id","order_number","return_number","exchange_number","stock_transfer_number","purchase_order_number","unit_cost","display_unit_cost"],"x-typelizer":true},"StockReceiptItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"number"},"quantity_rejected":{"type":"number"},"rejection_reason":{"type":"string","nullable":true,"enum":["damaged","wrong_item","expired","other"]},"notes":{"type":"string","nullable":true},"line_type":{"type":"string","enum":["purchase_order_item","stock_transfer_item"]},"line_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_accepted","quantity_rejected","rejection_reason","notes","line_type","line_id","variant_id","product_id","variant_name","variant_sku","thumbnail_url"],"x-typelizer":true},"StockReceipt":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"quantity_accepted_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"received_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"receivable_type":{"type":"string","enum":["purchase_order","stock_transfer"]},"receivable_id":{"type":"string"},"received_by_id":{"type":"string","nullable":true},"received_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"received_by":{"$ref":"#/components/schemas/Actor"},"items_count":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockReceiptItem"}}},"required":["id","number","reference","notes","metadata","quantity_accepted_total","quantity_rejected_total","received_at","created_at","updated_at","receivable_type","receivable_id","received_by_id","received_by_type","items_count"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_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_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransferItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_shipped":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_transfer_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_shipped","quantity_received","quantity_rejected","quantity_over","outstanding","created_at","updated_at","stock_transfer_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"shipped_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_shipped_total":{"type":"number"},"editable":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","created_at","updated_at","source_location_id","destination_location_id","status","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","shipped_at","received_at","closed_short_at","deleted_at","closed_short","quantity_shipped_total","editable"],"x-typelizer":true},"StoreCreditEvent":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"authorization_code":{"type":"string","nullable":true},"display_action":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"store_credit_id":{"type":"string"},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true}},"required":["id","action","authorization_code","display_action","amount","display_amount","created_at","updated_at","store_credit_id","originator_type","originator_id"],"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"},"amount_authorized":{"type":"string"},"outstanding":{"type":"boolean"},"display_amount_authorized":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","amount_authorized","outstanding","display_amount_authorized","customer_id","created_by_id","originator_type","originator_id"],"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"},"default_country_code":{"type":"string","nullable":true},"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","enum":["g","kg","lb","oz"]},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_always_include_confirm_step":{"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_low_stock_threshold":{"type":"number"},"preferred_tax_using_ship_address":{"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_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_auto_approve_sellers":{"type":"boolean"},"preferred_auto_approve_seller_products":{"type":"boolean"},"preferred_send_seller_transactional_emails":{"type":"boolean"},"preferred_default_commission_tax_rate":{"type":"number"},"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"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"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","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_always_include_confirm_step","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_low_stock_threshold","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_auto_approve_sellers","preferred_auto_approve_seller_products","preferred_send_seller_transactional_emails","preferred_default_commission_tax_rate","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","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},"Supplier":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"purchase_orders_count":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"can_be_deleted":{"type":"boolean"}},"required":["id","name","contact_name","email","phone","notes","address1","address2","city","state_name","state_code","country_code","postal_code","purchase_orders_count","metadata","created_at","updated_at","deleted_at","can_be_deleted"],"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":{"anyOf":[{"type":"string","enum":["pending","verified","expired","revoked"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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","description":"Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more."},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true,"enum":["pending","verified","unverified","unavailable","unsupported"]},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true,"enum":["override","company","customer"]},"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},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true,"enum":["unit","carton"]},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"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},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"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","weight_unit","dimensions_unit","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","preorderable","tax_category_id","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object"},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","created_at","updated_at","delivered_at","payload","webhook_endpoint_id","webhook_endpoint_url"],"x-typelizer":true},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"url":{"type":"string"},"active":{"type":"boolean"},"subscriptions":{"type":"array","items":{"type":"string"}},"disabled_reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"disabled_at":{"type":"string","nullable":true},"secret_key":{"type":"string","nullable":true},"last_delivery_at":{"type":"string","nullable":true},"recent_delivery_count":{"type":"number"},"recent_failure_count":{"type":"number"},"total_delivery_count":{"type":"number"},"successful_delivery_count":{"type":"number"},"failed_delivery_count":{"type":"number"}},"required":["id","name","url","active","subscriptions","disabled_reason","created_at","updated_at","disabled_at","secret_key","last_delivery_at","recent_delivery_count","recent_failure_count","total_delivery_count","successful_delivery_count","failed_delivery_count"],"x-typelizer":true}}}}
\ No newline at end of file
+{"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 is honoured only on the\ndashboard's origin and for an account that is staff of the store —\notherwise it is silently ignored and the link opens the dashboard's\nreset page. 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."},"sample_data":{"type":"boolean","description":"Load the demo catalog, customers and orders in the background once the admin account exists."}}}}}}}},"/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 products to a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Classifies products under the category in bulk (appended to the end). Already-classified products are skipped; the count reports what was added.\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":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a category","tags":["Categories"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the category's manual classification in bulk. Ids that are not classified are ignored; the count reports what was removed.\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":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/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 token (`short_text`, `long_text`, `rich_text`, `number`, …). An extension type that has no token is named by its registered class instead."},"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/{id}/export":{"get":{"summary":"Export a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns everything the store holds about this customer, for answering a\nGDPR right-of-access request (Art. 15) that reached the merchant\ndirectly.\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":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer data","content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object"},"marketing_consent":{"type":"object"},"consent_records":{"type":"array","items":{"type":"object"}},"addresses":{"type":"array","items":{"type":"object"}},"orders":{"type":"array","items":{"type":"object"}},"exported_at":{"type":"string"}}}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/customers/{id}/anonymize":{"post":{"summary":"Erase a customer's personal data","tags":["Customers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Carries out a GDPR right-to-erasure request (Art. 17). Personal data is\nreplaced across the account, its addresses, the address snapshots on\npast orders, saved cards, connected identities and live sessions.\n\nOrders, payments and tax records are kept — they carry their own\nretention obligation — with the personal details removed. The country,\nstate and a truncated postal code survive on order addresses so the tax\njurisdiction of a past sale stays provable.\n\nIrreversible.\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":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"customer anonymized","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"anonymized":{"type":"boolean"},"anonymized_at":{"type":"string","nullable":true}}}}}}}}},"/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., 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"],"properties":{"amount":{"type":"string"},"currency":{"type":"string"},"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 / 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"},"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","price_list_prices","purchase_orders"]},"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. A `price_list_prices` export requires `price_list_id_eq` naming a price list of the current store, and refuses `record_selection: \"all\"`.","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}/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}/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[customer_id_eq]` for cards issued\nto a specific customer, or `q[status_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[status_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 `customer_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},"customer_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},"customer_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","price_list_prices","purchase_orders"]},"price_list_id":{"type":"string","description":"For `price_list_prices` imports: the price list the rows are merged into. Must belong to the current store."},"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."},"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."},"shipping_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"}}},"billing_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\nOn a marketplace, an order holding several sellers' goods becomes one\norder per seller, and the response is the order group they belong to\nwith those orders nested inside it.\n\n\n**Required scope:** `write_orders` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Order ID","schema":{"type":"string"}}],"responses":{"200":{"description":"order completed","content":{"application/json":{}}},"422":{"description":"order cannot be completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"notify_customer":{"type":"boolean","description":"Send the order confirmation email after completion."}}}}}}}},"/api/v3/admin/orders/{id}/cancel":{"patch":{"summary":"Cancel an order","tags":["Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Cancels a completed order.\n\n`cancel_reason_id` records why, from the store's own cancellation-reason\nvocabulary (`/admin/order_cancellation_reasons`), and `cancel_note` is a\nstaff-facing note; both are shown on the order afterwards.\n\nStock is always released — the goods are not going out either way — and\nevery payment is settled at the gateway, which releases an\nauthorization it never drew on and refunds a charge it cannot release.\n\n`refund_payments` and `refund_amount` govern the shared payment of a\nsplit checkout, where one payment covers several orders: they decide\nwhether this order's share comes back, and how much of it. A\n`refund_amount` on an ordinary order is refused with a 422.\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":{"cancel_reason_id":{"type":"string","description":"Why the order was canceled — the id of one of the store's cancellation reasons."},"cancel_note":{"type":"string","description":"Staff-facing note about the cancellation."},"refund_payments":{"type":"boolean","default":false,"description":"Whether this order's share of a payment shared across a split checkout is handed back."},"refund_amount":{"type":"string","description":"How much of that share to return. Defaults to all of it; refused on an order whose payment is not shared."},"notify_customer":{"type":"boolean","default":false,"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}/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)","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"},"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 shape: ship the exact per-variant prices the list should contain. Each row upserts on the unique key `(variant_id, currency, price_list_id)` — `prices` alone tells the server which variants belong to the list and what the override amount is. Curating whole products goes through the nested `/price_lists/{id}/products` surface instead.","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"},"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_levels:` (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_levels":{"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_levels:` (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_levels":{"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/translations":{"get":{"summary":"Translation coverage for a resource type","tags":["Products"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reports how much of each record is translated into each of the store's non-default locales, plus per-locale totals. A record counts as covered for a locale only when every one of its translatable fields is filled in.\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":"resource_type","in":"query","required":true,"description":"A translatable resource type, e.g. `product`, `category`, `option_type`.","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"search","in":"query","required":false,"description":"Free-text term, applied through whichever predicate the resource type whitelists (reported back as `search_field`).","schema":{"type":"string"}}],"responses":{"200":{"description":"coverage found","content":{"application/json":{}}},"404":{"description":"resource type is not translatable","content":{"application/json":{}}}}}},"/api/v3/admin/policies":{"get":{"summary":"List policies","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's policy documents — terms of service, privacy\npolicy, returns policy, shipping policy, and any others the merchant\nhas written. Every store is created with the four standard policies,\nnamed but empty.\n\nA marketplace seller's own policies are managed by the seller and are\nnot listed here.\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":"fields","in":"query","required":false,"description":"Comma-separated list of fields to include. id is always included.","schema":{"type":"string"}}],"responses":{"200":{"description":"policies listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Policy"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a policy. `body` accepts HTML and is sanitized before it is\nstored; the stored markup is returned as `body_html`, and `body` reads\nback as plain text.\n\nThe slug is derived from the name when one is not given, and is what\nthe storefront addresses the policy by.\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":"policy created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}},"required":["name"]}}}}}},"/api/v3/admin/policies/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Policy prefixed ID or slug","schema":{"type":"string"}}],"get":{"summary":"Get a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single policy, addressed by prefixed ID or by slug.\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":"policy found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}},"404":{"description":"policy not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a policy. `body` accepts HTML and is sanitized before it is stored.\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":"policy updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Policy"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string"}}}}}}},"delete":{"summary":"Delete a policy","tags":["Policies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Deletes a policy. The four policies a store is created with can be\ndeleted like any other — they are conventions, not fixtures.\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":"policy deleted"}}}},"/api/v3/admin/claim_reasons":{"get":{"summary":"List claim reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer raised a claim — what the merchant got wrong, rather than a change of mind.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"claim reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a claim reason to this store. Names are unique per store, ignoring case.\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":"claim reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/claim_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Claim reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single claim reason 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"}}],"responses":{"200":{"description":"claim reason found","content":{"application/json":{}}},"404":{"description":"claim reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a claim reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"claim reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a claim reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a claim reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"claim reason deleted"}}}},"/api/v3/admin/order_cancellation_reasons":{"get":{"summary":"List order cancellation reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why an order was called off before it shipped. Staff pick one when canceling.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"order cancellation reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a order cancellation reason to this store. Names are unique per store, ignoring case.\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":"order cancellation reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/order_cancellation_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Order cancellation reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single order cancellation reason 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"}}],"responses":{"200":{"description":"order cancellation reason found","content":{"application/json":{}}},"404":{"description":"order cancellation reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a order cancellation reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"order cancellation reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a order cancellation reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a order cancellation reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"order cancellation reason deleted"}}}},"/api/v3/admin/refund_reasons":{"get":{"summary":"List refund reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why money went back. Some rows are seeded and looked up by name, so they refuse renaming and deletion.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"refund reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a refund reason to this store. Names are unique per store, ignoring case.\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":"refund reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/refund_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Refund reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single refund reason 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"}}],"responses":{"200":{"description":"refund reason found","content":{"application/json":{}}},"404":{"description":"refund reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a refund reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"refund reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a refund reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a refund reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"refund reason deleted"}}}},"/api/v3/admin/return_reasons":{"get":{"summary":"List return reasons","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Why a customer is sending items back. Shared by returns and exchanges.\n\nThe vocabulary is the merchant's own — seeded with a starting set and\nedited from the dashboard. Inactive rows stay for the records that\nalready reference them, but are not offered on new ones.\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[active_eq]","in":"query","required":false,"description":"Filter by active 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"}}],"responses":{"200":{"description":"return reasons found","content":{"application/json":{}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a return reason to this store. Names are unique per store, ignoring case.\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":"return reason created","content":{"application/json":{}}},"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"},"active":{"type":"boolean","description":"Inactive reasons are hidden from the pickers on new records."}}}}}}}},"/api/v3/admin/return_reasons/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Return reason ID","schema":{"type":"string"}}],"get":{"summary":"Get a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single return reason 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"}}],"responses":{"200":{"description":"return reason found","content":{"application/json":{}}},"404":{"description":"return reason not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Renames a return reason or retires it. Deactivating keeps it on the records\nthat already carry it while removing it from the pickers.\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":{"200":{"description":"return reason updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a return reason","tags":["Reasons"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a return reason the store no longer uses. A reason already recorded\non a document is refused — deactivate it instead, so the history it\nexplains stays readable.\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":"return reason deleted"}}}},"/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`).\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`).\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":{"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. Removing a role needs the same rights as granting it, and the store always keeps at least one admin.\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/{invitation_id}/acceptance_link":{"get":{"summary":"Get an invitation acceptance link","tags":["Staff"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the link the invitee opens to accept a pending invitation. The link carries the invitation token, so it needs write access to staff and the right to grant the invitation's role; invitation listings never include it.\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":"invitation_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"acceptance link found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationAcceptanceLink"}}}}}}},"/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/store_credits":{"get":{"summary":"List store credits","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every store credit in the current store, across all customers.\nRead-only: issuing, editing and deleting a credit stays nested under\nthe customer that holds it.\n\n`meta.totals` carries the outstanding balance as one row per currency,\nsummed over the same filter this request used — so filtering by a\ncustomer answers that customer's balance and no filter answers the\nstore's liability.\n\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,"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[customer_id_eq]","in":"query","required":false,"description":"Filter by the customer holding the credit","schema":{"type":"string"}},{"name":"q[customer_email_cont]","in":"query","required":false,"description":"Filter by customer email (contains)","schema":{"type":"string"}},{"name":"q[currency_eq]","in":"query","required":false,"description":"Filter by currency","schema":{"type":"string"}},{"name":"q[memo_cont]","in":"query","required":false,"description":"Filter by the free-text reason (contains)","schema":{"type":"string"}},{"name":"q[outstanding]","in":"query","required":false,"description":"True for credits with money left, false for credits already spent","schema":{"type":"boolean"}},{"name":"q[from_gift_card]","in":"query","required":false,"description":"True for credits a gift card redemption created, false for every other origin","schema":{"type":"boolean"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","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":"store credits found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCredit"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Retrieve a store credit","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**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":"expand","in":"query","required":false,"description":"Comma-separated associations to expand (customer, created_by).","schema":{"type":"string"}}],"responses":{"200":{"description":"store credit found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreCredit"}}}},"404":{"description":"not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/store_credits/{store_credit_id}/events":{"parameters":[{"name":"store_credit_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"List a store credit's ledger","tags":["Store Credits"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every movement of the credit's balance, newest first: allocated when\nissued, authorized when a checkout starts against it, captured when\nthat order is paid, and voided or credited back if it is cancelled.\n\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":"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":"events found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StoreCreditEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/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_levels, 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_levels":{"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_levels, 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_levels":{"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/catalogs":{"get":{"summary":"List catalogs","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store catalogs — product assortments with an optional price list, shown to audiences through assignments.\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"}}],"responses":{"200":{"description":"catalogs found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a catalog. Add products and assign audiences (customer group, or company subtree) afterwards.\n\n**Required scope:** `write_products` (for API-key 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":"catalog created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"active":{"type":"boolean"},"price_list":{"type":"object","nullable":true,"description":"The price list this catalog owns, written inline. Omit for assortment-only (base prices); send null to remove the pricing, which deletes the list. A catalog with an empty assortment prices without restricting visibility; import or curate products to make it restrictive.","properties":{"price_adjustment_percentage":{"type":"string","nullable":true},"adjust_compare_at":{"type":"boolean"}}}},"required":["name"]}}}}}},"/api/v3/admin/catalogs/{id}/assign":{"post":{"summary":"Assign a catalog to an audience","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Shows the catalog to an audience. A company assignment covers the node and its whole subtree.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"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":{"201":{"description":"catalog assigned","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"assignable_type":{"type":"string","enum":["customer_group","company"]},"assignable_id":{"type":"string"}},"required":["assignable_type","assignable_id"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/products":{"get":{"summary":"List catalog products","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The catalog's curated assortment, listed by product name — membership\ncarries no order.\n\n`expand=catalog_price` adds what a buyer on this agreement pays for\neach row and where the amount comes from: `explicit` (an amount\nentered on the catalog's own price list), `automatic` (that list's\npercentage applied to the shop price) or `base` (the shop price\nitself — this agreement does not price the product).\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":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `catalog_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the agreement charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CatalogProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the assortment in bulk. Already-present products are skipped; the count reports what was added.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the assortment in bulk. Ids that are not members are ignored; the count reports what was removed.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums":{"get":{"summary":"List catalog order minimums","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The least a whole order must come to under this agreement. One row per currency — Spree holds no exchange rates, so a threshold is never stated once and converted.\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":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimums found","content":{"application/json":{}}}}},"post":{"summary":"Create a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Requires orders in one currency to reach an amount. The buyer sees the shortfall on the cart while they can still act on it; completion is refused below it.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"order minimum created","content":{"application/json":{}}},"422":{"description":"invalid request","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"string"}},"required":["currency","amount"]}}}}}},"/api/v3/admin/catalogs/{catalog_id}/order_minimums/{id}":{"patch":{"summary":"Update a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Restates one currency's threshold.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"order minimum updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"string"}}}}}}},"delete":{"summary":"Delete a catalog order minimum","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lifts the threshold for one currency, so orders in it may come to any total.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"order minimum deleted"}}}},"/api/v3/admin/catalogs/{catalog_id}/quantity_rules":{"put":{"summary":"Set catalog quantity rules","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Writes the given products' quantity terms in one request, keyed by prefixed product id. The stated pair is written to every variant of the product, which is the grain the database keeps them at. Both fields null clears that product's terms; a product not yet in the assortment is added, since a term with nothing to apply to is not a reachable state. Products absent from the payload are left alone — an agreement may name terms for thousands of SKUs. Read them back on the assortment rows: `GET /catalogs/{id}/products?expand=quantity_rule`.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"catalog_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"quantity rules set"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"terms":{"type":"object","additionalProperties":{"type":"object","properties":{"minimum_order_quantity":{"type":"integer","nullable":true},"order_multiple":{"type":"integer","nullable":true}}}}},"required":["terms"]}}}}}},"/api/v3/admin/catalogs/{id}/activate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Activate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts the agreement into effect: its audience starts seeing its\nassortment and paying its prices. Refused for a catalog nobody is\nassigned to, since activating it would reach no buyer — a channel's\ndefault catalog is reached through the channel instead, so it needs\nno assignment.\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":"catalog activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/api/v3/admin/catalogs/{id}/deactivate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Deactivate a catalog","tags":["Catalogs"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Takes the agreement out of effect. Everything it holds — assignments,\ncommercial terms, its price list — survives, so activating again\nresumes exactly what was there.\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":"catalog deactivated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Catalog"}}}}}}},"/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 products to a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Curates products into the collection in bulk (appended to the end). Already-curated products are skipped; the count reports what was added.\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":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a collection","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the collection's manual curation in bulk. Ids that are not curated are ignored; the count reports what was removed.\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":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/api/v3/admin/collections/{collection_id}/products/{id}/reposition":{"patch":{"summary":"Reposition a collection product","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a product to a new index among the collection's products.\n\n**Required scope:** `write_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"collection_id","in":"path","required":true,"description":"Collection ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string"}}],"responses":{"204":{"description":"product repositioned"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"new_position":{"type":"integer","description":"0-based index among the collection's products"}},"required":["new_position"]}}}}}},"/api/v3/admin/collection_rules/types":{"get":{"summary":"List available collection rule types","tags":["Collections"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Enumerates the registered rule kinds with their labels and descriptions — drives the rule picker on an automatic collection. Plugins extend the list by registering `Spree::CollectionRule` subclasses via `config.spree.collection_rules`. The `type` returned here is the wire shorthand accepted when writing a collection's `rules`.\n\n**Required scope:** `read_collections` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"types found","content":{"application/json":{}}}}}},"/api/v3/admin/commission_lines":{"get":{"summary":"List commission lines","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What each sale actually earned the marketplace, frozen when the order\nwas placed. A later change to a commission rate never reaches these.\n\n`amount` is the fee charged to the seller and `tax_amount` is the VAT on\nthat fee — the marketplace's own service to the seller, a supply\nseparate from the sale itself, which is why the two are not folded\ntogether. `total` is their sum.\n\nOne line per commissioned item, plus one per delivery when the rate that\napplied charges shipping too — read `line_item_id` and `fulfillment_id`\nto tell them apart.\n\nRead-only: correcting a charge is a reversal, not an edit.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[seller_id_eq]","in":"query","required":false,"description":"Filter to one seller","schema":{"type":"string"}},{"name":"q[order_id_eq]","in":"query","required":false,"description":"Filter to one order","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed (e.g., `commission_rate`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission lines found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionLine"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_lines/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission line ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission line","tags":["Commission Lines"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission line found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionLine"}}}},"404":{"description":"commission line not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/commission_rates":{"get":{"summary":"List commission rates","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What the marketplace charges its sellers.\n\nRates are returned in resolution order: the list is walked top-down and\nthe first rate whose targeting matches the sale wins, so the order you\nsee is the precedence. Move a rate with `position` on update.\n\nA rate carrying no rules matches every sale — `global` says so — which\nis how a marketplace expresses a single default. Because resolution\nstops at the first match, a global rate makes everything below it\nunreachable, so it belongs at the bottom.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[enabled_eq]","in":"query","required":false,"description":"Filter by whether the rate is in use","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-position`).","schema":{"type":"string"}}],"responses":{"200":{"description":"commission rates found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRate"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets what the marketplace charges, and which sales it applies to.\n\n`rules` is the rate's whole targeting, sent inline. Every rule has to\nhold, and a rule naming several records means any of them — so\n\"(Cameras OR Audio) AND that seller\" is a category rule holding two ids\nbeside a seller rule holding one. Send no rules to charge every sale.\n\nRule kinds come from `GET /commission_rates/rule_types`, which also\ndescribes the configuration each one takes. A marketplace that adds its\nown kind sees it there without this endpoint changing.\n\n`commission_tax_rate` is VAT on the commission itself — the\nmarketplace's own service to the seller, a separate supply from the\nsale. Leave it null to let the store's tax engine answer for wherever\nthe seller's business sits.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"commission rate created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"422":{"description":"validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name","kind","value"],"properties":{"name":{"type":"string"},"code":{"type":"string","nullable":true,"description":"Your own identifier for this rate; unique per store."},"enabled":{"type":"boolean"},"position":{"type":"integer","description":"Place in the list. Rates resolve top-down, so 1 is tried first. New rates are created at the top; send this to move one."},"kind":{"type":"string","enum":["percentage","fixed"]},"value":{"type":"string","description":"A percentage (10 = 10%) or a flat amount, per `kind`."},"amounts":{"type":"object","additionalProperties":{"type":"string"},"description":"What a flat fee charges, keyed by currency. A currency with no amount is one this rate does not charge — those sales fall to the next rate. Ignored for a percentage."},"tax_inclusive":{"type":"boolean","description":"Charge on the price including the customer's VAT. Left off, commission is charged on the seller's net revenue, which is the usual basis where the fee is taxed as its own supply."},"include_shipping":{"type":"boolean","description":"Also charge commission on the seller's delivery revenue."},"bounds":{"type":"object","additionalProperties":{"type":"object","properties":{"min_amount":{"type":"string","nullable":true},"max_amount":{"type":"string","nullable":true}}},"description":"The floor and cap a percentage charges within, keyed by currency. Each holds only in its own currency; a sale in a currency with no bounds is charged unbounded."},"commission_tax_rate":{"type":"string","nullable":true,"description":"A fraction, not a percentage. Null asks the tax engine."},"rules":{"type":"array","description":"The full targeting; what you send replaces what the rate holds.","items":{"type":"object","properties":{"id":{"type":"string","description":"Present for an existing rule; omit to create one."},"type":{"type":"string","description":"A kind from /commission_rates/rule_types."},"preferences":{"type":"object","description":"Configuration for the kind, per its preference_schema."},"product_ids":{"type":"array","items":{"type":"string"},"description":"For kinds that name products, which are kept outside preferences."}}}}}}}}}}},"/api/v3/admin/commission_rates/rule_types":{"get":{"summary":"List the commission rule kinds","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every rule kind a rate can be narrowed by, with the schema describing\nthe configuration it takes — so a client builds its editor from what\nthis marketplace has rather than a list hardcoded to match core's.\n\n`association_fields` names any catalog-scale reference a kind keeps\noutside its preferences, so an editor knows to render a picker for it.\n\n\n**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"subject types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preference_schema":{"type":"array","items":{"type":"object"}},"association_fields":{"type":"array","items":{"type":"string"}}}}}}}}}}}}},"/api/v3/admin/commission_rates/{id}":{"parameters":[{"name":"id","in":"path","description":"Commission rate ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}},"404":{"description":"commission rate not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Editing a rate changes what the next sale is charged, never what a past\none was: commission lines keep their own snapshot of the rate that\napplied.\n\n\n**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"commission rate updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommissionRate"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"enabled":{"type":"boolean"},"position":{"type":"integer"},"value":{"type":"string"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"preferences":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}}}}}}}}}},"delete":{"summary":"Delete a commission rate","tags":["Commission Rates"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_commissions` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"commission rate deleted"}}}},"/api/v3/admin/companies/{company_id}/memberships":{"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 members","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the people with standing over this node. Standing covers the node and everything below it in the tree.\n\n**Required scope:** `read_customers` (for API-key authentication).","responses":{"200":{"description":"members found","content":{"application/json":{}}}}},"post":{"summary":"Add a member by email","tags":["Companies"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a person to the node by email. An email matching an existing customer becomes a\nmembership immediately (a `cmem_…` id); an unknown email becomes an invitation\n(a `cinv_…` id) and the invite email goes out.\n\n\n**Required scope:** `write_customers` (for API-key authentication).","parameters":[],"responses":{"201":{"description":"member added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string"}},"required":["customer_email"]}}}}}},"/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 company node. A root node is a legal entity; pass parent_id and kind to build the organization tree. Exemption certificates and tax registrations hang off legal-entity nodes.\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"},"kind":{"type":"string","enum":["company","division"],"description":"company = legal entity (may hold tax registrations), division = organizational unit. Roots must be company."},"parent_id":{"type":"string","nullable":true,"description":"The parent node. Omit for a root."},"external_references":{"type":"array","description":"Identities this business has in your own systems. A system you do not name keeps the reference it already has, and creating with a reference that already exists updates that business instead.","items":{"type":"object","properties":{"system":{"type":"string"},"external_id":{"type":"string"}},"required":["system","external_id"]}}},"required":["name"]}}}}}},"/api/v3/admin/custom_field_definitions/resource_types":{"get":{"summary":"List what custom fields can be attached to","tags":["Custom Field Definitions"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The resources a definition can describe, from the server's own\nregistry (`Spree.custom_fields.enabled_resources`).\n\nRead this rather than carrying a list: a resource an extension\nregisters appears here without a client release, and a `resource_type`\nthat is not listed is refused on create.\n\n`resource_type` is the value to send; `name` is what a merchant calls\nit. The two differ where a class has been renamed — categories are\nstored under `Spree::Taxon` and shown as \"Categories\" — so send the\nvalue back verbatim rather than deriving it from the name.\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"}}],"responses":{"200":{"description":"resource types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"resource_type":{"type":"string"},"name":{"type":"string"}}}}}}}}}}}},"/api/v3/admin/delivery_profiles":{"get":{"summary":"List delivery profiles","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Fulfillment profiles group products with the stock locations, delivery zones and delivery methods that fulfill them. Every store has exactly one default profile.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profiles found","content":{"application/json":{}}}}},"post":{"summary":"Create a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery profile. `kind` selects the registered profile kind (shipping, digital, extension kinds); `stock_location_ids` limits fulfillment to those locations — empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery profile created","content":{"application/json":{}}},"422":{"description":"validation error","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","description":"Registered profile kind; defaults to shipping."},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}},"required":["name"]}}}}}},"/api/v3/admin/delivery_profiles/{delivery_profile_id}/origin_groups":{"parameters":[{"name":"delivery_profile_id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Create an origin group","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Origin groups partition a profile's fulfillment origins: zones and methods belong to a group, so the same products can quote different rate tables per warehouse. `stock_location_ids` replaces the full membership; empty means every store location.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"origin group created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","nullable":true},"position":{"type":"integer","nullable":true},"stock_location_ids":{"type":"array","items":{"type":"string"},"description":"Empty means every store location."}}}}}}}},"/api/v3/admin/delivery_profiles/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery profile updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"default":{"type":"boolean"},"stock_location_ids":{"type":"array","items":{"type":"string"}}}}}}}},"delete":{"summary":"Delete a delivery profile","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The default profile and profiles still referenced by products cannot be deleted.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"delivery profile deleted"}}}},"/api/v3/admin/delivery_methods":{"get":{"summary":"List delivery methods","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns all delivery methods with calculator and zone configuration.\n\n**Required scope:** `read_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"delivery methods found","content":{"application/json":{}}}}},"post":{"summary":"Create delivery method","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery method inside a delivery profile (defaults to the store default profile). Delivery behavior comes from the fulfillment provider.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"delivery method created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"admin_name":{"type":"string","nullable":true},"code":{"type":"string","nullable":true},"fulfillment_provider":{"type":"string","nullable":true},"delivery_profile_id":{"type":"string","nullable":true},"storefront_visible":{"type":"boolean"},"tracking_url":{"type":"string","nullable":true},"estimated_transit_business_days_min":{"type":"integer","nullable":true},"estimated_transit_business_days_max":{"type":"integer","nullable":true},"tax_category_id":{"type":"string","nullable":true},"calculator_type":{"type":"string"},"calculator_preferences":{"type":"object"},"delivery_zone_id":{"type":"string","nullable":true}},"required":["name"]}}}}}},"/api/v3/admin/delivery_methods/calculators":{"get":{"summary":"List delivery calculators","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Registered delivery calculator classes with preference schemas for building configuration forms.\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"calculators found","content":{"application/json":{}}}}}},"/api/v3/admin/delivery_zones":{"post":{"summary":"Create delivery zone","tags":["Delivery"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Creates a delivery zone with typed members: country, state, or postal_code (prefix or from/to range).\n\n**Required scope:** `write_settings` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed, e.g. `members`","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery zone created","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"members":{"type":"array","items":{"type":"object","properties":{"member_type":{"type":"string","enum":["country","state","postal_code"]},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"postal_code_prefix":{"type":"string","nullable":true},"postal_code_from":{"type":"string","nullable":true},"postal_code_to":{"type":"string","nullable":true}},"required":["member_type"]}}},"required":["name"]}}}}}},"/api/v3/admin/integrations":{"get":{"summary":"List integrations","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the integrations connected to the current store. Secret preference values are masked.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integrations found","content":{"application/json":{}}}}},"post":{"summary":"Connect integration","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Connects an integration type to the current store. Setting active: true verifies the connection and fails with 422 when it cannot connect. Submitting a masked secret value back keeps the stored secret.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"integration connected","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"Wire shorthand from GET /integrations/types"},"active":{"type":"boolean"},"preferences":{"type":"object"}},"required":["type"]}}}}}},"/api/v3/admin/integrations/types":{"get":{"summary":"List integration types","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every registered integration type with its gallery metadata and configuration schema. Pure registry discovery — read live connection state from GET /integrations.\n\n**Required scope:** `read_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"integration types found","content":{"application/json":{}}}}}},"/api/v3/admin/integrations/{id}/test":{"post":{"summary":"Test integration connection","tags":["Integrations"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Runs a live connection check against the provider. Nothing is persisted; a failed check reports the seller error message.\n\n**Required scope:** `write_integrations` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"connection checked","content":{"application/json":{}}}}}},"/api/v3/admin/media":{"get":{"summary":"List media","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns every file in the store's media library, whether or not it has\nbeen placed on a product. Filter with `q[unattached]=true` for files not\nyet in use, `q[media_type_eq]` for images or video, and\n`q[filename_cont]` to search by file name.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"media found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Upload a file to the library","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a file to the library without placing it on anything. Upload the\nfile first through the direct-upload endpoint, then send the signed id\nhere. Put the file on a product by posting to that product's media with\nthis record's id as `source_media_id`.\n\n\n**Required scope:** `write_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"file added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"signed_id":{"type":"string","description":"Direct-upload signed id for the file."},"alt":{"type":"string"},"media_type":{"type":"string","enum":["image","video","external_video"]},"external_video_url":{"type":"string","description":"YouTube or Vimeo link, for an external video."}}}}}}}},"/api/v3/admin/media/{id}/usage":{"parameters":[{"name":"id","in":"path","description":"Media ID","required":true,"schema":{"type":"string"}}],"get":{"summary":"Where a file is used","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lists everywhere this file appears: products it is placed on, image\nfields that picked it, and descriptions embedding it. Reusing a file\nshares it rather than copying it, so deleting one placement can leave\nothers pointing at the same file — check this first.\n\nDescription matches are best-effort: an embedded image is a plain URL\nwith nothing recording it, so treat an empty result as \"nothing found\",\nnot proof the file is unused.\n\n\n**Required scope:** `read_media` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"usage found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["media","attachment","rich_text"]},"name":{"type":"string","nullable":true},"owner_type":{"type":"string"},"owner_id":{"type":"string","nullable":true},"field":{"type":"string","nullable":true}}}}}}}}}}}},"/api/v3/admin/products/{product_id}/media":{"parameters":[{"name":"product_id","in":"path","description":"Product ID","required":true,"schema":{"type":"string"}}],"post":{"summary":"Place a library file on a product","tags":["Media"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Puts a file that is already in the library onto this product. The new\nrecord shares the source's file rather than copying it, so nothing is\nuploaded and no image is reprocessed; it carries its own alt text,\nposition and variant links from here on.\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":"file placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Media"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_media_id":{"type":"string","description":"A media record already in the library."},"alt":{"type":"string"},"position":{"type":"integer"}},"required":["source_media_id"]}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries":{"get":{"summary":"List deliveries","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The consignments of a parcel — one per tracking number, each with the carrier status last reported.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Record a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a tracked consignment to a parcel — a second box, or a freight PRO number covering several pallets. The carrier is free text.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"delivery recorded","content":{"application/json":{}}},"422":{"description":"tracking number already recorded on this parcel","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["tracking_number"],"properties":{"tracking_number":{"type":"string","description":"Carrier tracking number, freight PRO number, or a full tracking link"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service"},"tracking_url":{"type":"string","description":"Tracking page for this consignment"}}}}},"required":true}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}":{"patch":{"summary":"Correct a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Corrects the tracking number, carrier or link. A corrected number starts the carrier journey over.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery updated","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking_number":{"type":"string"},"carrier":{"type":"string"},"service":{"type":"string"},"tracking_url":{"type":"string"}}}}},"required":true}},"delete":{"summary":"Delete a delivery","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a hand-entered consignment. One a label minted is refused — refund the label instead.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"204":{"description":"delivery deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/deliveries/{id}/mark_delivered":{"patch":{"summary":"Mark a delivery delivered","tags":["Deliveries"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Staff confirming one consignment arrived. The parcel becomes delivered once every one of its consignments has.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Delivery ID","schema":{"type":"string"}}],"responses":{"200":{"description":"delivery marked delivered","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"delivered_at":{"type":"string","format":"date-time","description":"When it arrived. Defaults to now."},"notify_customer":{"type":"boolean","description":"Whether the customer gets a delivery notification when the parcel completes."}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels":{"get":{"summary":"List shipping labels","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Every label bought or uploaded for a parcel, refunded ones included.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"200":{"description":"labels found","content":{"application/json":{}}}}},"post":{"summary":"Buy or record a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"With no body, buys the label through the parcel's carrier account. With a `file`, records a label bought elsewhere. Either way the tracking number becomes a delivery on the parcel.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}}],"responses":{"201":{"description":"label purchased","content":{"application/json":{}}},"422":{"description":"provider does not produce labels","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"Signed blob id of an uploaded label file; its presence records rather than buys"},"tracking_number":{"type":"string","description":"Number printed on an uploaded label"},"carrier":{"type":"string","description":"Free-text carrier; detected from the number when omitted"},"service":{"type":"string","description":"Carrier service the label was bought at"},"cost":{"type":"string","description":"What the merchant paid the carrier"},"currency":{"type":"string","description":"Currency of the cost"},"file_format":{"type":"string","enum":["pdf","png","zpl"],"description":"Label file format; taken from the file when omitted"},"tracking_url":{"type":"string","description":"Tracking page for the consignment"}}}}}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}":{"get":{"summary":"Get a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One label, with what it cost and where to print it from.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"label found","content":{"application/json":{}}}}},"delete":{"summary":"Delete an uploaded label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes an uploaded label. A purchased label is refunded instead, so the postage history stays honest.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"204":{"description":"label deleted"}}}},"/api/v3/admin/orders/{order_id}/fulfillments/{fulfillment_id}/labels/{id}/refund":{"patch":{"summary":"Refund a shipping label","tags":["Shipping Labels"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Asks the carrier to refund a purchased label. The consignment it minted is removed when the parcel never shipped.\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":"fulfillment_id","in":"path","required":true,"description":"Fulfillment ID","schema":{"type":"string"}},{"name":"id","in":"path","required":true,"description":"Shipping label ID","schema":{"type":"string"}}],"responses":{"200":{"description":"refund filed","content":{"application/json":{}}},"422":{"description":"uploaded labels cannot be refunded","content":{"application/json":{}}}}}},"/api/v3/admin/package_types":{"get":{"summary":"List package types","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the store's packaging vocabulary: the box it ships parcels in\nand the cartons, pallets and containers a wholesale order leaves on.\n\n`volume` is the cubic meters the package occupies, converted from\nwhatever unit its dimensions were recorded in — the figure freight\nvolume rules compare against. It is null until all three sides are\nmeasured.\n\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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[kind_eq]","in":"query","required":false,"description":"Filter by kind (`box`, `envelope`, `carton`, `pallet`, `container`)","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":"package types found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PackageType"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a kind of packaging to the store.\n\n`weight` is the empty package's own weight, added to content weight on\nevery quote; `max_weight` is what it can hold. Setting `default` makes\nthis the box every parcel quote is built on, and demotes whichever row\nheld that before.\n\nA variant references a `carton`-kind row to say what it is packed\ninto; other kinds are the merchant's own vocabulary.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}},"required":["name","kind"]}}}}}},"/api/v3/admin/package_types/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Package type ID","schema":{"type":"string"}}],"get":{"summary":"Get a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single package type by prefixed ID.\n\n**Required scope:** `read_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}},"404":{"description":"package type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates a package type. Every product packed in it follows the new geometry.\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PackageType"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight":{"type":"number"},"max_weight":{"type":"number"},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"default":{"type":"boolean"}}}}}}},"delete":{"summary":"Delete a package type","tags":["Package Types"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes a kind of packaging. Refused while any variant is packed into\nit — repack those products first.\n\n\n**Required scope:** `write_package_types` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"package type deleted"}}}},"/api/v3/admin/price_lists/{price_list_id}/products":{"get":{"summary":"List price list products","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The products the list prices, listed by name — membership is derived from the price rows.\n`expand=price_list_price` adds what the list charges for each variant, with its quantity\nbreaks as tiers, the same reading a catalog's products carry.\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":"price_list_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated. `price_list_price` adds the resolved price to every row.","schema":{"type":"string"}}],"responses":{"200":{"description":"products found, with what the list charges","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListProduct"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}},"post":{"summary":"Add products to a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds products to the list in bulk, materializing a placeholder price per variant and store currency. Already-present products are skipped.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"products added","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}},"delete":{"summary":"Remove products from a price list","tags":["Price Lists"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Removes products from the list in bulk, hard-deleting their price rows. Ids that are not members are ignored.\n\n**Required scope:** `write_products` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"price_list_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"products removed","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"product_ids":{"type":"array","items":{"type":"string"}}},"required":["product_ids"]}}}}}},"/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/purchase_orders":{"get":{"summary":"List purchase orders","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock bought from suppliers. A purchase order carries what a purchase\nhas and a stock transfer does not: a supplier, a unit cost per line and\nan expected arrival date.\n\nOrdered units never count toward availability. Nothing here changes\n`count_on_hand` until `receive` runs, because a merchant who has\nordered stock does not have it.\n\nStatuses are `draft`, `ordered`, `partially_received`, `received`, `over_received` and\n`canceled`. Each move between them is its own endpoint, not a `PATCH`\nthat writes `status`.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[supplier_id_eq]` or `q[expected_at_lteq]`. Expand `items`,\n`supplier` and `destination_location`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ordered', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase orders found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrder"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts an order. Nothing is on order and nothing touches availability\nuntil the order is marked as ordered and then received.\n\n`currency` defaults to the store's; set it for a foreign-currency\norder. `expected_at` is a calendar date (`yyyy-mm-dd`) — the day the\nsupplier promised means the same day in every timezone.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"purchase order created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"supplier belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"supplier_id":{"type":"string"},"destination_location_id":{"type":"string"},"currency":{"type":"string","nullable":true},"expected_at":{"type":"string","format":"date","nullable":true},"reference":{"type":"string","nullable":true,"description":"The supplier's own order number"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_ordered":{"type":"integer"},"unit_cost":{"type":"string"}},"required":["variant_id","quantity_ordered"]}},"metadata":{"type":"object","nullable":true}},"required":["supplier_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/purchase_orders/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"Get a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, supplier, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"purchase order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}},"404":{"description":"purchase order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_ordered":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Place the order with the supplier","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Moves a `draft` to `ordered`: the lines are frozen and `ordered_at` is\nstamped. Availability is still untouched — ordered stock is not stock\nthe merchant has.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"purchase order placed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{purchase_order_id}/stock_receipts":{"parameters":[{"name":"purchase_order_id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries booked against an order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the dock counted in, newest first — with its packing-slip reference and what it accepted and refused.\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Book in a delivery","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment purchased goods first count toward availability. Records\none delivery as a stock receipt: what this delivery brought, per line,\nnot a running total — a second delivery adds to the first.\n\n`quantity_accepted` reaches the shelf; `quantity_rejected` is refused\nand recorded with a `rejection_reason` (`damaged`, `wrong_item`,\n`expired` or `other`), never stocked. Omit `items` to book in\neverything still outstanding, intact.\n\nEach `received` stock movement carries the line's `unit_cost` and\nnames the receipt, so a delivery can be reconciled against the ledger.\n\nThe order stays `partially_received` while any line is still owed,\nsettles in `received` once every line has what it expected, and in\n`over_received` once any line has more.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"delivery booked in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"order has not been placed yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true,"description":"The supplier's delivery note or packing slip"},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/purchase_orders/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Take an order back to draft","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Reopens a placed order for editing. Only while no delivery has been booked against it; `ordered_at` is cleared.\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"order back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}}}},"/api/v3/admin/purchase_orders/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Close an order short","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received order whose balance the supplier will not\ndeliver. Nothing moves: what arrived stays on the shelf, the\noutstanding count stays on each line, and the order settles in\n`received` with `closed_short_at` and the `reason` recorded.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"order closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/purchase_orders/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Purchase order ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a purchase order","tags":["Purchase Orders"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Closes what is still outstanding. Nothing is unwound: a purchase order\nnever moved stock until units were received, and units already received\nstay on the shelf because the merchant has them.\n\nA `reason` is appended to the order's notes.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"purchase order cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseOrder"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/seller_requirements":{"get":{"summary":"List seller requirements","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"What this marketplace asks of a seller before it will let them trade,\nin the order sellers work through it.\n\nEach row is one configured requirement. `required` says whether it\nstands between the seller and approval — the others are shown as\nrecommended and counted in their progress, but never block. `active`\nswitches one off without losing how it was worded.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"seller requirements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerRequirement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"summary":"Add a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds something the marketplace asks of its sellers.\n\n`type` comes from `GET /seller_requirements/types`, which also\ndescribes the configuration each kind takes. Most kinds answer one\nquestion and can be added once; the open-ended ones — a seller\nconfirmation, a manual check, a document — carry the question in your\nown `name` and `description`, so a store may add as many as it needs.\n\nA kind that reads the seller's own data (their addresses, their\nproducts, whether they accepted the terms) needs nothing from the\nseller beyond doing it. The others wait for the seller to submit\nsomething, and the ones you review wait for you.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller requirement created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}},"422":{"description":"kind is not registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"The kind, from `GET /seller_requirements/types`."},"name":{"type":"string","description":"What the seller sees. Required for kinds that can be added more than once, since the wording is the only thing telling them apart. Left blank on the others, the kind names itself."},"description":{"type":"string","description":"Instructions shown to the seller."},"required":{"type":"boolean","description":"Whether this blocks approval. Off means recommended."},"active":{"type":"boolean"},"position":{"type":"integer","description":"Place in the checklist."},"preferences":{"type":"object","description":"Configuration for this kind, per its `preference_schema`."}}}}}}}},"/api/v3/admin/seller_requirements/types":{"get":{"summary":"List seller requirement kinds","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The kinds you can add, and the shape of each one's configuration form.\n\n`configured` says the store already has this kind — meaningful only\nwhere `allow_multiple` is false. `accepts_submissions` says the seller\nrecords having done it rather than it being read from their data, and\n`reviewed_by_operator` says what they send waits for you.\n\nA marketplace that registers its own kind server-side sees it here\nwithout this endpoint changing.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"kinds found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"},"configured":{"type":"boolean"},"addable":{"type":"boolean","description":"Whether the operator may add one now. The uniqueness rule is the server's, so clients filter on this rather than deriving it."},"preference_schema":{"type":"array","items":{"type":"object"}}}}}}}}}}}}},"/api/v3/admin/seller_requirements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"summary":"Update a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Changes how a requirement is worded, what it asks for, where it sits in\nthe checklist, and whether it blocks approval.\n\n`type` is not accepted: a saved row's kind never changes, because\nanything a seller already submitted answered the old one.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller requirement updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRequirement"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"required":{"type":"boolean"},"active":{"type":"boolean"},"position":{"type":"integer"},"preferences":{"type":"object"}}}}}}},"delete":{"summary":"Delete a seller requirement","tags":["Seller Requirements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops asking for this. Anything sellers already submitted against it\ngoes too — to keep the record while pausing the ask, set `active` to\nfalse instead.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller requirement deleted"}}}},"/api/v3/admin/sellers":{"get":{"summary":"List sellers","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the sellers on this marketplace. `status` says where each one\nis in its life on the marketplace, and `sellable` answers the question\nthe status alone cannot: an approved seller who is away cannot be\nbought from either.\n\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"description":"Bearer token for admin authentication","schema":{"type":"string"}},{"name":"page","in":"query","required":false,"description":"Page number","schema":{"type":"integer"}},{"name":"limit","in":"query","required":false,"description":"Number of records per page","schema":{"type":"integer"}},{"name":"q[name_cont]","in":"query","required":false,"description":"Filter by name (contains)","schema":{"type":"string"}},{"name":"q[status_eq]","in":"query","required":false,"description":"Filter by status","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"Sort by field. Prefix with `-` for descending (e.g., `-created_at`).","schema":{"type":"string"}}],"responses":{"200":{"description":"sellers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Opens a seller record. The seller starts as `pending` and has no team\nyet — invite someone to run it with the `invite` action below.\n\n`status` is deliberately not writable here or on update: every move\nthrough the lifecycle is its own action, because each one does more\nthan set a column.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"slug":{"type":"string","description":"Derived from the name when omitted."},"contact_email":{"type":"string","nullable":true},"billing_email":{"type":"string","nullable":true},"about":{"type":"string","nullable":true},"tax_remittance":{"type":"string","enum":["seller","platform"]},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"Get a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single seller, including its settlement and tax configuration.\n\n**Required scope:** `read_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Updates the seller's profile and the settlement configuration the\noperator owns. A `status` sent here is ignored — use the lifecycle\nactions.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller address written inline","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"billing_email":{"type":"string","nullable":true},"payouts_schedule_interval":{"type":"string","enum":["daily","weekly","biweekly","monthly","manual"],"nullable":true},"minimum_payout_amount":{"type":"string","nullable":true},"holiday_mode_until":{"type":"string","format":"date-time","nullable":true},"logo":{"type":"string","nullable":true,"description":"ActiveStorage signed id of a direct-uploaded file. Send `null` to remove the attachment, or omit the key to leave it alone. Same for `square_logo` and `cover_photo`."},"square_logo":{"type":"string","nullable":true},"cover_photo":{"type":"string","nullable":true},"billing_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}},"returns_address":{"type":"object","description":"The seller's own address, written inline. There is no `billing_address_id` — an address belongs to whoever it was created for, so it is never referenced by id here.","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"phone":{"type":"string"},"country_code":{"type":"string"},"state_code":{"type":"string"},"state_name":{"type":"string"},"label":{"type":"string"}}}}}}}}},"delete":{"summary":"Delete a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the seller. Their products are kept and left without a\nseller rather than deleted — what happens to a departed seller's\ncatalog is the operator's decision.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"seller deleted"}}}},"/api/v3/admin/sellers/{id}/invite":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Invite someone to run a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sends an invitation to the seller's own team and moves the seller to\n`invited`. The person becomes a member when they accept, and can then\nsign in to the seller panel.\n\n`role_id` must name a role this seller owns; omit it for the seller's\nown admin role. Re-inviting is allowed — an invitation expires, or the\nfirst one goes to the wrong address.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"invitation sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role_id":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/sellers/{id}/approve":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Approve a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Lets the seller sell. This is also the way back for one that was\nsuspended or turned down, and it clears any holiday along with the\nsuspension.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}},"422":{"description":"seller cannot be approved from its current status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{id}/suspend":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Suspend a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stops a trading seller from selling. Their catalog and history stay,\nand approving reinstates them. Use this rather than `reject` for a\nseller already on the marketplace — it says something different, and\nit can be undone.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{id}/reject":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Reject a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Turns down an applicant who never traded. A seller already selling is\nsuspended instead; rejecting one is refused.\n\n\n**Required scope:** `write_sellers` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"seller rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Seller"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}}}},"/api/v3/admin/sellers/{seller_id}/balances":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"get":{"summary":"List a seller's balances","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Where one seller stands with the marketplace, one row per currency:\nwhat they have earned (completed transfers, refund reversals\nincluded), what has been paid to them, what is still owed, and\nearnings the payout provider has not yet confirmed.\n\nComputed from the ledger rather than stored, so the rows carry no id.\n\n\n**Required scope:** `read_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"balances listed","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerBalance"}}},"required":["data"]}}}},"404":{"description":"seller not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/sellers/{seller_id}/payouts":{"parameters":[{"name":"seller_id","in":"path","required":true,"description":"Seller prefixed ID","schema":{"type":"string"}}],"post":{"summary":"Settle a seller","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sweeps everything this seller is owed into a payout — one per currency,\nsince nothing is ever converted between them.\n\nThis is what the `manual` payout interval means: the scheduled sweep\nruns on each seller's own interval and skips anyone set to `manual`,\nleaving the operator to decide when. It also settles any other seller\nearly.\n\nIt records the settlement rather than sending money: the built-in\nprovider waits to be told the bank transfer went out, which is\n`PATCH /api/v3/admin/seller_payouts/{id}/complete`.\n\nAnswers `422` when there is nothing to settle — no payout account,\nnothing unsettled, or a balance below the seller's minimum.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"201":{"description":"seller settled","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SellerPayout"}}},"required":["data"]}}}},"422":{"description":"nothing to settle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/seller_payouts/{id}/complete":{"parameters":[{"name":"id","in":"path","required":true,"description":"Seller payout prefixed ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a payout paid","tags":["Sellers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records that the money reached the seller, which is what debits their\nbalance — a balance is earnings less *completed* settlements.\n\nThis is the step the built-in provider waits for: it files the\nsettlement when the payout is created and expects an operator to say\nthe bank transfer went out. A connected provider marks its own payouts\npaid when its webhook reports the money landed.\n\nSend the provider's own id for the transfer as `reference` when there\nis one. Completing a payout that is already complete answers `200`\nwithout recording it twice, so a redelivered webhook or a double click\nis safe.\n\n\n**Required scope:** `write_payouts` (for API-key authentication).","parameters":[{"name":"x-spree-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"payout completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPayout"}}}},"404":{"description":"payout not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","description":"The provider's own id for the settlement, when one made it"}}}}}}}},"/api/v3/admin/stock_levels":{"get":{"summary":"List stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"One row per variant per stock location, carrying every figure the\nInventory page shows: `count_on_hand` (on hand), `allocated_count`\n(committed to placed orders), `reserved_count` (held by checkouts in\nprogress), `available_count` (on hand minus committed) and\n`incoming_count` (on its way on an open purchase order or a transfer\nin transit). The variant and location are named flat on the row\n(`variant_name`, `variant_sku`, `stock_location_name`, `thumbnail_url`)\nso a list needs no expansion.\n\nFilter with `q[stock_location_id_eq]`, `q[variant_id_eq]` or\n`q[variant_sku_or_variant_product_name_cont]`.\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,"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[stock_location_id_eq]","in":"query","required":false,"description":"Only levels at this stock location","schema":{"type":"string"}},{"name":"q[variant_id_eq]","in":"query","required":false,"description":"Only levels for this variant","schema":{"type":"string"}},{"name":"q[variant_sku_or_variant_product_name_cont]","in":"query","required":false,"description":"Only levels whose variant SKU or product name contains this text","schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}}}}},"/api/v3/admin/stock_levels/bulk_upsert":{"post":{"summary":"Bulk-upsert stock levels","tags":["Stock"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Sets stock levels for many (variant, location) pairs at once — what a\nwarehouse or ERP feed posts on a schedule.\n\nEach row names its variant and stock location by Spree id\n(`variant_id`, `stock_location_id`).\n\nA row carries either `count_on_hand` — the absolute level the external\nsystem reports — or `adjustment`, a relative change for feeds that\nreport movements instead. Every change is written as a stock movement,\nso a merchant can still see why a figure moved.\n\nThe response carries `stock_level_count`: how many rows moved a shelf.\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,"schema":{"type":"string"}}],"responses":{"200":{"description":"stock levels updated","content":{"application/json":{}}},"422":{"description":"row is missing a level","content":{"application/json":{}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["stock_levels"],"properties":{"stock_levels":{"type":"array","items":{"type":"object","required":["variant_id","stock_location_id"],"properties":{"variant_id":{"type":"string"},"stock_location_id":{"type":"string"},"count_on_hand":{"type":"integer","nullable":true},"adjustment":{"type":"integer","nullable":true},"backorderable":{"type":"boolean","nullable":true}}}}}}}}}}},"/api/v3/admin/stock_movements":{"get":{"summary":"List stock movements","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns the stock ledger, newest first. Every row says what happened to\nstock (`kind`) and carries a direct reference to what caused it, so a\nmerchant can answer \"why is this number what it is?\" from the data.\n\nKinds are `received` (goods arrived), `allocated` (stock promised to a\nplaced order), `shipped` (promised stock left), `released` (a promise\nwithdrawn) and `adjusted` (a manual correction, which always carries a\n`reason`).\n\nMovements are immutable — reversing one means writing its counterpart\nthrough the resource that caused it, which is why there is no create,\nupdate or delete here.\n\nFilter with Ransack predicates such as `q[kind_eq]`,\n`q[stock_level_id_eq]`, `q[order_id_eq]`, `q[fulfillment_id_eq]` or\n`q[created_at_gteq]`.\n\n`kind` is null on rows written before Spree 6.0 until\n`spree:migrate_stock_movements_to_typed_rows` has run.\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[kind_eq]","in":"query","required":false,"description":"Filter by kind ('received', 'allocated', 'shipped', 'released', 'adjusted')","schema":{"type":"string"}},{"name":"q[stock_level_id_eq]","in":"query","required":false,"description":"Filter by stock level, e.g. sl_1234567890","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 movements found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_movements/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock movement ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock movement","tags":["Stock Movements"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Returns a single stock movement 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 movement found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockMovement"}}}},"404":{"description":"stock movement not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v3/admin/stock_transfers":{"get":{"summary":"List stock transfers","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Stock moving between two of the merchant's own warehouses.\n\nA transfer is a trip, not an instant. Units leave the source when the\ntransfer is marked in transit and land at the destination when somebody\ncounts them in — in between they are in flight, gone from one shelf and\nnot yet on the other.\n\nStatuses are `draft`, `ready_to_ship`, `in_transit`,\n`partially_received`, `received`, `over_received` and `canceled`. Each move between them\nis its own endpoint, not a `PATCH` that writes `status`.\n\nReceiving from a supplier is a purchase order, not a transfer with a\nmissing source.\n\nFilter with Ransack predicates such as `q[status_eq]`,\n`q[source_location_id_eq]` or `q[number_or_reference_cont]`. Expand\n`items`, `source_location` and `destination_location`.\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[status_eq]","in":"query","required":false,"description":"Filter by status ('draft', 'ready_to_ship', 'in_transit', 'partially_received', 'received', 'over_received', 'canceled')","schema":{"type":"string"}},{"name":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockTransfer"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Persists a draft — a packing list the merchant can still edit. Nothing\nmoves until the transfer is marked in transit.\n\nA draft may legitimately open empty and gain lines as the merchant\npacks. Both warehouses are required and must belong to the same store.\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 transfer created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"warehouse belongs to another store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"reference":{"type":"string","nullable":true,"description":"The merchant's own label for the trip"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":"string"},"quantity_shipped":{"type":"integer"}},"required":["variant_id","quantity_shipped"]}},"metadata":{"type":"object","nullable":true}},"required":["source_location_id","destination_location_id"]}}},"required":true}}},"/api/v3/admin/stock_transfers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"Get a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**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":"expand","in":"query","required":false,"description":"Comma-separated associations to embed: items, source_location, destination_location","schema":{"type":"string"}}],"responses":{"200":{"description":"stock transfer found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"404":{"description":"stock transfer not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"summary":"Delete a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Drafts only. Past `draft` the transfer describes a box that physically\nexists, so it is cancelled rather than deleted — a 422 says so.\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 transfer deleted"}}}},"/api/v3/admin/stock_transfers/{id}/mark_ready":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Mark a transfer ready to ship","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Freezes the lines so the warehouse and the merchant are looking at the\nsame list. Nothing leaves the shelf yet.\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":"transfer is ready to ship","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_in_transit":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Send a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"The moment stock leaves the source warehouse: `shipped` movements are\nwritten against the source's levels and `shipped_at` is stamped. The\ndestination is deliberately untouched — the units are in flight.\n\nRefused with a 422 when the source does not hold enough. Pass\n`force: true` to record the departure anyway: a merchant forcing it has\ndecided the box left whatever the ledger claims.\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":"transfer is in transit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"force":{"type":"boolean","description":"Ship even if it drives the source below zero"}}}}}}}},"/api/v3/admin/stock_transfers/{stock_transfer_id}/stock_receipts":{"parameters":[{"name":"stock_transfer_id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"get":{"summary":"List the deliveries counted in against a transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Each delivery the destination counted in, with what it accepted and refused.\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"}}],"responses":{"200":{"description":"deliveries found","content":{"application/json":{}}}}},"post":{"summary":"Count a delivery in","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Records one delivery the destination warehouse counted in, as a stock\nreceipt. Partial receipt is the normal case: ten left, eight arrived,\ntwo were crushed in transit. Quantities are this delivery's counts —\na second box adds to the first rather than restating it.\n\n`quantity_accepted` lands on the destination's shelf;\n`quantity_rejected` is refused and recorded with a `rejection_reason`\n(`damaged`, `wrong_item`, `expired` or `other`), never stocked. A\nrefused unit still arrived, so it counts toward the trip being over.\nOmit `items` to count in everything still outstanding, intact.\n\nThe transfer stays `partially_received` while units are still on the\nroad, settles in `received` once everything has arrived, and in\n`over_received` once more arrived than was shipped.\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":"delivery counted in","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockReceipt"}}}},"422":{"description":"transfer has not shipped yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","nullable":true},"received_at":{"type":"string","format":"date-time","nullable":true,"description":"Defaults to now"},"notes":{"type":"string","nullable":true},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"integer"},"quantity_rejected":{"type":"integer"},"rejection_reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}},"required":["id"]}}}}}}}}},"/api/v3/admin/stock_transfers/{id}/mark_draft":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Take a transfer back to draft","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Unfreezes a ready-to-ship transfer so its lines can be changed. Nothing has left the source, so nothing is undone.\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":"transfer back in draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}}}},"/api/v3/admin/stock_transfers/{id}/close":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Close a transfer short","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Ends a partially received transfer whose missing units are not going\nto turn up. Nothing moves — they already left the source — and the\ntransfer settles in `received` with `closed_short_at` and the\n`reason` recorded, the outstanding count left on each line.\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":"transfer closed short","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","nullable":true}}}}}}}},"/api/v3/admin/stock_transfers/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Stock transfer ID","schema":{"type":"string"}}],"patch":{"summary":"Cancel a stock transfer","tags":["Stock Transfers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Calls the trip off.\n\nCancelling a draft or a packed transfer costs nothing — no stock has\nmoved. Cancelling one already in transit needs `on_in_transit`, because\nthe units are physically gone from the source: either they come back\n(`restock`, as if the transfer had never shipped) or they are written\noff as lost (`write_off`). There is no default — guessing would either\ninvent stock or destroy it — so an in-flight cancellation without it is\nrefused with a 422.\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":"transfer cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StockTransfer"}}}},"422":{"description":"in-transit cancellation needs a decision","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"on_in_transit":{"type":"string","enum":["restock","write_off"],"description":"Required once the units have left the source"},"reason":{"type":"string","nullable":true,"description":"Recorded against the written-off lines"}}}}}}}},"/api/v3/admin/suppliers":{"get":{"summary":"List suppliers","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Who the merchant buys stock from. A supplier is an address-book entry\nwith a purchasing history — not a party that sells on the store, which\nis a seller.\n\nSuppliers belong to one store, and are soft-deleted so the purchase\norders that name them stay readable.\n\nFilter with Ransack predicates such as\n`q[name_or_contact_name_or_email_cont]` or `q[country_code_eq]`.\n\n\n**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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_or_contact_name_or_email_cont]","in":"query","required":false,"description":"Search by name, contact name or email","schema":{"type":"string"}}],"responses":{"200":{"description":"suppliers found","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}},"required":["data","meta"]}}}},"401":{"description":"unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"summary":"Create a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Adds a supplier to this store's address book. The address is inline —\nstreet, city, state and country live on the supplier itself, the same\nshape a stock location uses.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"422":{"description":"validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true}},"required":["name"]}}},"required":true}}},"/api/v3/admin/suppliers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Supplier ID","schema":{"type":"string"}}],"get":{"summary":"Get a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `read_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"404":{"description":"supplier not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"patch":{"summary":"Update a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true}}}}},"required":true}},"delete":{"summary":"Delete a supplier","tags":["Suppliers"],"security":[{"api_key":[],"bearer_auth":[]}],"description":"Soft-deletes the supplier, so the purchase orders naming it stay\nreadable. Refused with a 422 while a purchase order still points at it.\n\n\n**Required scope:** `write_purchasing` (for API-key authentication).","parameters":[{"name":"x-spree-api-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":"supplier deleted"}}}}},"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"]},"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"]},"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"]},"Actor":{"type":"object","properties":{"id":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"label":{"type":"string","nullable":true}},"required":["id","type","label"],"x-typelizer":true},"Address":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string","nullable":true},"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},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"customer_id":{"type":"string","nullable":true},"owner_id":{"type":"string","nullable":true},"owner_type":{"type":"string","nullable":true}},"required":["id","label","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","metadata","created_at","updated_at","latitude","longitude","customer_id","owner_id","owner_type"],"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","enum":["publishable","secret"]},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by_label":{"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","created_by_type","created_by_label"],"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},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_number_required":{"type":"boolean"},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"token":{"type":"string"},"email":{"type":"string","nullable":true},"customer_note":{"type":"string","nullable":true},"po_number":{"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"}},"order_minimum":{"type":"number","nullable":true},"order_minimum_shortfall":{"type":"number","nullable":true},"below_order_minimum":{"type":"boolean","nullable":true},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true},"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","company_id","company_name","po_number_required","po_document_filename","po_document_byte_size","number","token","email","customer_note","po_number","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","order_minimum","order_minimum_shortfall","below_order_minimum","freight_summary","shipping_eq_billing_address","items","billing_address","shipping_address","market","completed_at","created_at","updated_at","applied_promotions"],"x-typelizer":true},"CatalogAssignment":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"catalog_id":{"type":"string"},"assignable_type":{"type":"string"},"assignable_id":{"type":"string"},"assignable_name":{"type":"string","nullable":true}},"required":["id","created_at","catalog_id","assignable_type","assignable_id","assignable_name"],"x-typelizer":true},"CatalogOrderMinimum":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"}},"required":["id","currency","created_at","updated_at","amount","display_amount"],"x-typelizer":true},"CatalogPrice":{"type":"object","properties":{"id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"currency":{"type":"string"},"source":{"type":"string","enum":["explicit","automatic","base"]},"break_count":{"type":"number"},"amount":{"type":"string"},"display_amount":{"type":"string"},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPriceTier"}}},"required":["id","label","sku","currency","source","break_count","amount","display_amount","tiers"],"x-typelizer":true},"CatalogPriceTier":{"type":"object","properties":{"min_quantity":{"type":"number"},"display_amount":{"type":"string"},"amount":{"type":"string"}},"required":["min_quantity","display_amount","amount"],"x-typelizer":true},"CatalogProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"quantity_rule":{"allOf":[{"$ref":"#/components/schemas/CatalogProductTerm"}],"nullable":true},"catalog_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"CatalogProductTerm":{"type":"object","properties":{"id":{"type":"string"},"product_id":{"type":"string"},"product_name":{"type":"string","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"mixed":{"type":"boolean"}},"required":["id","product_id","product_name","minimum_order_quantity","order_multiple","mixed"],"x-typelizer":true},"CatalogQuantityRule":{"type":"object","properties":{"id":{"type":"string"},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"variant_id":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"product_name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","minimum_order_quantity","order_multiple","created_at","updated_at","variant_id","variant_sku","product_name","options_text"],"x-typelizer":true},"Catalog":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"active":{"type":"boolean"},"position":{"type":"number","nullable":true},"metadata":{"type":"object","nullable":true},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products_count":{"type":"number"},"pricing_strategy":{"type":"string"},"order_minimums":{"type":"array","items":{"$ref":"#/components/schemas/CatalogOrderMinimum"}},"price_list":{"$ref":"#/components/schemas/PriceList"},"assignments":{"type":"array","items":{"$ref":"#/components/schemas/CatalogAssignment"}}},"required":["id","name","description","active","position","metadata","minimum_order_quantity","order_multiple","created_at","updated_at","products_count","pricing_strategy"],"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"}},"external_references":{"type":"object"},"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","external_references","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"}},"default_catalog_id":{"type":"string","nullable":true}},"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","default_catalog_id"],"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":{"anyOf":[{"type":"string","enum":["open","approved","resolved","denied","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"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","created_by_type"],"x-typelizer":true},"CollectionRule":{"type":"object","properties":{"id":{"type":"string"},"value":{"type":"string","nullable":true},"match_policy":{"type":"string","enum":["is_equal_to","is_not_equal_to","contains","does_not_contain"]},"type":{"type":"string","description":"Rule type. Built-in: tag, available_on, sale. Extensions may register more."}},"required":["id","value","match_policy","type"],"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","enum":["all","any"]},"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","enum":["percentage","fixed"]},"currency":{"type":"string"},"taxability_reason":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"rate":{"type":"string"},"tax_rate":{"type":"string"},"amount":{"type":"string"},"tax_amount":{"type":"string"},"total":{"type":"string"},"display_amount":{"type":"string"},"display_tax_amount":{"type":"string"},"display_total":{"type":"string"},"order_id":{"type":"string"},"seller_id":{"type":"string"},"line_item_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"commission_rate_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"commission_rate":{"$ref":"#/components/schemas/CommissionRate"}},"required":["id","kind","currency","taxability_reason","country_code","state_code","created_at","updated_at","rate","tax_rate","amount","tax_amount","total","display_amount","display_tax_amount","display_total","order_id","seller_id","line_item_id","fulfillment_id","commission_rate_id","seller_name"],"x-typelizer":true},"CommissionRate":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"code":{"type":"string","nullable":true},"enabled":{"type":"boolean"},"position":{"type":"number"},"kind":{"type":"string","enum":["percentage","fixed"]},"tax_inclusive":{"type":"boolean"},"include_shipping":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"value":{"type":"string"},"commission_tax_rate":{"type":"string","nullable":true},"amounts":{"type":"object"},"bounds":{"type":"object"},"global":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/CommissionRule"}}},"required":["id","name","code","enabled","position","kind","tax_inclusive","include_shipping","metadata","deleted_at","created_at","updated_at","value","commission_tax_rate","amounts","bounds","global","rules"],"x-typelizer":true},"CommissionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: seller_rule, category_rule, product_rule, item_total_rule. Extensions may register more."},"commission_rate_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"object","nullable":true},"seller_ids":{"type":"object","nullable":true},"category_ids":{"type":"object","nullable":true},"sellers":{"type":"array","items":{"$ref":"#/components/schemas/Seller"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["id","created_at","updated_at","type","commission_rate_id","preferences","preference_schema","product_ids","seller_ids","category_ids"],"x-typelizer":true},"CompanyInvitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"expires_at":{"type":"string","nullable":true},"company_id":{"type":"string"},"status":{"type":"string","enum":["pending","accepted","revoked","expired"]},"accepted_at":{"type":"string","nullable":true},"revoked_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","email","expires_at","company_id","status","accepted_at","revoked_at","created_at","updated_at"],"x-typelizer":true},"CompanyMembership":{"type":"object","properties":{"id":{"type":"string"},"company_id":{"type":"string"},"customer_id":{"type":"string"},"email":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","company_id","customer_id","email","created_at","updated_at"],"x-typelizer":true},"Company":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["company","division"]},"po_number_required":{"type":"boolean"},"parent_id":{"type":"string","nullable":true},"ancestors":{"type":"object"},"external_references":{"type":"object"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"children_count":{"type":"number"},"members_count":{"type":"number"},"children":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/CompanyMembership"}}},"required":["id","name","kind","po_number_required","parent_id","ancestors","external_references","metadata","created_at","updated_at","children_count","members_count"],"x-typelizer":true},"ConsentRecord":{"type":"object","properties":{"id":{"type":"string"},"purpose":{"type":"string"},"source":{"type":"string","enum":["checkout","registration","account","admin","newsletter","anonymization","unknown","import","storefront"]},"accepted":{"type":"boolean"},"email":{"type":"string","nullable":true},"ip_address":{"type":"string","nullable":true},"created_at":{"type":"string"},"recorded_at":{"type":"string","nullable":true},"documents":{"type":"object"}},"required":["id","purpose","source","accepted","email","ip_address","created_at","recorded_at","documents"],"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","description":"Class name of the resource the field attaches to, for example Spree::Product, Spree::Order or Spree::Customer. Extensions may register more."},"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"},"email_marketing_consent_updated_at":{"type":"string","nullable":true},"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"},"email_marketing_consent_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"anonymized_at":{"type":"string","nullable":true},"anonymized":{"type":"boolean"},"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"}},"companies":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["id","email","first_name","last_name","phone","accepts_email_marketing","email_marketing_consent_updated_at","full_name","available_store_credit_total","display_available_store_credit_total","failed_attempts","metadata","email_marketing_consent_source","created_at","updated_at","anonymized_at","anonymized","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},"DashboardCounter":{"type":"object","properties":{"key":{"type":"string","description":"Registered counter name. The dashboard translates it; built-in: orders_to_fulfill, payments_to_collect, open_returns, open_exchanges, open_claims, low_stock_items, out_of_stock_items."},"value":{"type":"number"},"link":{"type":"object","nullable":true,"description":"The list filter that shows exactly the rows counted, or null when no list can."},"nav":{"type":"string","nullable":true,"description":"Sidebar entry key this count badges, or null."}},"required":["key","value","link","nav"],"x-typelizer":true},"DataRequest":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"kind":{"type":"string","enum":["access","erasure"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"requested_at":{"type":"string","nullable":true},"completed_at":{"type":"string","nullable":true},"expires_at":{"type":"string","nullable":true},"email":{"type":"string"},"error_message":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"customer_id":{"type":"string","nullable":true},"requested_by_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"}},"required":["id","number","kind","status","requested_at","completed_at","expires_at","email","error_message","created_at","updated_at","customer_id","requested_by_id"],"x-typelizer":true},"DeliveryMethodRule":{"type":"object","properties":{"id":{"type":"string"},"active":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: item_total_rule, weight_rule, excluded_products_rule, channel_rule, volume_rule, company_rule. Extensions may register more."},"preferences":{"type":"object"},"preference_schema":{"type":"object"},"product_ids":{"type":"array","items":{"type":"string"}}},"required":["id","active","created_at","updated_at","type","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},"available_to_sellers":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"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","available_to_sellers","created_at","updated_at","deleted_at","seller_id","seller_name","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","description":"Profile kind. Built-in: shipping, digital. Extensions may register more."},"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},"unpriced":{"type":"boolean"},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"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","unpriced","freight_summary","display_cost","display_total","display_additional_tax_total","display_included_tax_total","display_tax_total","metadata","created_at","updated_at"],"x-typelizer":true},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"tracking_number":{"type":"string"},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","pre_transit","in_transit","out_for_delivery","available_for_pickup","delivered","return_to_sender","failure","unknown"]},"tracking_url":{"type":"string","nullable":true},"estimated_delivery_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"details":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"shipping_label_id":{"type":"string","nullable":true}},"required":["id","tracking_number","carrier","carrier_name","service","status","tracking_url","estimated_delivery_at","delivered_at","details","created_at","updated_at","shipping_label_id"],"x-typelizer":true},"DeliveryZoneMember":{"type":"object","properties":{"id":{"type":"string"},"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},"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},"DigitalAsset":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string","nullable":true},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"authorized_clicks":{"type":"number","nullable":true},"authorized_days":{"type":"number","nullable":true},"byte_size":{"type":"number","nullable":true},"provider_type":{"type":"string","nullable":true},"provider_settings":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"provider_name":{"type":"string","description":"Digital asset provider name. Built-in: File. Extensions may register more."},"download_url":{"type":"string","nullable":true},"effective_authorized_clicks":{"type":"number"},"effective_authorized_days":{"type":"number"}},"required":["id","variant_id","filename","content_type","authorized_clicks","authorized_days","byte_size","provider_type","provider_settings","created_at","updated_at","provider_name","download_url","effective_authorized_clicks","effective_authorized_days"],"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"},"expires_at":{"type":"string","nullable":true},"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","expires_at","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","enum":["promotion","manual"]},"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":{"anyOf":[{"type":"string","enum":["requested","approved","received","fulfilled","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"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","created_by_type"],"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"},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"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","store_id","seller_id","seller_name","filename","byte_size","download_url"],"x-typelizer":true},"Fee":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"kind":{"anyOf":[{"type":"string","enum":["surcharge","handling","gift_wrap","cod","payment","duty"]},{"type":"string"}],"description":"What sort of charge this is. `duty` is a customs duty on a cross-border order and is not taxed; the other kinds are. Extensions may register further kinds."},"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},"FreightSummaryLine":{"type":"object","properties":{"variant_id":{"type":"string","nullable":true},"sku":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"units":{"type":"number"},"cartons":{"type":"number","nullable":true},"pallets":{"type":"number","nullable":true},"units_per_carton":{"type":"number","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"complete":{"type":"boolean"},"weight_per_carton":{"type":"string","nullable":true},"volume":{"type":"string"},"weight":{"type":"string"}},"required":["variant_id","sku","name","units","cartons","pallets","units_per_carton","cartons_per_pallet","complete","weight_per_carton","volume","weight"],"x-typelizer":true},"FreightSummary":{"type":"object","properties":{"total_units":{"type":"number"},"total_cartons":{"type":"number"},"total_pallets":{"type":"number","nullable":true},"total_volume":{"type":"string"},"total_weight":{"type":"string"},"complete":{"type":"boolean"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/FreightSummaryLine"}}},"required":["total_units","total_cartons","total_pallets","total_volume","total_weight","complete","lines"],"x-typelizer":true},"FulfillmentItem":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"status":{"anyOf":[{"type":"string","enum":["on_hand","backordered","shipped","returned"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"variant_id":{"type":"string","nullable":true},"line_item_id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true}},"required":["id","quantity","status","variant_id","line_item_id","name","options_text"],"x-typelizer":true},"Fulfillment":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"tracking":{"type":"string","nullable":true},"tracking_url":{"type":"string","nullable":true},"pickup_point_data":{"type":"object","nullable":true},"selected_delivery_rate_id":{"type":"string","nullable":true},"unpriced":{"type":"boolean"},"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":{"anyOf":[{"type":"string","enum":["unfulfilled","fulfilled","delivered","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"fulfillment_type":{"type":"string","enum":["shipping","digital","pickup","pickup_point"]},"fulfilled_at":{"type":"string","nullable":true},"delivered_at":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentManifestItem"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"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"},"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"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"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","pickup_point_data","selected_delivery_rate_id","unpriced","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","delivered_at","items","deliveries","metadata","adjustment_total","pre_tax_amount","created_at","updated_at","order_id","stock_location_id","documents","labels","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":{"anyOf":[{"type":"string","enum":["active","partially_redeemed","redeemed","canceled","expired"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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,"description":"Import type. Built-in: products, product_translations, customers, price_list_prices. Extensions may register more."},"status":{"anyOf":[{"type":"string","enum":["pending","mapping","completed_mapping","processing","completed","failed"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"store_id":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"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"},"price_list_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"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","store_id","seller_id","owner_type","owner_id","user_id","processing_errors","preferred_delimiter","price_list_id","seller_name","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","description":"Integration type, registered by the provider gem that owns it (for example the EasyPost provider). Core ships none."},"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},"InvitationAcceptanceLink":{"type":"object","properties":{"id":{"type":"string"},"acceptance_url":{"type":"string"}},"required":["id","acceptance_url"],"x-typelizer":true},"Invitation":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expires_at":{"type":"string"},"role_id":{"type":"string"},"role_name":{"type":"string"},"inviter_email":{"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","invitee_exists","store"],"x-typelizer":true},"LineItem":{"type":"object","properties":{"id":{"type":"string"},"variant_id":{"type":"string"},"seller_id":{"type":"string","nullable":true},"preorder":{"type":"boolean"},"preorder_ships_at":{"type":"string","nullable":true},"quantity":{"type":"number"},"currency":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"options_text":{"type":"string"},"price":{"type":"string"},"display_price":{"type":"string"},"total":{"type":"string"},"display_total":{"type":"string"},"adjustment_total":{"type":"string"},"display_adjustment_total":{"type":"string"},"additional_tax_total":{"type":"string"},"display_additional_tax_total":{"type":"string"},"included_tax_total":{"type":"string"},"display_included_tax_total":{"type":"string"},"discount_total":{"type":"string"},"display_discount_total":{"type":"string"},"pre_tax_amount":{"type":"string"},"display_pre_tax_amount":{"type":"string"},"discounted_amount":{"type":"string"},"display_discounted_amount":{"type":"string"},"display_compare_at_amount":{"type":"string","nullable":true},"compare_at_amount":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"digital_links":{"type":"array","items":{"$ref":"#/components/schemas/DigitalLink"}},"tax_lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxLine"}},"metadata":{"type":"object"},"price_source":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"catalog_price":{"type":"string","nullable":true},"price_list_id":{"type":"string","nullable":true},"price_list_name":{"type":"string","nullable":true},"catalog_id":{"type":"string","nullable":true},"catalog_name":{"type":"string","nullable":true},"cost_price":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"variant":{"$ref":"#/components/schemas/Variant"},"tax_category":{"$ref":"#/components/schemas/TaxCategory"}},"required":["id","variant_id","seller_id","preorder","preorder_ships_at","quantity","currency","name","slug","options_text","price","display_price","total","display_total","adjustment_total","display_adjustment_total","additional_tax_total","display_additional_tax_total","included_tax_total","display_included_tax_total","discount_total","display_discount_total","pre_tax_amount","display_pre_tax_amount","discounted_amount","display_discounted_amount","display_compare_at_amount","compare_at_amount","thumbnail_url","option_values","digital_links","metadata","price_source","created_at","updated_at","catalog_price","price_list_id","price_list_name","catalog_id","catalog_name","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"}},"country_isos":{"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","country_isos","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","enum":["image","video","external_video"]},"focal_point_x":{"type":"number","nullable":true},"focal_point_y":{"type":"number","nullable":true},"external_video_url":{"type":"string","nullable":true},"video_provider":{"type":"string","nullable":true},"video_embed_url":{"type":"string","nullable":true},"video_url":{"type":"string","nullable":true},"poster_url":{"type":"string","nullable":true},"original_url":{"type":"string","nullable":true},"mini_url":{"type":"string","nullable":true},"small_url":{"type":"string","nullable":true},"medium_url":{"type":"string","nullable":true},"large_url":{"type":"string","nullable":true},"xlarge_url":{"type":"string","nullable":true},"og_image_url":{"type":"string","nullable":true},"external_references":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"attached":{"type":"boolean"},"filename":{"type":"string","nullable":true},"content_type":{"type":"string","nullable":true},"byte_size":{"type":"number","nullable":true},"embed_url":{"type":"string","nullable":true},"signed_id":{"type":"string","nullable":true},"viewable_id":{"type":"string","nullable":true},"download_url":{"type":"string","nullable":true},"metadata":{"type":"object"},"viewable_type":{"type":"string","nullable":true}},"required":["id","product_id","variant_ids","position","alt","media_type","focal_point_x","focal_point_y","external_video_url","video_provider","video_embed_url","video_url","poster_url","original_url","mini_url","small_url","medium_url","large_url","xlarge_url","og_image_url","external_references","created_at","updated_at","attached","filename","content_type","byte_size","embed_url","signed_id","viewable_id","download_url","metadata","viewable_type"],"x-typelizer":true},"MembershipProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","name","thumbnail_url"],"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","enum":["dropdown","color_swatch","buttons"]},"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},"OrderCancellationReason":{"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},"OrderGroup":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"email":{"type":"string","nullable":true},"currency":{"type":"string"},"total":{"type":"string","nullable":true},"display_total":{"type":"string","nullable":true},"item_total":{"type":"string","nullable":true},"display_item_total":{"type":"string","nullable":true},"fulfillment_status":{"type":"string","nullable":true,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"completed_at":{"type":"string","nullable":true},"billing_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipping_address":{"allOf":[{"$ref":"#/components/schemas/Address"}],"nullable":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"customer_id":{"type":"string","nullable":true},"cart_id":{"type":"string","nullable":true},"seller_count":{"type":"number"},"includes_first_party":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"payments":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}},"required":["id","number","email","currency","total","display_total","item_total","display_item_total","fulfillment_status","payment_status","completed_at","billing_address","shipping_address","orders","customer_id","cart_id","seller_count","includes_first_party","created_at","updated_at","payments"],"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","description":"Rule type. Built-in: preferred_location, default_location, minimize_splits. Extensions may register more."},"channel_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"object"}},"required":["id","position","active","created_at","updated_at","type","channel_id","preferences","preference_schema"],"x-typelizer":true},"Order":{"type":"object","properties":{"id":{"type":"string"},"market_id":{"type":"string","nullable":true},"withdrawal_period_ends_at":{"type":"string","nullable":true},"within_withdrawal_period":{"type":"boolean"},"cart_id":{"type":"string","nullable":true},"channel_id":{"type":"string","nullable":true},"company_id":{"type":"string","nullable":true},"company_name":{"type":"string","nullable":true},"po_document_filename":{"type":"string","nullable":true},"po_document_byte_size":{"type":"number","nullable":true},"number":{"type":"string"},"email":{"type":"string"},"customer_note":{"type":"string","nullable":true},"po_number":{"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,"enum":["backorder","canceled","partial","unfulfilled","fulfilled","delivered","pending","ready","shipped"]},"payment_status":{"type":"string","nullable":true,"enum":["none","authorized","partially_paid","paid","partially_refunded","refunded","overcharged","voided"]},"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},"external_references":{"type":"object"},"status":{"type":"string","enum":["draft","placed","canceled"]},"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"},"cancel_note":{"type":"string","nullable":true},"commission_amount_total":{"type":"string"},"display_commission_amount_total":{"type":"string"},"commission_tax_total":{"type":"string"},"display_commission_tax_total":{"type":"string"},"commission_total":{"type":"string"},"display_commission_total":{"type":"string"},"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},"po_document_url":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"order_group_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},"approver_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"approver":{"$ref":"#/components/schemas/Actor"},"canceler_id":{"type":"string","nullable":true},"canceler_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"canceler":{"$ref":"#/components/schemas/Actor"},"created_by_id":{"type":"string","nullable":true},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"cancel_reason_id":{"type":"string","nullable":true},"cancel_reason_name":{"type":"string","nullable":true},"customer_id":{"type":"string","nullable":true},"applied_promotions":{"type":"array","items":{"$ref":"#/components/schemas/AppliedPromotion"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}},"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"},"cancel_reason":{"$ref":"#/components/schemas/OrderCancellationReason"},"returns":{"type":"array","items":{"$ref":"#/components/schemas/Return"}},"exchanges":{"type":"array","items":{"$ref":"#/components/schemas/Exchange"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"freight_summary":{"allOf":[{"$ref":"#/components/schemas/FreightSummary"}],"nullable":true}},"required":["id","market_id","withdrawal_period_ends_at","within_withdrawal_period","cart_id","channel_id","company_id","company_name","po_document_filename","po_document_byte_size","number","email","customer_note","po_number","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","external_references","status","last_ip_address","considered_risky","confirmation_delivered","store_owner_notification_delivered","payment_total","display_payment_total","metadata","cancel_note","commission_amount_total","display_commission_amount_total","commission_tax_total","display_commission_tax_total","commission_total","display_commission_total","canceled_at","approved_at","created_at","updated_at","preferred_stock_location_id","po_document_url","seller_id","order_group_id","tags","internal_note","internal_note_html","approver_id","approver_type","canceler_id","canceler_type","created_by_id","created_by_type","cancel_reason_id","cancel_reason_name","customer_id","freight_summary"],"x-typelizer":true},"PackageType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["box","envelope","carton","pallet","container"]},"length":{"type":"string","nullable":true},"width":{"type":"string","nullable":true},"height":{"type":"string","nullable":true},"weight":{"type":"string","nullable":true},"max_weight":{"type":"string","nullable":true},"default":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"volume":{"type":"string","nullable":true},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true}},"required":["id","name","kind","length","width","height","weight","max_weight","default","metadata","created_at","updated_at","dimensions_unit","weight_unit","volume","seller_id","seller_name"],"x-typelizer":true},"PaymentMethod":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","description":"Payment method type. Built-in: check, store_credit, custom_payment_source_method, bogus (test only); payment provider gems register their own, for example stripe."},"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"},"status":{"anyOf":[{"type":"string","enum":["checkout","processing","pending","completed","failed","void","invalid"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"amount":{"type":"string"},"display_amount":{"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"}},"payment_splits":{"type":"array","items":{"$ref":"#/components/schemas/PaymentSplit"}}},"required":["id","payment_method_id","response_code","number","status","amount","display_amount","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},"PaymentSplit":{"type":"object","properties":{"id":{"type":"string"},"currency":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"authorized_amount":{"type":"string"},"display_authorized_amount":{"type":"string"},"captured_amount":{"type":"string"},"display_captured_amount":{"type":"string"},"refunded_amount":{"type":"string"},"display_refunded_amount":{"type":"string"},"claimed_amount":{"type":"string"},"display_claimed_amount":{"type":"string"},"net_captured_amount":{"type":"string"},"display_net_captured_amount":{"type":"string"},"refundable_amount":{"type":"string"},"display_refundable_amount":{"type":"string"},"payment_id":{"type":"string"},"payment_number":{"type":"string","nullable":true},"order_id":{"type":"string"},"order_number":{"type":"string","nullable":true}},"required":["id","currency","created_at","updated_at","authorized_amount","display_authorized_amount","captured_amount","display_captured_amount","refunded_amount","display_refunded_amount","claimed_amount","display_claimed_amount","net_captured_amount","display_net_captured_amount","refundable_amount","display_refundable_amount","payment_id","payment_number","order_id","order_number"],"x-typelizer":true},"Permission":{"type":"object","properties":{"key":{"type":"string"},"resource":{"type":"string"},"kind":{"type":"string","enum":["read","write"]},"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},"Policy":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"body":{"type":"string","nullable":true},"body_html":{"type":"string","nullable":true},"updated_at":{"type":"string"},"created_at":{"type":"string"}},"required":["id","name","slug","body","body_html","updated_at","created_at"],"x-typelizer":true},"PriceAdjustmentTier":{"type":"object","properties":{"id":{"type":"string"},"min_quantity":{"type":"number"},"percentage":{"type":"string"}},"required":["id","min_quantity","percentage"],"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},"PriceListProduct":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"thumbnail_url":{"type":"string","nullable":true},"price_list_variants":{"type":"array","items":{"$ref":"#/components/schemas/CatalogPrice"}}},"required":["id","name","thumbnail_url"],"x-typelizer":true},"PriceList":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["draft","active","inactive","scheduled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"position":{"type":"number"},"match_policy":{"type":"string","enum":["all","any"]},"adjust_compare_at":{"type":"boolean"},"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"},"price_adjustment_percentage":{"type":"string","nullable":true},"automatic_pricing":{"type":"boolean"},"currently_active":{"type":"boolean"},"products_count":{"type":"number"},"prices_count":{"type":"number"},"price_adjustment_tiers":{"type":"array","items":{"$ref":"#/components/schemas/PriceAdjustmentTier"}},"price_rules":{"type":"array","items":{"$ref":"#/components/schemas/PriceRule"}}},"required":["id","name","description","status","position","match_policy","adjust_compare_at","starts_at","ends_at","deleted_at","created_at","updated_at","price_adjustment_percentage","automatic_pricing","currently_active","products_count","prices_count","price_adjustment_tiers"],"x-typelizer":true},"PriceRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: channel_rule, customer_group_rule, market_rule, user_rule, volume_rule, zone_rule. Extensions may register more."},"price_list_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"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"],"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},"min_quantity":{"type":"number"},"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","min_quantity","variant_id","created_at","updated_at"],"x-typelizer":true},"ProductPublication":{"type":"object","properties":{"id":{"type":"string"},"published_at":{"type":"string","nullable":true},"unpublished_at":{"type":"string","nullable":true},"product_id":{"type":"string"},"channel_id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","published_at","unpublished_at","product_id","channel_id","created_at","updated_at"],"x-typelizer":true},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"meta_title":{"type":"string","nullable":true},"meta_description":{"type":"string","nullable":true},"meta_keywords":{"type":"string","nullable":true},"variant_count":{"type":"number"},"available_on":{"type":"string","nullable":true},"preorder_ships_at":{"type":"string","nullable":true},"purchasable":{"type":"boolean"},"preorder":{"type":"boolean"},"in_stock":{"type":"boolean"},"backorderable":{"type":"boolean"},"available":{"type":"boolean"},"description":{"type":"string","nullable":true},"description_html":{"type":"string","nullable":true},"default_variant_id":{"type":"string"},"buy_box_variant_id":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"tags":{"type":"array","items":{"type":"string"}},"price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"default_variant":{"$ref":"#/components/schemas/Variant"},"option_types":{"type":"array","items":{"$ref":"#/components/schemas/OptionType"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"translations":{"type":"object"},"status":{"anyOf":[{"type":"string","enum":["draft","active","archived","proposed","rejected"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"metadata":{"type":"object"},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"submission":{"allOf":[{"$ref":"#/components/schemas/ProductSubmission"}],"nullable":true},"seller_name":{"type":"string","nullable":true},"product_type_id":{"type":"string","nullable":true},"tax_category_id":{"type":"string","nullable":true},"digital_assets":{"type":"array","items":{"$ref":"#/components/schemas/DigitalAsset"}},"collections":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"product_publications":{"type":"array","items":{"$ref":"#/components/schemas/ProductPublication"}},"channels":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}},"product_type":{"$ref":"#/components/schemas/ProductType"}},"required":["id","name","slug","meta_title","meta_description","meta_keywords","variant_count","available_on","preorder_ships_at","purchasable","preorder","in_stock","backorderable","available","description","description_html","default_variant_id","buy_box_variant_id","thumbnail_url","tags","price","original_price","seller_id","external_references","status","metadata","deleted_at","created_at","updated_at","delivery_profile_id","seller_name","product_type_id","tax_category_id"],"x-typelizer":true},"ProductSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","approved","rejected","withdrawn"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"review_note":{"type":"string","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"product_id":{"type":"string"},"metadata":{"type":"object","nullable":true},"updated_at":{"type":"string"},"submitted_by_id":{"type":"string","nullable":true},"reviewed_by_id":{"type":"string","nullable":true},"reviewed_by_name":{"type":"string","nullable":true},"auto_approved":{"type":"boolean"}},"required":["id","status","review_note","reviewed_at","created_at","product_id","metadata","updated_at","submitted_by_id","reviewed_by_id","reviewed_by_name","auto_approved"],"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","description":"Action type. Built-in: create_adjustment, create_item_adjustments, create_line_items, free_shipping. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"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","calculator","line_items"],"x-typelizer":true},"PromotionRule":{"type":"object","properties":{"id":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"type":{"type":"string","description":"Rule type. Built-in: currency, country, channel, market, item_total, product, customer, customer_group, first_order, customer_logged_in, one_use_per_user, category, option_value. Extensions may register more."},"promotion_id":{"type":"string"},"preferences":{"type":"object"},"preference_schema":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceField"}},"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},"option_value_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"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}}},"required":["id","created_at","updated_at","type","promotion_id","preferences","preference_schema","product_ids","category_ids","customer_ids","option_value_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},"PurchaseOrderItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_ordered":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"currency":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"unit_cost":{"type":"string"},"total_cost":{"type":"string"},"display_unit_cost":{"type":"string"},"display_total_cost":{"type":"string"},"purchase_order_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_ordered","quantity_received","quantity_rejected","quantity_over","outstanding","currency","created_at","updated_at","unit_cost","total_cost","display_unit_cost","display_total_cost","purchase_order_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"PurchaseOrder":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"status":{"type":"string"},"currency":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"ordered_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"expected_at":{"type":"string","nullable":true},"cancel_by":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_ordered_total":{"type":"number"},"editable":{"type":"boolean"},"subtotal":{"type":"string"},"display_subtotal":{"type":"string"},"supplier_id":{"type":"string","nullable":true},"destination_location_id":{"type":"string","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseOrderItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"supplier":{"$ref":"#/components/schemas/Supplier"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","status","currency","reference","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","ordered_at","received_at","closed_short_at","created_at","updated_at","expected_at","cancel_by","closed_short","quantity_ordered_total","editable","subtotal","display_subtotal","supplier_id","destination_location_id"],"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"},"refunder_id":{"type":"string","nullable":true},"refunder_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"refunder":{"$ref":"#/components/schemas/Actor"},"payment":{"$ref":"#/components/schemas/Payment"}},"required":["id","transaction_id","amount","payment_id","refund_reason_id","originator_id","originator_type","metadata","created_at","updated_at","refunder_id","refunder_type"],"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":{"anyOf":[{"type":"string","enum":["requested","approved","received","refunded","canceled"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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},"created_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"created_by":{"$ref":"#/components/schemas/Actor"},"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"}},"documents":{"type":"object"},"labels":{"type":"array","items":{"$ref":"#/components/schemas/ShippingLabel"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}},"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","created_by_type","refunded_total","refundable_total","documents","labels","deliveries"],"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},"SavedReport":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"query":{"type":"object"},"seeded":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"user_id":{"type":"string","nullable":true},"author_name":{"type":"string","nullable":true}},"required":["id","name","description","query","seeded","created_at","updated_at","user_id","author_name"],"x-typelizer":true},"SellerBalance":{"type":"object","properties":{"currency":{"type":"string"},"settlement_currency":{"type":"string"},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"earned":{"type":"string"},"display_earned":{"type":"string"},"payable":{"type":"string"},"display_payable":{"type":"string"},"paid":{"type":"string"},"display_paid":{"type":"string"},"balance":{"type":"string"},"display_balance":{"type":"string"},"pending":{"type":"string"},"display_pending":{"type":"string"}},"required":["currency","settlement_currency","converted","seller_id","earned","display_earned","payable","display_payable","paid","display_paid","balance","display_balance","pending","display_pending"],"x-typelizer":true},"SellerPayout":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"provider":{"type":"string","description":"Payout provider class name. Built-in: Spree::PayoutProvider::System. Provider gems register more."},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"period_start":{"type":"string","nullable":true},"period_end":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"seller_id":{"type":"string"},"seller_name":{"type":"string","nullable":true},"transfers_count":{"type":"number"}},"required":["id","status","currency","provider","reference","metadata","period_start","period_end","created_at","updated_at","amount","display_amount","seller_id","seller_name","transfers_count"],"x-typelizer":true},"SellerRequirement":{"type":"object","properties":{"id":{"type":"string"},"position":{"type":"number"},"active":{"type":"boolean"},"required":{"type":"boolean"},"metadata":{"type":"object","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"preferences":{"type":"object"},"custom_field_definition_ids":{"type":"array","items":{"type":"string"}},"allow_multiple":{"type":"boolean"},"accepts_submissions":{"type":"boolean"},"reviewed_by_operator":{"type":"boolean"}},"required":["id","position","active","required","metadata","created_at","updated_at","kind","name","description","preferences","custom_field_definition_ids","allow_multiple","accepts_submissions","reviewed_by_operator"],"x-typelizer":true},"SellerRequirementStatus":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","description":"Requirement kind. Built-in: accept_terms, complete_profile, billing_address, returns_address, delivery_method, package_type, minimum_products, payout_account, required_custom_fields, policy, attestation, operator_review, document. Extensions may register more."},"name":{"type":"string"},"description":{"type":"string","nullable":true},"required":{"type":"boolean"},"position":{"type":"number"},"status":{"type":"string","enum":["complete","incomplete","pending","rejected"]},"action_url":{"type":"string","nullable":true},"blocker":{"type":"object","nullable":true},"blocking":{"type":"boolean"},"required_policy_name":{"type":"string","nullable":true},"submission":{"$ref":"#/components/schemas/SellerRequirementSubmission"},"published_policy":{"$ref":"#/components/schemas/Policy"}},"required":["id","kind","name","description","required","position","status","action_url","blocker","blocking","required_policy_name"],"x-typelizer":true},"SellerRequirementSubmission":{"type":"object","properties":{"id":{"type":"string"},"status":{"anyOf":[{"type":"string","enum":["pending","accepted","rejected","waived"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"note":{"type":"string","nullable":true},"review_note":{"type":"string","nullable":true},"reference":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"reviewed_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string"},"requirement_id":{"type":"string"},"requirement_name":{"type":"string"},"file_url":{"type":"string","nullable":true},"file_name":{"type":"string","nullable":true}},"required":["id","status","note","review_note","reference","metadata","reviewed_at","created_at","updated_at","seller_id","requirement_id","requirement_name","file_url","file_name"],"x-typelizer":true},"Seller":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"about":{"type":"string"},"about_html":{"type":"string"},"logo_url":{"type":"string","nullable":true},"square_logo_url":{"type":"string","nullable":true},"cover_photo_url":{"type":"string","nullable":true},"status":{"anyOf":[{"type":"string","enum":["pending","invited","canceled","onboarding","ready_for_review","approved","rejected","suspended"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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"},"onboarding_progress":{"type":"object"},"onboarding_complete":{"type":"boolean"},"legal_name":{"type":"string","nullable":true},"registration_number":{"type":"string","nullable":true},"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","onboarding_progress","onboarding_complete","legal_name","registration_number"],"x-typelizer":true},"SellerTeamMember":{"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},"created_at":{"type":"string"},"updated_at":{"type":"string"},"avatar_url":{"type":"string","nullable":true}},"required":["id","email","first_name","last_name","full_name","created_at","updated_at","avatar_url"],"x-typelizer":true},"SellerTransfer":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["earning","refund_reversal"]},"status":{"anyOf":[{"type":"string","enum":["pending","processing","completed","failed","unresolved"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"currency":{"type":"string"},"provider":{"type":"string","description":"Payout provider class name. Built-in: Spree::PayoutProvider::System. Provider gems register more."},"reference":{"type":"string","nullable":true},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"amount":{"type":"string"},"display_amount":{"type":"string"},"settled_amount":{"type":"string","nullable":true},"settled_currency":{"type":"string","nullable":true},"converted":{"type":"boolean"},"seller_id":{"type":"string"},"order_id":{"type":"string","nullable":true},"payout_id":{"type":"string","nullable":true},"reversed_from_id":{"type":"string","nullable":true},"refund_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true}},"required":["id","kind","status","currency","provider","reference","metadata","created_at","updated_at","amount","display_amount","settled_amount","settled_currency","converted","seller_id","order_id","payout_id","reversed_from_id","refund_id","seller_name","order_number"],"x-typelizer":true},"SetupTask":{"type":"object","properties":{"name":{"type":"string"},"done":{"type":"boolean"}},"required":["name","done"],"x-typelizer":true},"ShippingLabel":{"type":"object","properties":{"id":{"type":"string"},"source":{"type":"string","enum":["purchased","uploaded"]},"status":{"anyOf":[{"type":"string","enum":["purchased","refund_requested","refunded"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"carrier":{"type":"string","nullable":true},"carrier_name":{"type":"string","nullable":true},"service":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"currency":{"type":"string","nullable":true},"format":{"type":"string","nullable":true},"external_id":{"type":"string","nullable":true},"metadata":{"type":"object"},"refunded_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"owner_id":{"type":"string"},"owner_type":{"type":"string","enum":["Spree::Fulfillment","Spree::Return"]},"cost":{"type":"string"},"display_cost":{"type":"string"},"integration_id":{"type":"string","nullable":true},"file_pending":{"type":"boolean"},"download_url":{"type":"string","nullable":true}},"required":["id","source","status","carrier","carrier_name","service","tracking_number","currency","format","external_id","metadata","refunded_at","created_at","updated_at","owner_id","owner_type","cost","display_cost","integration_id","file_pending","download_url"],"x-typelizer":true},"State":{"type":"object","properties":{"abbr":{"type":"string"},"name":{"type":"string"}},"required":["abbr","name"],"x-typelizer":true},"StockLevel":{"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},"external_references":{"type":"object"},"metadata":{"type":"object"},"reserved_count":{"type":"number"},"incoming_count":{"type":"number"},"purchasable_count":{"type":"number"},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_location_name":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true},"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","external_references","metadata","reserved_count","incoming_count","purchasable_count","variant_name","variant_sku","created_at","updated_at","stock_location_name","product_id","options_text","thumbnail_url","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},"external_references":{"type":"object"},"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":{"anyOf":[{"type":"string","enum":["warehouse","store","fulfillment_center"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"pickup_enabled":{"type":"boolean"},"pickup_stock_policy":{"type":"string","enum":["local","any"]},"returns_enabled":{"type":"boolean"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"seller_id":{"type":"string","nullable":true},"seller_name":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"}},"required":["id","name","address1","city","zipcode","country_code","country_name","state_code","state_text","pickup_ready_in_minutes","pickup_instructions","external_references","admin_name","address2","state_name","phone","company","active","default","backorderable_default","propagate_all_variants","kind","pickup_enabled","pickup_stock_policy","returns_enabled","created_at","updated_at","seller_id","seller_name"],"x-typelizer":true},"StockMovement":{"type":"object","properties":{"id":{"type":"string"},"quantity":{"type":"number"},"kind":{"type":"string","nullable":true,"enum":["received","allocated","shipped","released","adjusted"]},"reason":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_level_id":{"type":"string","nullable":true},"stock_location_id":{"type":"string","nullable":true},"stock_location_name":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"order_id":{"type":"string","nullable":true},"fulfillment_id":{"type":"string","nullable":true},"return_id":{"type":"string","nullable":true},"exchange_id":{"type":"string","nullable":true},"stock_transfer_id":{"type":"string","nullable":true},"stock_receipt_id":{"type":"string","nullable":true},"purchase_order_id":{"type":"string","nullable":true},"order_number":{"type":"string","nullable":true},"return_number":{"type":"string","nullable":true},"exchange_number":{"type":"string","nullable":true},"stock_transfer_number":{"type":"string","nullable":true},"purchase_order_number":{"type":"string","nullable":true},"unit_cost":{"type":"string","nullable":true},"display_unit_cost":{"type":"string","nullable":true}},"required":["id","quantity","kind","reason","created_at","updated_at","stock_level_id","stock_location_id","stock_location_name","variant_id","variant_name","variant_sku","order_id","fulfillment_id","return_id","exchange_id","stock_transfer_id","stock_receipt_id","purchase_order_id","order_number","return_number","exchange_number","stock_transfer_number","purchase_order_number","unit_cost","display_unit_cost"],"x-typelizer":true},"StockReceiptItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_accepted":{"type":"number"},"quantity_rejected":{"type":"number"},"rejection_reason":{"type":"string","nullable":true,"enum":["damaged","wrong_item","expired","other"]},"notes":{"type":"string","nullable":true},"line_type":{"type":"string","enum":["purchase_order_item","stock_transfer_item"]},"line_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_accepted","quantity_rejected","rejection_reason","notes","line_type","line_id","variant_id","product_id","variant_name","variant_sku","thumbnail_url"],"x-typelizer":true},"StockReceipt":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"quantity_accepted_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"received_at":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"receivable_type":{"type":"string","enum":["purchase_order","stock_transfer"]},"receivable_id":{"type":"string"},"received_by_id":{"type":"string","nullable":true},"received_by_type":{"anyOf":[{"type":"string","enum":["admin_user","api_key"]},{"type":"string"}],"nullable":true,"description":"The values listed are the built-in ones; extensions may add more."},"received_by":{"$ref":"#/components/schemas/Actor"},"items_count":{"type":"number"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockReceiptItem"}}},"required":["id","number","reference","notes","metadata","quantity_accepted_total","quantity_rejected_total","received_at","created_at","updated_at","receivable_type","receivable_id","received_by_id","received_by_type","items_count"],"x-typelizer":true},"StockReservation":{"type":"object","properties":{"id":{"type":"string"},"stock_level_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_level_id","line_item_id","order_id","variant_id","stock_location_id","quantity","expires_at","active","created_at","updated_at"],"x-typelizer":true},"StockTransferItem":{"type":"object","properties":{"id":{"type":"string"},"quantity_shipped":{"type":"number"},"quantity_received":{"type":"number"},"quantity_rejected":{"type":"number"},"quantity_over":{"type":"number"},"outstanding":{"type":"number"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"stock_transfer_id":{"type":"string","nullable":true},"variant_id":{"type":"string","nullable":true},"product_id":{"type":"string","nullable":true},"variant_name":{"type":"string","nullable":true},"variant_sku":{"type":"string","nullable":true},"options_text":{"type":"string","nullable":true},"thumbnail_url":{"type":"string","nullable":true}},"required":["id","quantity_shipped","quantity_received","quantity_rejected","quantity_over","outstanding","created_at","updated_at","stock_transfer_id","variant_id","product_id","variant_name","variant_sku","options_text","thumbnail_url"],"x-typelizer":true},"StockTransfer":{"type":"object","properties":{"id":{"type":"string"},"number":{"type":"string"},"reference":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"source_location_id":{"type":"string"},"destination_location_id":{"type":"string"},"status":{"type":"string"},"notes":{"type":"string","nullable":true},"metadata":{"type":"object"},"close_reason":{"type":"string","nullable":true},"items_count":{"type":"number"},"quantity_received_total":{"type":"number"},"quantity_rejected_total":{"type":"number"},"shipped_at":{"type":"string","nullable":true},"received_at":{"type":"string","nullable":true},"closed_short_at":{"type":"string","nullable":true},"deleted_at":{"type":"string","nullable":true},"closed_short":{"type":"boolean"},"quantity_shipped_total":{"type":"number"},"editable":{"type":"boolean"},"items":{"type":"array","items":{"$ref":"#/components/schemas/StockTransferItem"}},"stock_receipts":{"type":"array","items":{"$ref":"#/components/schemas/StockReceipt"}},"source_location":{"$ref":"#/components/schemas/StockLocation"},"destination_location":{"$ref":"#/components/schemas/StockLocation"}},"required":["id","number","reference","created_at","updated_at","source_location_id","destination_location_id","status","notes","metadata","close_reason","items_count","quantity_received_total","quantity_rejected_total","shipped_at","received_at","closed_short_at","deleted_at","closed_short","quantity_shipped_total","editable"],"x-typelizer":true},"StoreCreditEvent":{"type":"object","properties":{"id":{"type":"string"},"action":{"type":"string"},"authorization_code":{"type":"string","nullable":true},"display_action":{"type":"string","nullable":true},"amount":{"type":"string"},"display_amount":{"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"store_credit_id":{"type":"string"},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true}},"required":["id","action","authorization_code","display_action","amount","display_amount","created_at","updated_at","store_credit_id","originator_type","originator_id"],"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"},"amount_authorized":{"type":"string"},"outstanding":{"type":"boolean"},"display_amount_authorized":{"type":"string"},"customer_id":{"type":"string","nullable":true},"created_by_id":{"type":"string","nullable":true},"originator_type":{"type":"string","nullable":true},"originator_id":{"type":"string","nullable":true},"customer":{"$ref":"#/components/schemas/Customer"},"created_by":{"$ref":"#/components/schemas/AdminUser"}},"required":["id","amount","amount_used","amount_remaining","display_amount","display_amount_used","display_amount_remaining","currency","memo","metadata","created_at","updated_at","amount_authorized","outstanding","display_amount_authorized","customer_id","created_by_id","originator_type","originator_id"],"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"},"default_country_code":{"type":"string","nullable":true},"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","enum":["g","kg","lb","oz"]},"preferred_unit_system":{"type":"string"},"preferred_storefront_access":{"type":"string"},"preferred_guest_checkout":{"type":"boolean"},"preferred_always_include_confirm_step":{"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_low_stock_threshold":{"type":"number"},"preferred_tax_using_ship_address":{"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_pricing_provider":{"type":"string"},"preferred_inventory_provider":{"type":"string"},"preferred_pricing_provider_failure_policy":{"type":"string"},"preferred_inventory_provider_failure_policy":{"type":"string"},"preferred_payout_provider":{"type":"string","nullable":true},"preferred_default_payouts_schedule_interval":{"type":"string"},"preferred_default_minimum_payout_amount":{"type":"number"},"preferred_auto_approve_sellers":{"type":"boolean"},"preferred_auto_approve_seller_products":{"type":"boolean"},"preferred_send_seller_transactional_emails":{"type":"boolean"},"preferred_default_commission_tax_rate":{"type":"number"},"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"},"preferred_limit_digital_download_count":{"type":"boolean"},"preferred_digital_asset_authorized_clicks":{"type":"number"},"preferred_limit_digital_download_days":{"type":"boolean"},"preferred_digital_asset_authorized_days":{"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","default_country_code","mail_from_address","customer_support_email","new_order_notifications_email","preferred_send_consumer_transactional_emails","preferred_admin_locale","preferred_timezone","preferred_weight_unit","preferred_unit_system","preferred_storefront_access","preferred_guest_checkout","preferred_always_include_confirm_step","preferred_company_field_enabled","preferred_address_requires_company","preferred_address_requires_phone","preferred_capture_method","preferred_track_inventory_levels","preferred_stock_reservations_enabled","preferred_low_stock_threshold","preferred_tax_using_ship_address","preferred_track_price_history","preferred_show_products_without_price","preferred_disable_sku_validation","preferred_order_routing_strategy","preferred_pricing_provider","preferred_inventory_provider","preferred_pricing_provider_failure_policy","preferred_inventory_provider_failure_policy","preferred_payout_provider","preferred_default_payouts_schedule_interval","preferred_default_minimum_payout_amount","preferred_auto_approve_sellers","preferred_auto_approve_seller_products","preferred_send_seller_transactional_emails","preferred_default_commission_tax_rate","preferred_document_number_format","preferred_order_number_prefix","preferred_order_number_suffix","preferred_order_number_sequence_start","preferred_limit_digital_download_count","preferred_digital_asset_authorized_clicks","preferred_limit_digital_download_days","preferred_digital_asset_authorized_days","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},"Supplier":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"contact_name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"address1":{"type":"string","nullable":true},"address2":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_name":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"postal_code":{"type":"string","nullable":true},"purchase_orders_count":{"type":"number"},"metadata":{"type":"object"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"deleted_at":{"type":"string","nullable":true},"can_be_deleted":{"type":"boolean"}},"required":["id","name","contact_name","email","phone","notes","address1","address2","city","state_name","state_code","country_code","postal_code","purchase_orders_count","metadata","created_at","updated_at","deleted_at","can_be_deleted"],"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":{"anyOf":[{"type":"string","enum":["pending","verified","expired","revoked"]},{"type":"string"}],"description":"The values listed are the built-in ones; extensions may add more."},"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","description":"Tax identifier kind, keyed to a registered validator. Built-in: eu_vat. Extensions may register more."},"value":{"type":"string"},"validation_status":{"type":"string","nullable":true,"enum":["pending","verified","unverified","unavailable","unsupported"]},"validation_evidence":{"type":"object","nullable":true},"source":{"type":"string","nullable":true,"enum":["override","company","customer"]},"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},"weight_unit":{"type":"string","enum":["g","kg","lb","oz"]},"dimensions_unit":{"type":"string","enum":["mm","cm","in","ft"]},"minimum_order_quantity":{"type":"number","nullable":true},"order_multiple":{"type":"number","nullable":true},"purchase_unit":{"type":"string","nullable":true,"enum":["unit","carton"]},"units_per_carton":{"type":"number","nullable":true},"price":{"$ref":"#/components/schemas/Price"},"original_price":{"allOf":[{"$ref":"#/components/schemas/Price"}],"nullable":true},"seller_id":{"type":"string","nullable":true},"seller":{"$ref":"#/components/schemas/Seller"},"primary_media":{"$ref":"#/components/schemas/Media"},"media":{"type":"array","items":{"$ref":"#/components/schemas/Media"}},"option_values":{"type":"array","items":{"$ref":"#/components/schemas/OptionValue"}},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"}},"prior_price":{"allOf":[{"$ref":"#/components/schemas/PriceHistory"}],"nullable":true},"external_references":{"type":"object"},"metadata":{"type":"object"},"position":{"type":"number"},"cost_price":{"type":"string","nullable":true},"cost_currency":{"type":"string","nullable":true},"barcode":{"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},"carton_weight":{"type":"string","nullable":true},"cartons_per_pallet":{"type":"number","nullable":true},"deleted_at":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"preorderable":{"type":"boolean"},"tax_category_id":{"type":"string","nullable":true},"carton_package_type_id":{"type":"string","nullable":true},"units_per_pallet":{"type":"number","nullable":true},"available_stock":{"type":"number","nullable":true},"reserved_quantity":{"type":"number"},"total_on_hand":{"type":"number","nullable":true},"product_name":{"type":"string"},"delivery_profile_id":{"type":"string","nullable":true},"prices":{"type":"array","items":{"$ref":"#/components/schemas/Price"}},"stock_levels":{"type":"array","items":{"$ref":"#/components/schemas/StockLevel"}}},"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","weight_unit","dimensions_unit","minimum_order_quantity","order_multiple","purchase_unit","units_per_carton","price","original_price","seller_id","option_values","external_references","metadata","position","cost_price","cost_currency","barcode","backorder_limit","hs_code","country_of_origin","customs_description","carton_weight","cartons_per_pallet","deleted_at","created_at","updated_at","preorderable","tax_category_id","carton_package_type_id","units_per_pallet","available_stock","reserved_quantity","total_on_hand","product_name","delivery_profile_id"],"x-typelizer":true},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"event_name":{"type":"string"},"event_id":{"type":"string","nullable":true},"response_code":{"type":"number","nullable":true},"execution_time":{"type":"number","nullable":true},"error_type":{"type":"string","nullable":true},"request_errors":{"type":"string","nullable":true},"response_body":{"type":"string","nullable":true},"success":{"type":"boolean","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"},"delivered_at":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true},"webhook_endpoint_id":{"type":"string"},"webhook_endpoint_url":{"type":"string"}},"required":["id","event_name","event_id","response_code","execution_time","error_type","request_errors","response_body","success","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